BufferedRandomAccessFile (Core 1.0.2 API)

java.lang.Object
- org.gridfour.io.BufferedRandomAccessFile

All Implemented Interfaces:

Closeable, DataInput, DataOutput, AutoCloseable
```
public class BufferedRandomAccessFile
extends Object
implements Closeable, AutoCloseable, DataInput, DataOutput
```
Provides a wrapper around a Java Random Access File which supports buffered I/O, dramatically improving the performance for many kinds of random-access file read and write operations.
Many of the methods in this class are based on Java's API DataInput and DataOutput interfaces.
Note: It is the intent of this implementation to ultimately be expanded to implement the full Java DataInput and DataOutput interfaces. Because Java defines these methods and accessing a file in big-endian byte order, methods with names such as readInt and writeInt would necessarily have to operate over data given in big-endian order. Thus those methods in the current implementation that operate on multi-byte data types (int, long, short, float, double) all begin with the prefix "le" for "little endian".
Note: At the present time, this implementation does not support operations that seek to positions past the length of the file. That is, of the length of the file is n, the seek(n) is supported but seek(n+1) is not. Thus, operations that would create files with "unwritten" or "unpopulated" blocks of disk space are not supported. Future development of this feature will depend on user interest and a clear definition of the appropriate behavior.

Constructor Summary

Constructors
Constructor and Description
`BufferedRandomAccessFile(File file, String mode)` Opens the specified file for read or write access using the specified access mode following the conventions of the Java RandomnAccessFile class.
`BufferedRandomAccessFile(String fileName, String mode)` Opens the specified file for read or write access using the specified access mode following the conventions of the Java RandomnAccessFile class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()`
`void`	`flush()` Ensures that any pending output stored in the buffer is written to the underlying random access file.
`File`	`getFile()` Gets a reference to the file associated with this class.
`long`	`getFilePosition()` Gets the position within the file at which the next write or read operation will be performed.
`long`	`getFileSize()` Gets the size of the file in bytes.
`boolean`	`isClosed()` Indicates whether the file is closed.
`double`	`leReadDouble()`
`float`	`leReadFloat()`
`void`	`leReadFloatArray(float[] array, int arrayOffset, int length)` Read an array of floats accessing them in little-endian order.
`int`	`leReadInt()`
`void`	`leReadIntArray(int[] array, int arrayOffset, int length)` Reads an array of integers accessing them in little-endian order.
`long`	`leReadLong()`
`short`	`leReadShort()`
`void`	`leReadShortArray(short[] array, int arrayOffset, int length)` Reads an array of integers accessing them in little-endian order.
`int`	`leReadUnsignedShort()`
`String`	`leReadUTF()` Reads a series of UTF-8 characters based on the little-endian byte order The first two bytes give a short integer indicating the length of the string specification in bytes.
`void`	`leWriteDouble(double v)`
`void`	`leWriteFloat(float v)`
`void`	`leWriteInt(int value)`
`void`	`leWriteLong(long v)`
`void`	`leWriteShort(int v)`
`void`	`leWriteUTF(String s)` Writes a series of UTF-8 characters using the little-endian byte order.
`void`	`printDiagnostics(PrintStream ps)` Prints current state data for file.
`String`	`readASCII(int nBytesToRead)` Reads the specified number of bytes from the source file treating them as ASCII characters and returning a valid, potentially zero-length string.
`int`	`readASCII(StringBuilder builder, int nBytesToRead)` Reads the specified number of bytes from the source file treating them as ASCII characters and appending them to a string builder.
`boolean`	`readBoolean()` Reads one input byte and returns true if that byte is nonzero, false if that byte is zero.
`byte`	`readByte()` Reads a single byte from the file, interpreting it as a signed value in the range -128 through 127, inclusive.
`char`	`readChar()` Reads two input bytes and returns a char value following the general specification of the Java DataInput interface.
`char`	`readCharASCII()` Reads a single byte from the file, interpreting it as an ASCII character.
`double`	`readDouble()` Reads a 8-byte floating-point value in the big-endian order compatible with the Java DataInput interface.
`float`	`readFloat()` Reads a 4-byte floating-point value in the big-endian order compatible with the Java DataInput interface.
`void`	`readFully(byte[] array)` Reads enough bytes from the input file to fill the specified byte array.
`void`	`readFully(byte[] array, int arrayOffset, int length)` Reads the specified number of bytes from the input file into the provided array starting at the specified offset position.Bytes are signed values in the range -128 to 127.
`int`	`readInt()` Reads a 4-byte integer value in the big-endian order compatible with the Java DataInput interface.
`String`	`readLine()` Reads the next line of text from the input following the general specifications of the DataInput interface.
`long`	`readLong()` Reads a 8-byte integer value in the big-endian order compatible with the Java DataInput interface.
`short`	`readShort()` Reads a 2-byte (short) integer value in the big-endian order compatible with the Java DataInput interface.
`int`	`readUnsignedByte()` Reads a single unsigned byte from the file, interpreting it as a signed value in the range 0 through 255, inclusive.
`int`	`readUnsignedShort()` Reads 2-bytes as an unsigned integer value in the big-endian order compatible with the Java DataInput interface.
`String`	`readUTF()` Reads a series of UTF-8 characters following the specifications of the DataOutput interface.
`void`	`seek(long position)` Sets the file position given as an offset the beginning of the file.
`int`	`skipBytes(int n)` Attempts to skip over n bytes.
`void`	`write(byte[] b)` Writes an array of bytes to the output
`void`	`write(byte[] b, int offset, int length)`
`void`	`write(int b)`
`void`	`writeASCII(String s, int nBytes)`
`void`	`writeBoolean(boolean v)`
`void`	`writeByte(int value)`
`void`	`writeBytes(String s)`
`void`	`writeChar(int v)` Writes a character using two output bytes following the general specification of the Java DataOutput interface.
`void`	`writeChars(String s)`
`void`	`writeDouble(double v)`
`void`	`writeFloat(float v)`
`void`	`writeFully(byte[] array)`
`void`	`writeFully(byte[] array, int arrayOffset, int length)`
`void`	`writeInt(int value)` Writes a 4 byte integer value to the output in a form consistent with the Java DataOutput interface.
`void`	`writeLong(long v)`
`void`	`writeShort(int s)` Writes two bytes to the output following the specifications of the Java DataOutput interface.
`void`	`writeUTF(String s)` Writes a series of UTF-8 characters following the specifications of the DataOutput interface.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - BufferedRandomAccessFile
```
public BufferedRandomAccessFile(String fileName,
                                String mode)
                         throws IOException
```
    Opens the specified file for read or write access using the specified access mode following the conventions of the Java RandomnAccessFile class. Since the BufferedRandomAccessFile is a wrapper around the Java class, application developers can expect this class to perform similar operations to the Java class.
    
    Parameters:
    
    fileName - a valid path or file name for opening a file
    
    mode - the access mode following the conventions of Java
    
    Throws:
    
    IOException - in the event of an I/O error
  - BufferedRandomAccessFile
```
public BufferedRandomAccessFile(File file,
                                String mode)
                         throws IOException
```
    Opens the specified file for read or write access using the specified access mode following the conventions of the Java RandomnAccessFile class. Since the BufferedRandomAccessFile is a wrapper around the Java class, application developers can expect this class to perform similar operations to the Java class.
    
    Parameters:
    
    file - a valid file reference
    
    mode - the access mode following the conventions of Java
    
    Throws:
    
    IOException - in the event of an I/O error
- Method Detail
  - close
```
public void close()
           throws IOException
```
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Throws:
    
    IOException
  - isClosed
```
public boolean isClosed()
```
    Indicates whether the file is closed.
    
    Returns:
    
    true if the file is closed; otherwise, true
  - flush
```
public void flush()
           throws IOException
```
    Ensures that any pending output stored in the buffer is written to the underlying random access file.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - getFileSize
```
public long getFileSize()
```
    Gets the size of the file in bytes. If this instance is currently holding output data in its buffer, the return value from this method may be larger than the actual size of the file on disk.
    
    Returns:
    
    a positive long integer value.
  - getFilePosition
```
public long getFilePosition()
```
    Gets the position within the file at which the next write or read operation will be performed. The file position is measured in bytes and given as an offset from the first byte in the file (i.e. the first byte is at position zero).
    
    Returns:
    
    a positive long integer value
  - getFile
```
public File getFile()
```
    Gets a reference to the file associated with this class.
    
    Returns:
    
    a valid file reference.
  - leReadDouble
```
public double leReadDouble()
                    throws IOException
```
    Throws:
    
    IOException
  - leReadFloat
```
public float leReadFloat()
                  throws IOException
```
    Throws:
    
    IOException
  - leReadInt
```
public int leReadInt()
              throws IOException
```
    Throws:
    
    IOException
  - leReadLong
```
public long leReadLong()
                throws IOException
```
    Throws:
    
    IOException
  - leReadShort
```
public short leReadShort()
                  throws IOException
```
    Throws:
    
    IOException
  - leReadUnsignedShort
```
public int leReadUnsignedShort()
                        throws IOException
```
    Throws:
    
    IOException
  - leWriteShort
```
public void leWriteShort(int v)
                  throws IOException
```
    Throws:
    
    IOException
  - leWriteInt
```
public void leWriteInt(int value)
                throws IOException
```
    Throws:
    
    IOException
  - leWriteLong
```
public void leWriteLong(long v)
                 throws IOException
```
    Throws:
    
    IOException
  - leWriteFloat
```
public void leWriteFloat(float v)
                  throws IOException
```
    Throws:
    
    IOException
  - leWriteDouble
```
public void leWriteDouble(double v)
                   throws IOException
```
    Throws:
    
    IOException
  - leReadIntArray
```
public void leReadIntArray(int[] array,
                           int arrayOffset,
                           int length)
                    throws IOException
```
    Reads an array of integers accessing them in little-endian order.
    
    Parameters:
    
    array - a valid, non-zero sized array
    
    arrayOffset - the starting position within the array.
    
    length - the number of values to read.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - leReadFloatArray
```
public void leReadFloatArray(float[] array,
                             int arrayOffset,
                             int length)
                      throws IOException
```
    Read an array of floats accessing them in little-endian order.
    
    Parameters:
    
    array - a valid, non-zero sized array
    
    arrayOffset - the starting position within the array.
    
    length - the number of values to read.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - leReadShortArray
```
public void leReadShortArray(short[] array,
                             int arrayOffset,
                             int length)
                      throws IOException
```
    Reads an array of integers accessing them in little-endian order.
    
    Parameters:
    
    array - a valid, non-zero sized array
    
    arrayOffset - the starting position within the array.
    
    length - the number of values to read.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - leReadUTF
```
public String leReadUTF()
                 throws IOException
```
    Reads a series of UTF-8 characters based on the little-endian byte order The first two bytes give a short integer indicating the length of the string specification in bytes. They are followed by the bytes comprising the UTF-8 encoded characters for the string. Note that some of the UTF-8 characters in the string may require more than a single byte for their representation.
    
    Returns:
    
    a valid, potentially empty string.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - leWriteUTF
```
public void leWriteUTF(String s)
                throws IOException
```
    Writes a series of UTF-8 characters using the little-endian byte order. The first two bytes give an unsigned short integer indicating the length of the string specification. Next follow the bytes comprising the UTF-8 encoded characters for the string. Note that some of the UTF-8 characters in the string may require more than a single byte for their representation.
    
    Parameters:
    
    s - a valid String
    
    Throws:
    
    IOException - in the event of an I/O error.
  - readBoolean
```
public boolean readBoolean()
                    throws IOException
```
    Reads one input byte and returns true if that byte is nonzero, false if that byte is zero. This method is suitable for reading the byte written by the writeBoolean method of this class.
    
    Specified by:
    
    readBoolean in interface DataInput
    
    Returns:
    
    the boolean value read from the source file.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - readByte
```
public byte readByte()
              throws IOException
```
    Reads a single byte from the file, interpreting it as a signed value in the range -128 through 127, inclusive. This method is suitable for reading the byte written by the writeByte method of this class.
    
    Specified by:
    
    readByte in interface DataInput
    
    Returns:
    
    a signed by value.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - readCharASCII
```
public char readCharASCII()
                   throws IOException
```
    Reads a single byte from the file, interpreting it as an ASCII character.
    
    Returns:
    
    a character in the range 0 to 255.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - readFully
```
public void readFully(byte[] array)
               throws IOException
```
    Reads enough bytes from the input file to fill the specified byte array. Bytes are signed values in the range -128 to 127.
    
    Specified by:
    
    readFully in interface DataInput
    
    Parameters:
    
    array - a valid array
    
    Throws:
    
    IOException - if an I/O error occurs, including an end-of-file condition.
  - readFully
```
public void readFully(byte[] array,
                      int arrayOffset,
                      int length)
               throws IOException
```
    Reads the specified number of bytes from the input file into the provided array starting at the specified offset position.Bytes are signed values in the range -128 to 127.
    
    Specified by:
    
    readFully in interface DataInput
    
    Parameters:
    
    array - a valid array
    
    arrayOffset - the starting index in the array
    
    length - the number of bytes to read
    
    Throws:
    
    IOException - if an I/O error occurs, including an end-of-file condition.
  - readUnsignedByte
```
public int readUnsignedByte()
                     throws IOException
```
    Reads a single unsigned byte from the file, interpreting it as a signed value in the range 0 through 255, inclusive. This method is suitable for reading the byte written by the writeByte method of this class.
    
    Specified by:
    
    readUnsignedByte in interface DataInput
    
    Returns:
    
    a signed by value.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - readASCII
```
public int readASCII(StringBuilder builder,
                     int nBytesToRead)
              throws IOException
```
    Reads the specified number of bytes from the source file treating them as ASCII characters and appending them to a string builder. If a zero byte is detected, it is treated as a null terminator and the additional bytes will not be appended to the builder, but the file position will be advanced by the specified number of bytes.
    
    Parameters:
    
    builder - a valid StringBuilder instance, not necessarily empty.
    
    nBytesToRead - the number of bytes to read from the file
    
    Returns:
    
    the length of the null-terminated string read from the file (not the length of the StringBuilder content).
    
    Throws:
    
    IOException - if an I/O error occurs.
  - readASCII
```
public String readASCII(int nBytesToRead)
                 throws IOException
```
    Reads the specified number of bytes from the source file treating them as ASCII characters and returning a valid, potentially zero-length string. If a zero byte is detected in the input, it is treated as a null terminator and the additional bytes will not be appended to the string, but the file position will be advanced by the specified number of bytes.
    
    Parameters:
    
    nBytesToRead - the number of bytes to read from the file
    
    Returns:
    
    the length of the null-terminated string read from the file (not the length of the StringBuilder content).
    
    Throws:
    
    IOException - if an I/O error occurs.
  - seek
```
public void seek(long position)
          throws IOException
```
    Sets the file position given as an offset the beginning of the file. This setting gives the position at which the next read or write will occur.
    
    Parameters:
    
    position - the file-pointer offset position
    
    Throws:
    
    IOException - if the position is less than zero or an I/O error occurs.
  - skipBytes
```
public int skipBytes(int n)
              throws IOException
```
    Attempts to skip over n bytes.
    
    Specified by:
    
    skipBytes in interface DataInput
    
    Parameters:
    
    n - the number of bytes to skip
    
    Returns:
    
    the actual number of bytes skipped.
    
    Throws:
    
    IOException - if an I/O error occurs.
  - writeByte
```
public void writeByte(int value)
               throws IOException
```
    Specified by:
    
    writeByte in interface DataOutput
    
    Throws:
    
    IOException
  - writeFully
```
public void writeFully(byte[] array)
                throws IOException
```
    Throws:
    
    IOException
  - writeFully
```
public void writeFully(byte[] array,
                       int arrayOffset,
                       int length)
                throws IOException
```
    Throws:
    
    IOException
  - write
```
public void write(int b)
           throws IOException
```
    Specified by:
    
    write in interface DataOutput
    
    Throws:
    
    IOException
  - write
```
public void write(byte[] b)
           throws IOException
```
    Writes an array of bytes to the output
    
    Specified by:
    
    write in interface DataOutput
    
    Parameters:
    
    b - a valid array of bytes
    
    Throws:
    
    IOException - in the event of an unexpected I/O condition
  - write
```
public void write(byte[] b,
                  int offset,
                  int length)
           throws IOException
```
    Specified by:
    
    write in interface DataOutput
    
    Throws:
    
    IOException
  - writeBoolean
```
public void writeBoolean(boolean v)
                  throws IOException
```
    Specified by:
    
    writeBoolean in interface DataOutput
    
    Throws:
    
    IOException
  - writeBytes
```
public void writeBytes(String s)
                throws IOException
```
    Specified by:
    
    writeBytes in interface DataOutput
    
    Throws:
    
    IOException
  - writeASCII
```
public void writeASCII(String s,
                       int nBytes)
                throws IOException
```
    Throws:
    
    IOException
  - writeShort
```
public void writeShort(int s)
                throws IOException
```
    Writes two bytes to the output following the specifications of the Java DataOutput interface.
    
    Specified by:
    
    writeShort in interface DataOutput
    
    Parameters:
    
    s - an integer value. If the value is outside the range of a short integer (-32768 to 32767), only the two low-order bytes will be written.
    
    Throws:
    
    IOException - in the event of an I/O error
  - writeInt
```
public void writeInt(int value)
              throws IOException
```
    Writes a 4 byte integer value to the output in a form consistent with the Java DataOutput interface.
    
    Specified by:
    
    writeInt in interface DataOutput
    
    Parameters:
    
    value - an integer value
    
    Throws:
    
    IOException - in the event of an I/O error
  - writeUTF
```
public void writeUTF(String s)
              throws IOException
```
    Writes a series of UTF-8 characters following the specifications of the DataOutput interface. The first two bytes give a short integer indicating the length of the string specification, followed by the bytes comprising the UTF-8 encoded characters for the string. Note that some of the UTF-8 characters in the string may require more than a single byte for their representation.
    
    Specified by:
    
    writeUTF in interface DataOutput
    
    Parameters:
    
    s - a valid String
    
    Throws:
    
    IOException - in the event of an I/O error.
  - readDouble
```
public double readDouble()
                  throws IOException
```
    Reads a 8-byte floating-point value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readDouble in interface DataInput
    
    Returns:
    
    if successful, a valid float value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readFloat
```
public float readFloat()
                throws IOException
```
    Reads a 4-byte floating-point value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readFloat in interface DataInput
    
    Returns:
    
    if successful, a valid float value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readInt
```
public int readInt()
            throws IOException
```
    Reads a 4-byte integer value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readInt in interface DataInput
    
    Returns:
    
    if successful, a valid integer value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readLong
```
public long readLong()
              throws IOException
```
    Reads a 8-byte integer value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readLong in interface DataInput
    
    Returns:
    
    if successful, a valid integer value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readShort
```
public short readShort()
                throws IOException
```
    Reads a 2-byte (short) integer value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readShort in interface DataInput
    
    Returns:
    
    if successful, a valid signed short value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readUnsignedShort
```
public int readUnsignedShort()
                      throws IOException
```
    Reads 2-bytes as an unsigned integer value in the big-endian order compatible with the Java DataInput interface.
    
    Specified by:
    
    readUnsignedShort in interface DataInput
    
    Returns:
    
    if successful, a valid signed short value
    
    Throws:
    
    IOException - in the event of an I/O error
  - readUTF
```
public String readUTF()
               throws IOException
```
    Reads a series of UTF-8 characters following the specifications of the DataOutput interface. The first two bytes give a short integer indicating the length of the string specification, followed by the bytes comprising the UTF-8 encoded characters for the string. Note that some of the UTF-8 characters in the string may require more than a single byte for their representation.
    
    Specified by:
    
    readUTF in interface DataInput
    
    Returns:
    
    a valid, potentially empty string.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - readLine
```
public String readLine()
                throws IOException
```
    Reads the next line of text from the input following the general specifications of the DataInput interface. Note that this method reads characters one byte at a time and does not fully implement the Unicode character set.
    
    Specified by:
    
    readLine in interface DataInput
    
    Returns:
    
    if successful, a valid potentially empty string; if unsuccessful, a null.
    
    Throws:
    
    IOException - in the event of an I/O error.
  - printDiagnostics
```
public void printDiagnostics(PrintStream ps)
```
    Prints current state data for file. Intended for debugging and development.
    
    Parameters:
    
    ps - a valid PrintStream for writing the output (may be System.out).
  - readChar
```
public char readChar()
              throws IOException
```
    Reads two input bytes and returns a char value following the general specification of the Java DataInput interface.
    
    Specified by:
    
    readChar in interface DataInput
    
    Returns:
    
    a valid char
    
    Throws:
    
    IOException - in the event of an I/O error.
  - writeChar
```
public void writeChar(int v)
               throws IOException
```
    Writes a character using two output bytes following the general specification of the Java DataOutput interface.
    
    Specified by:
    
    writeChar in interface DataOutput
    
    Parameters:
    
    v - a valid char; due to the two-byte limitation, not all UTF characters are supported
    
    Throws:
    
    IOException - in the event of an I/O error.
  - writeLong
```
public void writeLong(long v)
               throws IOException
```
    Specified by:
    
    writeLong in interface DataOutput
    
    Throws:
    
    IOException
  - writeFloat
```
public void writeFloat(float v)
                throws IOException
```
    Specified by:
    
    writeFloat in interface DataOutput
    
    Throws:
    
    IOException
  - writeDouble
```
public void writeDouble(double v)
                 throws IOException
```
    Specified by:
    
    writeDouble in interface DataOutput
    
    Throws:
    
    IOException
  - writeChars
```
public void writeChars(String s)
                throws IOException
```
    Specified by:
    
    writeChars in interface DataOutput
    
    Throws:
    
    IOException

Class BufferedRandomAccessFile

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BufferedRandomAccessFile

BufferedRandomAccessFile

Method Detail

close

isClosed

flush

getFileSize

getFilePosition

getFile

leReadDouble

leReadFloat

leReadInt

leReadLong

leReadShort

leReadUnsignedShort

leWriteShort

leWriteInt

leWriteLong

leWriteFloat

leWriteDouble

leReadIntArray

leReadFloatArray

leReadShortArray

leReadUTF

leWriteUTF

readBoolean

readByte

readCharASCII

readFully

readFully

readUnsignedByte

readASCII

readASCII

seek

skipBytes

writeByte

writeFully

writeFully

write

write

write

writeBoolean

writeBytes

writeASCII

writeShort

writeInt

writeUTF

readDouble

readFloat

readInt

readLong

readShort

readUnsignedShort

readUTF

readLine

printDiagnostics

readChar

writeChar

writeLong

writeFloat

writeDouble

writeChars