home | career | drupal | java | mac | mysql | perl | scala | uml | unix  

Commons IO example source code file (MagicNumberFileFilter.java)

This example Commons IO source code file (MagicNumberFileFilter.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Java - Commons IO tags/keywords

abstractfilefilter, illegalargumentexception, illegalargumentexception, io, ioexception, magicnumberfilefilter, magicnumberfilefilter, override, randomaccessfile, randomaccessfile, serializable, string, the, the, todo, util

The Commons IO MagicNumberFileFilter.java source code

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.io.filefilter;

import java.io.File;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.io.Serializable;
import java.util.Arrays;

import org.apache.commons.io.IOUtils;

/**
 * <p>
 * File filter for matching files containing a "magic number". A magic number 
 * is a unique series of bytes common to all files of a specific file format.
 * For instance, all Java class files begin with the bytes 
 * <code>0xCAFEBABE. 
 * </p>
 * 
 * <code>
 * File dir = new File(".");
 * MagicNumberFileFilter javaClassFileFilter =
 *     MagicNumberFileFilter(new byte[] {(byte) 0xCA, (byte) 0xFE, 
 *       (byte) 0xBA, (byte) 0xBE}); 
 * String[] javaClassFiles = dir.list(javaClassFileFilter);
 * for (String javaClassFile : javaClassFiles) {
 *     System.out.println(javaClassFile);
 * }
 * </pre>
 * 
 * <p>
 * Sometimes, such as in the case of TAR files, the
 * magic number will be offset by a certain number of bytes in the file. In the
 * case of TAR archive files, this offset is 257 bytes.
 * </p>
 * 
 * <code>
 * File dir = new File(".");
 * MagicNumberFileFilter tarFileFilter = 
 *     MagicNumberFileFilter("ustar", 257); 
 * String[] tarFiles = dir.list(tarFileFilter);
 * for (String tarFile : tarFiles) {
 *     System.out.println(tarFile);
 * }
 * </pre>
 * @since Commons IO 2.0
 * @see FileFilterUtils#magicNumberFileFilter(byte[])
 * @see FileFilterUtils#magicNumberFileFilter(String)
 * @see FileFilterUtils#magicNumberFileFilter(byte[], long)
 * @see FileFilterUtils#magicNumberFileFilter(String, long)
 */
public class MagicNumberFileFilter extends AbstractFileFilter implements
        Serializable {
    
    /**
     * The serialization version unique identifier.
     */
    private static final long serialVersionUID = -547733176983104172L;

    /**
     * The magic number to compare against the file's bytes at the provided 
     * offset.
     */
    private final byte[] magicNumbers;
    
    /**
     * The offset (in bytes) within the files that the magic number's bytes 
     * should appear.
     */
    private final long byteOffset;
    
    /**
     * <p>
     * Constructs a new MagicNumberFileFilter and associates it with the magic
     * number to test for in files. This constructor assumes a starting offset
     * of <code>0.
     * </p>
     * 
     * <p>
     * It is important to note that <em>the array is not cloned and that
     * any changes to the magic number array after construction will affect the
     * behavior of this file filter.
     * </p>
     * 
     * <code>
     * MagicNumberFileFilter javaClassFileFilter =
     *     MagicNumberFileFilter(new byte[] {(byte) 0xCA, (byte) 0xFE, 
     *       (byte) 0xBA, (byte) 0xBE}); 
     * </pre>
     * 
     * @param magicNumber the magic number to look for in the file.
     * 
     * @throws IllegalArgumentException if <code>magicNumber is 
     *         <code>null, or contains no bytes.
     */
    public MagicNumberFileFilter(byte[] magicNumber) {
        this(magicNumber, 0);
    }
    
    /**
     * <p>
     * Constructs a new MagicNumberFileFilter and associates it with the magic
     * number to test for in files. This constructor assumes a starting offset
     * of <code>0.
     * </p>
     * 
     * Example usage:
     * <pre>
     * {@code
     * MagicNumberFileFilter xmlFileFilter = 
     *     MagicNumberFileFilter("<?xml"); 
     * }
     * </pre>
     * 
     * @param magicNumber the magic number to look for in the file.
     *        The string is converted to bytes using the platform default charset.
     *
     * @throws IllegalArgumentException if <code>magicNumber is 
     *         <code>null or the empty String.
     */
    public MagicNumberFileFilter(String magicNumber) {
        this(magicNumber, 0);
    }
    
    /**
     * <p>
     * Constructs a new MagicNumberFileFilter and associates it with the magic
     * number to test for in files and the byte offset location in the file to
     * to look for that magic number.
     * </p>
     * 
     * <code>
     * MagicNumberFileFilter tarFileFilter = 
     *     MagicNumberFileFilter("ustar", 257); 
     * </pre>
     * 
     * @param magicNumber the magic number to look for in the file. 
     *        The string is converted to bytes using the platform default charset.
     * @param offset the byte offset in the file to start comparing bytes.
     * 
     * @throws IllegalArgumentException if <code>magicNumber is 
     *         <code>null or the empty String, or offset is 
     *         a negative number.
     */
    public MagicNumberFileFilter(String magicNumber, long offset) {
        if (magicNumber == null) {
            throw new IllegalArgumentException("The magic number cannot be null");
        }
        if (magicNumber.length() == 0) {
            throw new IllegalArgumentException("The magic number must contain at least one byte");
        }
        if (offset < 0) {
            throw new IllegalArgumentException("The offset cannot be negative");
        }
        
        this.magicNumbers = magicNumber.getBytes(); // uses the platform default charset
        this.byteOffset = offset;
    }
    
    /**
     * <p>
     * Constructs a new MagicNumberFileFilter and associates it with the magic
     * number to test for in files and the byte offset location in the file to
     * to look for that magic number.
     * </p>
     * 
     * <p>
     * It is important to note that <em>the array is not cloned and that
     * any changes to the magic number array after construction will affect the
     * behavior of this file filter.
     * </p>
     * 
     * <code>
     * MagicNumberFileFilter tarFileFilter =
     *     MagicNumberFileFilter(new byte[] {0x75, 0x73, 0x74, 0x61, 0x72}, 257); 
     * </pre>
     * 
     * <code>
     * MagicNumberFileFilter javaClassFileFilter =
     *     MagicNumberFileFilter(new byte[] {0xCA, 0xFE, 0xBA, 0xBE}, 0); 
     * </pre>
     * 
     * @param magicNumber the magic number to look for in the file.
     * @param offset the byte offset in the file to start comparing bytes.
     * 
     * @throws IllegalArgumentException if <code>magicNumber is 
     *         <code>null, or contains no bytes, or offset 
     *         is a negative number.
     */
    public MagicNumberFileFilter(byte[] magicNumber, long offset) {
        if (magicNumber == null) {
            throw new IllegalArgumentException("The magic number cannot be null");
        }
        if (magicNumber.length == 0) {
            throw new IllegalArgumentException("The magic number must contain at least one byte");
        }
        if (offset < 0) {
            throw new IllegalArgumentException("The offset cannot be negative");
        }
        
        this.magicNumbers = new byte[magicNumber.length];
        System.arraycopy(magicNumber, 0, this.magicNumbers, 0, magicNumber.length);
        this.byteOffset = offset;
    }
    
    /**
     * <p>
     * Accepts the provided file if the file contains the file filter's magic
     * number at the specified offset.
     * </p>
     * 
     * <p>
     * If any {@link IOException}s occur while reading the file, the file will
     * be rejected.
     * </p>
     * 
     * @param file the file to accept or reject.
     * 
     * @return <code>true if the file contains the filter's magic number 
     *         at the specified offset, <code>false otherwise.
     */
    @Override
    public boolean accept(File file) {
        if (file != null && file.isFile() && file.canRead()) {
            RandomAccessFile randomAccessFile = null;
            try {
                byte[] fileBytes = new byte[this.magicNumbers.length]; 
                randomAccessFile = new RandomAccessFile(file, "r");
                randomAccessFile.seek(byteOffset);
                int read = randomAccessFile.read(fileBytes);
                if (read != magicNumbers.length) {
                    return false;
                }
                return Arrays.equals(this.magicNumbers, fileBytes);
            } catch (IOException ioe) {
                // Do nothing, fall through and do not accept file
            } finally {
                IOUtils.closeQuietly(randomAccessFile);
            }
        }
        
        return false;
    }

    /**
     * Returns a String representation of the file filter, which includes the 
     * magic number bytes and byte offset.
     * 
     * @return a String representation of the file filter.
     */
    @Override
    public String toString() {
        StringBuilder builder = new StringBuilder(super.toString());
        builder.append("(");
        builder.append(new String(magicNumbers));// TODO perhaps use hex if value is not printable
        builder.append(",");
        builder.append(this.byteOffset);
        builder.append(")");
        return builder.toString();
    }
}

Other Commons IO examples (source code examples)

Here is a short list of links related to this Commons IO MagicNumberFileFilter.java source code file:



my book on functional programming

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.