com.bbn.openmap.io
Class BinaryFile

java.lang.Object
  com.bbn.openmap.io.BinaryFile

Direct Known Subclasses:

BinaryBufferedFile

public class BinaryFile
extends java.lang.Object

The BinaryFile is the standard object used to access data files. It acts like a RandomAccessFile, but will work on jar file contents and URLs, too. The source of the data is isolated through the InputReader interface.

Field Summary

protected boolean

MSBFirst The byte order of the underlying file.

Constructor Summary

BinaryFile(java.io.File f)
Constructs a new BinaryFile with the specified file as the input.

BinaryFile(java.lang.String name)
Constructs a new BinaryFile with the specified file as the input.

Method Summary

static void	addClosable(Closable it) Add an object that can be closed if needed.
void	assertChar(char expected) Read a bytes and throw an InvalidCharException if it doesn't match expected
long	available() Return how many bytes left to be read in the file.
boolean	byteOrder() Accessor for the byte ordering used to read multibyte types.
void	byteOrder(boolean msbfirst) Set the byte-ordering used to read shorts, int, etc.
void	close() Closes the underlying file, but with a chance for re-opening if accessed again.
static void	closeClosable()
void	dispose() Closes underlying file, get rid of resources and knowledge of file.
static boolean	exists(java.lang.String name) A simple test method to determine if a file or directory, represented by a string, can be found by the current Java environment.
protected void	finalize() Makes sure that the file has been closed.
long	getFilePointer() Get the index of the next character to be read
InputReader	getInputReader() Get the inputReader used for accessing the file, for querying purposes.
java.lang.String	getName() Get the source name from the input reader.
long	length() The length of the InputReader source.
int	read() Read from the file.
int	read(byte[] b) Read from the file.
int	read(byte[] b, int off, int len) Read from the file
byte[]	readBytes(int howmany, boolean allowless) Read from the file.
char	readChar() Reads and returns a single byte, cast to a char
double	readDouble() Reads and returns a double
java.lang.String	readFixedLengthString(int length) Reads length bytes and returns a string composed of the bytes cast to chars
float	readFloat() Reads and returns a float
void	readFloatArray(double[] vec, int offset, int len)
void	readFloatArray(float[] vec, int offset, int len)
BinaryFile	readFully() Read the BinaryFile into memory and return a new BinaryFile instance working on that in-memory version of the file.
int	readInteger() Reads and returns a long
void	readIntegerArray(int[] vec, int offset, int len)
long	readLong() Reads and returns a long
short	readShort() Reads and returns a short.
short	readShortData() Code for reading shorts that are two-byte integers, high order first, and negatives are signed magnitude.
java.lang.String	readToDelimiter(char delim) Reads a string until the specified delimiter or EOF is encountered
int	readUnsigned() Read a byte from the file, return an unsigned integer.
int	readUnsignedShort() Reads and returns a integer from 2 bytes.
static void	removeClosable(Closable it) Remove an object from the closable list.
void	seek(long pos) Set the index of the next character to be read.
void	setInputReader(InputReader reader) Set the input reader used by the BinaryFile.
protected boolean	setJarInputReader(java.lang.String name) Takes a name of a file, and checks to see if it reflects an entry in a jar file.
long	skipBytes(long n) Skip over n bytes in the input file

Methods inherited from class java.lang.Object

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

Field Detail

MSBFirst

protected boolean MSBFirst

The byte order of the underlying file. (true== MSB-First == big-endian)

Constructor Detail

BinaryFile

public BinaryFile(java.io.File f)
           throws java.io.IOException

Constructs a new BinaryFile with the specified file as the input. The default byte-order is LSB first. Reads start at the first byte of the file.

Parameters:

f - the file to be opened for reading

Throws:

java.io.IOException - pass-through errors from opening a RandomAccessFile with f

See Also:

RandomAccessFile

BinaryFile

public BinaryFile(java.lang.String name)
           throws java.io.IOException

Constructs a new BinaryFile with the specified file as the input. The byte-order is undefined. Reads start at the first byte of the file. This constructor looks for the file with the string given, and will call the correct constructor as appropriate. If the string represents a file available locally, then the BinaryFile will be accessed with a FileInputReader using a RandomAccessFile. If it's only available as a resource, then a StreamInputReader will be used. The name should be a path to a file, or the name of a resource that can be found in the classpath, or a URL.

Parameters:

name - the name of the file to be opened for reading

Throws:

java.io.IOException - pass-through errors from opening the file.

Method Detail

setJarInputReader

protected boolean setJarInputReader(java.lang.String name)
                             throws java.io.IOException

Takes a name of a file, and checks to see if it reflects an entry in a jar file. (Check the filename and see if it looks like "jarfile!jarfileentry".) If it is, it separates the path, and set the inputReader to a JarInputReader and returns true. If not, it returns false.

Throws:

java.io.IOException

exists

public static boolean exists(java.lang.String name)

A simple test method to determine if a file or directory, represented by a string, can be found by the current Java environment. Uses the same tests as BinaryFile constructor for tracking down a file.

Parameters:

name - A path to a file, a URL, or a path to a jar file entry.

Returns:

true if the file can be found

getName

public java.lang.String getName()

Get the source name from the input reader.

getInputReader

public InputReader getInputReader()

Get the inputReader used for accessing the file, for querying purposes. Don't use it to get data, or the file pointers may get messed up.

setInputReader

public void setInputReader(InputReader reader)

Set the input reader used by the BinaryFile. Make sure it's initialized properly.

byteOrder

public void byteOrder(boolean msbfirst)

Set the byte-ordering used to read shorts, int, etc.

Parameters:

msbfirst - true= MSB first, false= LSB first

byteOrder

public boolean byteOrder()

Accessor for the byte ordering used to read multibyte types.

Returns:

byte ordering, true means MSB first.

skipBytes

public long skipBytes(long n)
               throws java.io.IOException

Skip over n bytes in the input file

Parameters:

n - the number of bytes to skip

Returns:

the actual number of bytes skipped. annoying, isn't it?

Throws:

java.io.IOException - Any IO errors that occur in skipping bytes in the underlying file

getFilePointer

public long getFilePointer()
                    throws java.io.IOException

Get the index of the next character to be read

Returns:

the index

Throws:

java.io.IOException - Any IO errors that occur in accessing the underlying file

seek

public void seek(long pos)
          throws java.io.IOException

Set the index of the next character to be read.

Parameters:

pos - the position to seek to.

Throws:

java.io.IOException - Any IO Errors that occur in seeking the underlying file.

length

public long length()
            throws java.io.IOException

The length of the InputReader source.

Throws:

java.io.IOException

available

public long available()
               throws java.io.IOException

Return how many bytes left to be read in the file.

Returns:

the number of bytes remaining to be read (counted in bytes)

Throws:

java.io.IOException - Any IO errors encountered in accessing the file

close

public void close()
           throws java.io.IOException

Closes the underlying file, but with a chance for re-opening if accessed again.

Throws:

java.io.IOException - Any IO errors encountered in accessing the file

dispose

public void dispose()
             throws java.io.IOException

Closes underlying file, get rid of resources and knowledge of file. To be called when you don't need the file any more.

Throws:

java.io.IOException

read

public int read()
         throws java.io.IOException

Read from the file.

Returns:

one byte from the file. -1 for EOF

Throws:

java.io.IOException - Any IO errors encountered in reading from the file

read

public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException

Read from the file

Parameters:

b - The byte array to read into

off - the first array position to read into

len - the number of bytes to read

Returns:

the number of bytes read

Throws:

java.io.IOException - Any IO errors encountered in reading from the file

read

public int read(byte[] b)
         throws java.io.IOException

Read from the file.

Parameters:

b - the byte array to read into. Equivalent to read(b, 0, b.length)

Returns:

the number of bytes read

Throws:

java.io.IOException - Any IO errors encountered in reading from the file

See Also:

RandomAccessFile.read(byte[])

readBytes

public byte[] readBytes(int howmany,
                        boolean allowless)
                 throws java.io.EOFException,
                        FormatException

Read from the file.

Parameters:

howmany - the number of bytes to read

allowless - if we can return fewer bytes than requested

Returns:

the array of bytes read.

Throws:

FormatException - Any IO Exceptions, plus an end-of-file encountered after reading some, but now enough, bytes when allowless was false

java.io.EOFException - Encountered an end-of-file while allowless was false, but NO bytes had been read.

readChar

public char readChar()
              throws java.io.EOFException,
                     FormatException

Reads and returns a single byte, cast to a char

Returns:

the byte read from the file, cast to a char

Throws:

java.io.EOFException - the end-of-file has been reached, so no chars where available

FormatException - a rethrown IOException

readUnsigned

public int readUnsigned()
                 throws java.io.IOException,
                        java.io.EOFException

Read a byte from the file, return an unsigned integer.

Returns:

one byte from the file. -1 for EOF causes EOFException

Throws:

java.io.IOException - Any IO errors encountered in reading from the file

java.io.EOFException

readShort

public short readShort()
                throws java.io.EOFException,
                       FormatException

Reads and returns a short.

Returns:

the 2 bytes merged into a short, according to the current byte ordering

Throws:

java.io.EOFException - there were less than 2 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the short

See Also:

read(byte[])

readShortData

public short readShortData()
                    throws java.io.EOFException,
                           FormatException

Code for reading shorts that are two-byte integers, high order first, and negatives are signed magnitude. Users may have to switch the bytes and convert negatives to the complement they use. This can be done by putting the low order byte first, then turning off bit 15 (the high order bit), and then multiplying by -1." Basically they are encoded as positive numbers, but bit 15 is set to 1.

Returns:

2 bytes merged into a short

Throws:

java.io.EOFException

FormatException

readUnsignedShort

public int readUnsignedShort()
                      throws java.io.EOFException,
                             FormatException

Reads and returns a integer from 2 bytes.

Returns:

the 2 bytes merged into a short, according to the current byte ordering, and then unsigned to int.

Throws:

java.io.EOFException - there were less than 2 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the short

See Also:

read(byte[])

readInteger

public int readInteger()
                throws java.io.EOFException,
                       FormatException

Reads and returns a long

Returns:

the 4 bytes merged into a long, according to the current byte ordering

Throws:

java.io.EOFException - there were less than 4 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the integer

See Also:

read(byte[])

readIntegerArray

public void readIntegerArray(int[] vec,
                             int offset,
                             int len)
                      throws java.io.EOFException,
                             FormatException

Throws:

java.io.EOFException

FormatException

readLong

public long readLong()
              throws java.io.EOFException,
                     FormatException

Reads and returns a long

Returns:

the 8 bytes merged into a long, according to the current byte ordering

Throws:

java.io.EOFException - there were less than 8 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the long

See Also:

read(byte[])

readFloat

public float readFloat()
                throws java.io.EOFException,
                       FormatException

Reads and returns a float

Returns:

the 4 bytes merged into a float, according to the current byte ordering

Throws:

java.io.EOFException - there were less than 4 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the float

See Also:

read(byte[])

readFloatArray

public void readFloatArray(float[] vec,
                           int offset,
                           int len)
                    throws java.io.EOFException,
                           FormatException

Throws:

java.io.EOFException

FormatException

readFloatArray

public void readFloatArray(double[] vec,
                           int offset,
                           int len)
                    throws java.io.EOFException,
                           FormatException

Throws:

java.io.EOFException

FormatException

readDouble

public double readDouble()
                  throws java.io.EOFException,
                         FormatException

Reads and returns a double

Returns:

the 8 bytes merged into a double, according to the current byte ordering

Throws:

java.io.EOFException - there were less than 8 bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the short

See Also:

read(byte[])

readFixedLengthString

public java.lang.String readFixedLengthString(int length)
                                       throws java.io.EOFException,
                                              FormatException

Reads length bytes and returns a string composed of the bytes cast to chars

Parameters:

length - the number of bytes to read into the string

Returns:

the composed string

Throws:

java.io.EOFException - there were less than length bytes left in the file

FormatException - rethrow of IOExceptions encountered while reading the bytes for the short

assertChar

public void assertChar(char expected)
                throws java.io.EOFException,
                       FormatException

Read a bytes and throw an InvalidCharException if it doesn't match expected

Parameters:

expected - what the next char is claimed to be

Throws:

java.io.EOFException - there wasn't a byte, so we can't check for a match

InvalidCharException - throws when the character read doesn't match expected The .c member of the thrown exception is the actual char read

FormatException - some other error from reading the file

readToDelimiter

public java.lang.String readToDelimiter(char delim)
                                 throws FormatException

Reads a string until the specified delimiter or EOF is encountered

Parameters:

delim - the end-of-string delimiter

Returns:

the string that was read

Throws:

FormatException - rethrow of IOExceptions from the read methods

finalize

protected void finalize()
                 throws java.lang.Throwable

Makes sure that the file has been closed.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - what it throws.

addClosable

public static void addClosable(Closable it)

Add an object that can be closed if needed. Duplicates are allowed. Only holds a WeakReference, so that the object can still be garbage-collected.

Parameters:

it - the object that can be closed

removeClosable

public static void removeClosable(Closable it)

Remove an object from the closable list.

Parameters:

it - the object to remove

closeClosable

public static void closeClosable()

readFully

public BinaryFile readFully()
                     throws java.io.IOException

Read the BinaryFile into memory and return a new BinaryFile instance working on that in-memory version of the file.

Returns:

BinaryFile object pointing to memory version.

Throws:

java.io.IOException