Package org.tinfour.io

Class 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 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 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()
      Reads an 8-byte IEEE-754 floating-point value given in little-endian order.
      float leReadFloat()
      Reads a 4-byte IEEE-754 floating-point value given in little-endian order.
      void leReadFloatArray​(float[] array, int arrayOffset, int length)
      Read an array of floats accessing them in little-endian order.
      int leReadInt()
      Reads a 4-byte integer given in little-endian order.
      void leReadIntArray​(int[] array, int arrayOffset, int length)
      Reads an array of integers accessing them in little-endian order.
      long leReadLong()
      Reads an 8-byte integer given in little-endian order.
      short leReadShort()
      Reads an 2-byte integer given in little-endian order.
      int leReadUnsignedShort()
      Reads an 2-byte integer given in little-endian order, treating it as an unsigned value.
      void leWriteDouble​(double v)
      Writes an 8-byte IEEE-754 floating-point value output in little-endian order.
      void leWriteFloat​(float v)
      Writes an 4-byte IEEE-754 floating-point value output in little-endian order.
      void leWriteInt​(int value)
      Writes an 4-byte integer given in little-endian order.
      void leWriteLong​(long v)
      Writes an 8-byte integer output in little-endian order.
      void leWriteShort​(int v)
      Writes an 2-byte integer given in little-endian 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 linhe 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 unsignd 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)
      Write the content of the string as a sequence of characters in the range of the ASCII character set.
      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)
      Write the content of the specified array
      void writeFully​(byte[] array, int arrayOffset, int length)
      Write the specified number of bytes from the byte array starting at the indicated offset (array index).
      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.

    • 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

      • 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.
        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
        Reads an 8-byte IEEE-754 floating-point value given in little-endian order.
        Returns:
        a floating-point value, potentially NaN or INFINITY
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leReadFloat

        public float leReadFloat()
                  throws IOException
        Reads a 4-byte IEEE-754 floating-point value given in little-endian order.
        Returns:
        a floating-point value, potentially NaN or INFINITY
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leReadInt

        public int leReadInt()
              throws IOException
        Reads a 4-byte integer given in little-endian order.
        Returns:
        a valid integer
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leReadLong

        public long leReadLong()
                throws IOException
        Reads an 8-byte integer given in little-endian order.
        Returns:
        a valid integer
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leReadShort

        public short leReadShort()
                  throws IOException
        Reads an 2-byte integer given in little-endian order.
        Returns:
        a valid Java short
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leReadUnsignedShort

        public int leReadUnsignedShort()
                        throws IOException
        Reads an 2-byte integer given in little-endian order, treating it as an unsigned value.
        Returns:
        a Java int with a positive value
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leWriteShort

        public void leWriteShort​(int v)
                  throws IOException
        Writes an 2-byte integer given in little-endian order.
        Parameters:
        v - an integral value.
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leWriteInt

        public void leWriteInt​(int value)
                throws IOException
        Writes an 4-byte integer given in little-endian order.
        Parameters:
        value - an integral value.
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leWriteLong

        public void leWriteLong​(long v)
                 throws IOException
        Writes an 8-byte integer output in little-endian order.
        Parameters:
        v - an integral value.
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leWriteFloat

        public void leWriteFloat​(float v)
                  throws IOException
        Writes an 4-byte IEEE-754 floating-point value output in little-endian order.
        Parameters:
        v - an integral value.
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

      • leWriteDouble

        public void leWriteDouble​(double v)
                   throws IOException
        Writes an 8-byte IEEE-754 floating-point value output in little-endian order.
        Parameters:
        v - an integral value.
        Throws:
        IOException - in the event of an unrecoverable I/O exception.

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

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

      • writeFully

        public void writeFully​(byte[] array)
                throws IOException
        Write the content of the specified array
        Parameters:
        array - a valid array
        Throws:
        IOException - in the event of an unhandled I/O exception.

      • writeFully

        public void writeFully​(byte[] array,
                       int arrayOffset,
                       int length)
                throws IOException
        Write the specified number of bytes from the byte array starting at the indicated offset (array index).
        Parameters:
        array - a valid array
        arrayOffset - the starting index into the array.
        length - the number of bytes to be written.
        Throws:
        IOException - in the event of an unhandled I/O exception.

      • 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

      • writeASCII

        public void writeASCII​(String s,
                       int nBytes)
                throws IOException
        Write the content of the string as a sequence of characters in the range of the ASCII character set. If the length of the output string exceeds the specified number of bytes, the string is truncated. If the length of the string is less than the specified number of bytes, zeroes are written to the output.
        Parameters:
        s - a valid string.
        nBytes - the number of bytes to be written to the file.
        Throws:
        IOException - in the event of an unhandled I/O exception.

      • 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 unsignd 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 linhe 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.