## 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.
`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.
`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.

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

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

### 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:
  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`

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

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

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details