MagicNumberFileFilter (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.filefilter

## Class MagicNumberFileFilter

- java.lang.Object
- - org.apache.commons.io.filefilter.AbstractFileFilter
  - - org.apache.commons.io.filefilter.MagicNumberFileFilter

- All Implemented Interfaces:
    java.io.FileFilter, java.io.FilenameFilter, java.io.Serializable, IOFileFilter

      public class MagicNumberFileFilter
      extends AbstractFileFilter
      implements java.io.Serializable

  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 `0xCAFEBABE`.

       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);
       }

  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.

       File dir = new File(".");
       MagicNumberFileFilter tarFileFilter =
           MagicNumberFileFilter("ustar", 257);
       String[] tarFiles = dir.list(tarFileFilter);
       for (String tarFile : tarFiles) {
           System.out.println(tarFile);
       }

  Since:
    2.0
  See Also:
    `FileFilterUtils.magicNumberFileFilter(byte[])`, `FileFilterUtils.magicNumberFileFilter(String)`, `FileFilterUtils.magicNumberFileFilter(byte[], long)`, `FileFilterUtils.magicNumberFileFilter(String, long)`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private long` | `byteOffset` The offset (in bytes) within the files that the magic number's bytes should appear.
    `private byte[]` | `magicNumbers` The magic number to compare against the file's bytes at the provided offset.
    `private static long` | `serialVersionUID` The serialization version unique identifier.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MagicNumberFileFilter(byte[] magicNumber)` Constructs a new MagicNumberFileFilter and associates it with the magic number to test for in files.
    `MagicNumberFileFilter(byte[] magicNumber, long offset)` 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.
    `MagicNumberFileFilter(java.lang.String magicNumber)` Constructs a new MagicNumberFileFilter and associates it with the magic number to test for in files.
    `MagicNumberFileFilter(java.lang.String magicNumber, long offset)` 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.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `accept(java.io.File file)` Accepts the provided file if the file contains the file filter's magic number at the specified offset.
    `java.lang.String` | `toString()` Returns a String representation of the file filter, which includes the magic number bytes and byte offset.

    - ### Methods inherited from class org.apache.commons.io.filefilter.AbstractFileFilter

      `accept`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      The serialization version unique identifier.
      See Also:
        Constant Field Values

    - #### magicNumbers

          private final byte[] magicNumbers

      The magic number to compare against the file's bytes at the provided offset.

    - #### byteOffset

          private final long byteOffset

      The offset (in bytes) within the files that the magic number's bytes should appear.

  - ### Constructor Detail

    - #### MagicNumberFileFilter

          public MagicNumberFileFilter(byte[] magicNumber)

      Constructs a new MagicNumberFileFilter and associates it with the magic number to test for in files. This constructor assumes a starting offset of `0`.

      It is important to note that the array is not cloned and that any changes to the magic number array after construction will affect the behavior of this file filter.

           MagicNumberFileFilter javaClassFileFilter =
               MagicNumberFileFilter(new byte[] {(byte) 0xCA, (byte) 0xFE,
                 (byte) 0xBA, (byte) 0xBE});

      Parameters:
        `magicNumber` - the magic number to look for in the file.
      Throws:
        `java.lang.IllegalArgumentException` - if `magicNumber` is `null`, or contains no bytes.

    - #### MagicNumberFileFilter

          public MagicNumberFileFilter(java.lang.String magicNumber)

      Constructs a new MagicNumberFileFilter and associates it with the magic number to test for in files. This constructor assumes a starting offset of `0`.

      Example usage:

           MagicNumberFileFilter xmlFileFilter =
               MagicNumberFileFilter("<?xml");

      Parameters:
        `magicNumber` - the magic number to look for in the file. The string is converted to bytes using the platform default charset.
      Throws:
        `java.lang.IllegalArgumentException` - if `magicNumber` is `null` or the empty String.

    - #### MagicNumberFileFilter

          public MagicNumberFileFilter(java.lang.String magicNumber,
                               long offset)

      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.

           MagicNumberFileFilter tarFileFilter =
               MagicNumberFileFilter("ustar", 257);

      Parameters:
        `magicNumber` - the magic number to look for in the file. The string is converted to bytes using the platform default charset.
        `offset` - the byte offset in the file to start comparing bytes.
      Throws:
        `java.lang.IllegalArgumentException` - if `magicNumber` is `null` or the empty String, or `offset` is a negative number.

    - #### MagicNumberFileFilter

          public MagicNumberFileFilter(byte[] magicNumber,
                               long offset)

      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.

           MagicNumberFileFilter tarFileFilter =
               MagicNumberFileFilter(new byte[] {0x75, 0x73, 0x74, 0x61, 0x72}, 257);

           MagicNumberFileFilter javaClassFileFilter =
               MagicNumberFileFilter(new byte[] {0xCA, 0xFE, 0xBA, 0xBE}, 0);

      Parameters:
        `magicNumber` - the magic number to look for in the file.
        `offset` - the byte offset in the file to start comparing bytes.
      Throws:
        `java.lang.IllegalArgumentException` - if `magicNumber` is `null`, or contains no bytes, or `offset` is a negative number.

  - ### Method Detail

    - #### accept

          public boolean accept(java.io.File file)

      Accepts the provided file if the file contains the file filter's magic number at the specified offset.

      If any `IOException`s occur while reading the file, the file will be rejected.

      Specified by:
        `accept` in interface `java.io.FileFilter`
      Specified by:
        `accept` in interface `IOFileFilter`
      Overrides:
        `accept` in class `AbstractFileFilter`
      Parameters:
        `file` - the file to accept or reject.
      Returns:
        `true` if the file contains the filter's magic number at the specified offset, `false` otherwise.

    - #### toString

          public java.lang.String toString()

      Returns a String representation of the file filter, which includes the magic number bytes and byte offset.
      Overrides:
        `toString` in class `AbstractFileFilter`
      Returns:
        a String representation of the file filter.

Copyright (c) 2002-2016 Apache Software Foundation