Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.util.MagicNumber

java.lang.Object
  |
  +--ncsa.horizon.util.MagicNumber

Subclasses:

FITSMagicNumber, GIFMagicNumber, JPEGMagicNumber

public class MagicNumber

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

a class for identifying a file by its contents, usually in the first few bytes.

This class is based on the "magic number" scheme for identifying files commonly used by UNIX operating systems. This scheme is based on the idea that files certain standardized formats will contain a sequence of bytes near the beginning of the file. For example, the first three bytes of a GIF image file will be the string "GIF"; the second three bytes will identifies the version of the GIF standard, either "87a" or "89a". This class can encapsulate these criteria and provide a way to determine if a file of a particular type or subtype.

Tests are configured at construction typically via three arrays. Each element from each array give an offset for applying the test, a standard (either a byte array or a String) to be compared to, and a string describing the test. The tests should be ordered from general to specific as applicable. If the standard is given as a String, it will be converted to a byte array using the local file string encoding (as given by the file.encoding system property); this is expected to be ASCII in most cases.

Tests are carried out by passing a byte array containing the first few bytes from the file in question along with a bit-field indicating which tests to apply to the test() method. The order of the bit-field corresponds to the order of the tests set at construction. Returned is a bit-field indicating which tests passed. This bit-field can then be handed to getFullTestID() to get a string describing what the file is (much like the output of the UNIX command file).

By default, the test() method applys all the tests that were requested. Subclasses of this class, however, are encouraged to override this method "short-circuit" the tests for efficiency; that is, later tests can be skipped if earlier tests fail.

See Also:

Serialized Form

Field Summary

static int	ALL_TESTS a bit-field specifying all the available tests
java.util.Vector	ids
java.util.Vector	offsets
java.util.Vector	tests

Constructor Summary

MagicNumber()

MagicNumber(int ntests, int defaultTests)

MagicNumber(java.util.Vector offsets, java.util.Vector tests, java.util.Vector ids, int defs)

MagicNumber(int[] offsets, byte[][] tests, java.lang.String[] ids, int defaultTestSet)
initialize a MagicNumber object with a set of tests.

MagicNumber(int[] offsets, java.lang.String[] tests, java.lang.String[] ids, int defaultTestSet)
initialize a MagicNumber object with a set of tests.

MagicNumber(int offset, byte[] test, java.lang.String id)
initialize a MagicNumber object with a single test.

MagicNumber(int offset, java.lang.String test, java.lang.String id)
initialize a MagicNumber object with a single test.

Method Summary

MagicNumber	cloneWithDefaults(int defaultTests) return a new instance that is a clone of this MagicNumber with a different set of default tests
static boolean	compare(byte[] b, int off, byte[] std) test the input byte array against another byte array
int	getByteCount(int t) return the number of bytes that needed from the beginning of the file for a given set of tests.
int	getDefaultTests() return the default set of tests
java.lang.String	getFullTestID(int t) return a concatonation of the descriptions for given a given set of tests.
int	getOffset(int i) return the offset associated with a test of a given index (beginning with 0).
int	getTestCount() return the number of tests that can be applied from this MagicNumber
java.lang.String	getTestID(int i) return the short description of the file type associated with the test of a given index.
byte[]	getTest(int i) return the array of bytes to match for a test of a given index (beginning with 0).
int	testFile(java.io.File file, int which) test the identity of the given input file
int	test(byte[] b, int fileoffset, int t) test the input byte array against a given set of tests
int	test(byte[] b, int fileoffset) test the input byte array against the default set of tests
int	testStream(java.io.InputStream strm, int which) test the identity of the given input stream
int	testURL(java.net.URL url, int which) test the identity of the given URL

Methods inherited from class java.lang.Object

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

Field Detail

offsets

protected java.util.Vector offsets

tests

protected java.util.Vector tests

ids

protected java.util.Vector ids

ALL_TESTS

public static final int ALL_TESTS

a bit-field specifying all the available tests

Constructor Detail

MagicNumber

protected MagicNumber()

MagicNumber

protected MagicNumber(int ntests,
                      int defaultTests)

MagicNumber

protected MagicNumber(java.util.Vector offsets,
                      java.util.Vector tests,
                      java.util.Vector ids,
                      int defs)

MagicNumber

public MagicNumber(int[] offsets,
                   byte[][] tests,
                   java.lang.String[] ids,
                   int defaultTestSet)

initialize a MagicNumber object with a set of tests. The input arrays should all be of the same length.

Parameters:

offset - the byte offsets from the beginning of the file to to apply each test to.

test - the byte arrays identifying the file with increasing specificity

id - short descriptions of a file that passes each test

defaultTestSet - the default set tests to apply when none are specified to the test() method; zero means use the default (in this case, just the first test).

MagicNumber

public MagicNumber(int[] offsets,
                   java.lang.String[] tests,
                   java.lang.String[] ids,
                   int defaultTestSet)

initialize a MagicNumber object with a set of tests. It is assumed by this constructor that all the tests are strings. The input arrays should all be of the same length.

Parameters:

offset - the byte offsets from the beginning of the file to to apply each test to.

test - the sub-strings identifying the file with increasing specificity; the default character encoding is used to convert the string to bytes.

id - short descriptions of a file that passes each test

defaultTestSet - the default set tests to apply when none are specified to the test() method; zero means use the default (in this case, just the first test).

MagicNumber

public MagicNumber(int offset,
                   byte[] test,
                   java.lang.String id)

initialize a MagicNumber object with a single test.

Parameters:

offset - the byte offset from the beginning of the file to to apply the test to.

test - a byte array identifying the file

id - a short description of a file that passes the test

MagicNumber

public MagicNumber(int offset,
                   java.lang.String test,
                   java.lang.String id)

initialize a MagicNumber object with a single test.

Parameters:

offset - the byte offset from the beginning of the file to to apply the test to.

test - a string identifying the file; the default character encoding is used to convert the string to bytes.

id - a short description of a file that passes the test

Method Detail

getTestCount

public int getTestCount()

return the number of tests that can be applied from this MagicNumber

getOffset

public int getOffset(int i)

return the offset associated with a test of a given index (beginning with 0).

getTest

public byte[] getTest(int i)

return the array of bytes to match for a test of a given index (beginning with 0).

getTestID

public java.lang.String getTestID(int i)

return the short description of the file type associated with the test of a given index.

getFullTestID

public java.lang.String getFullTestID(int t)

return a concatonation of the descriptions for given a given set of tests. (A space will be inserted between each description.)

Parameters:

t - a bit-field identifying the tests

getByteCount

public int getByteCount(int t)

return the number of bytes that needed from the beginning of the file for a given set of tests.

Parameters:

t - a bit-field identifying the tests

getDefaultTests

public int getDefaultTests()

return the default set of tests

test

public int test(byte[] b,
                int fileoffset,
                int t)
        throws java.lang.ArrayIndexOutOfBoundsException

test the input byte array against a given set of tests

Parameters:

b - the byte array from the file to test

fileoffset - the offset of the first byte in b from the beginning of the file (may be negative).

t - the set of tests to apply given as a bit-field.

Returns:

int the set of tests that passed

Throws:

java.lang.ArrayIndexOutOfBoundsException - if b does not contain enough bytes to carry out the requested tests

test

public int test(byte[] b,
                int fileoffset)
        throws java.lang.ArrayIndexOutOfBoundsException

test the input byte array against the default set of tests

Parameters:

b - the byte array from the file to test

fileoffset - the offset of the first byte in b from the beginning of the file (may be negative).

Returns:

int the set of tests that passed

Throws:

java.lang.ArrayIndexOutOfBoundsException - if b does not contain enough bytes to carry out the requested tests

compare

public static boolean compare(byte[] b,
                              int off,
                              byte[] std)

test the input byte array against another byte array

Parameters:

b - a byte array

off - the offset of the first byte in b to begin the comparison

std - a byte array to compare with b

cloneWithDefaults

public MagicNumber cloneWithDefaults(int defaultTests)

return a new instance that is a clone of this MagicNumber with a different set of default tests

testStream

public int testStream(java.io.InputStream strm,
                      int which)
              throws java.io.IOException

test the identity of the given input stream

Parameters:

strm - the input stream, assuming it is set to the start of the file

which - the tests to apply

Returns:

int the tests that succeeded

Throws:

java.io.IOException - if an IO error occurs while reading the stream.

testFile

public int testFile(java.io.File file,
                    int which)
            throws java.io.IOException,
                   java.io.FileNotFoundException

test the identity of the given input file

Parameters:

file - the input file

which - the tests to apply

Returns:

int the tests that succeeded

Throws:

java.io.IOException - if an IO error occurs while reading the stream.

java.io.FileNotFoundException - if the file is not found

testURL

public int testURL(java.net.URL url,
                   int which)
           throws java.io.IOException

test the identity of the given URL

Parameters:

url - the URL of the file

which - the tests to apply

Returns:

int the tests that succeeded

Throws:

java.io.IOException - if an IO error occurs while reading the URL stream.