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
static void	closeClosable()
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.
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 quering 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(float[] vec, int offset, int len)
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.
java.lang.String	readToDelimiter(char delim) Reads a string until the specified delimiter or EOF is encountered
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.

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.

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 quering 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 intialized 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

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.

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

Throws:

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

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. Equivelent 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

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[])

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

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

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

public 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()