Package java.io

Class RandomAccessFile

java.lang.Object
java.io.RandomAccessFile
All Implemented Interfaces:
Closeable, DataInput, DataOutput, AutoCloseable
public class RandomAccessFile
extends Object
implements DataInput, DataOutput, Closeable
Allows reading from and writing to a file in a random-access manner. This is different from the uni-directional sequential access that a FileInputStream or FileOutputStream provides. If the file is opened in read/write mode, write operations are available as well. The position of the next read or write operation can be moved forwards and backwards after every operation.

  • Constructor Summary

    Constructors
    Constructor Description
    RandomAccessFile​(File file, String mode)
    Constructs a new RandomAccessFile based on file and opens it according to the access string in mode.
    RandomAccessFile​(String fileName, String mode)
    Constructs a new RandomAccessFile based on the file named fileName and opens it according to the access string in mode.

  • Method Summary

    Modifier and Type Method Description
    void close()
    Closes this file.
    protected void finalize()
    Invoked when the garbage collector has detected that this instance is no longer reachable.
    FileChannel getChannel()
    Gets this file's FileChannel object.
    FileDescriptor getFD()
    Gets this file's FileDescriptor.
    long getFilePointer()
    Gets the current position within this file.
    long length()
    Returns the length of this file in bytes.
    int read()
    Reads a single byte from the current position in this file and returns it as an integer in the range from 0 to 255.
    int read​(byte[] buffer)
    Reads bytes from the current position in this file and stores them in the byte array buffer.
    int read​(byte[] buffer, int byteOffset, int byteCount)
    Reads up to byteCount bytes from the current position in this file and stores them in the byte array buffer starting at byteOffset.
    boolean readBoolean()
    Reads a boolean from the current position in this file.
    byte readByte()
    Reads an 8-bit byte from the current position in this file.
    char readChar()
    Reads a big-endian 16-bit character from the current position in this file.
    double readDouble()
    Reads a big-endian 64-bit double from the current position in this file.
    float readFloat()
    Reads a big-endian 32-bit float from the current position in this file.
    void readFully​(byte[] dst)
    Equivalent to readFully(dst, 0, dst.length);.
    void readFully​(byte[] dst, int offset, int byteCount)
    Reads byteCount bytes from this stream and stores them in the byte array dst starting at offset.
    int readInt()
    Reads a big-endian 32-bit integer from the current position in this file.
    String readLine()
    Reads a line of text form the current position in this file.
    long readLong()
    Reads a big-endian 64-bit long from the current position in this file.
    short readShort()
    Reads a big-endian 16-bit short from the current position in this file.
    int readUnsignedByte()
    Reads an unsigned 8-bit byte from the current position in this file and returns it as an integer.
    int readUnsignedShort()
    Reads an unsigned big-endian 16-bit short from the current position in this file and returns it as an integer.
    String readUTF()
    Reads a string that is encoded in modified UTF-8 from this file.
    void seek​(long offset)
    Moves this file's file pointer to a new position, from where following read, write or skip operations are done.
    void setLength​(long newLength)
    Sets the length of this file to newLength.
    int skipBytes​(int count)
    Skips over count bytes in this file.
    void write​(byte[] buffer)
    Writes the entire contents of the byte array buffer to this file, starting at the current file pointer.
    void write​(byte[] buffer, int byteOffset, int byteCount)
    Writes byteCount bytes from the byte array buffer to this file, starting at the current file pointer and using byteOffset as the first position within buffer to get bytes.
    void write​(int oneByte)
    Writes a byte to this file, starting at the current file pointer.
    void writeBoolean​(boolean val)
    Writes a boolean to this file as a single byte (1 for true, 0 for false), starting at the current file pointer.
    void writeByte​(int val)
    Writes an 8-bit byte to this file, starting at the current file pointer.
    void writeBytes​(String str)
    Writes the low order 8-bit bytes from a string to this file, starting at the current file pointer.
    void writeChar​(int val)
    Writes a big-endian 16-bit character to this file, starting at the current file pointer.
    void writeChars​(String str)
    Writes big-endian 16-bit characters from str to this file, starting at the current file pointer.
    void writeDouble​(double val)
    Writes a big-endian 64-bit double to this file, starting at the current file pointer.
    void writeFloat​(float val)
    Writes a big-endian 32-bit float to this file, starting at the current file pointer.
    void writeInt​(int val)
    Writes a big-endian 32-bit integer to this file, starting at the current file pointer.
    void writeLong​(long val)
    Writes a big-endian 64-bit long to this file, starting at the current file pointer.
    void writeShort​(int val)
    Writes a big-endian 16-bit short to this file, starting at the current file pointer.
    void writeUTF​(String str)
    Writes a string encoded with modified UTF-8 to this file, starting at the current file pointer.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • RandomAccessFile

      public RandomAccessFile​(File file, String mode) throws FileNotFoundException
      Constructs a new RandomAccessFile based on file and opens it according to the access string in mode.

      mode may have one of following values:

      "r" The file is opened in read-only mode. An IOException is thrown if any of the write methods is called.
      "rw" The file is opened for reading and writing. If the file does not exist, it will be created.
      "rws" The file is opened for reading and writing. Every change of the file's content or metadata must be written synchronously to the target device.
      "rwd" The file is opened for reading and writing. Every change of the file's content must be written synchronously to the target device.
      Parameters:
      file - the file to open.
      mode - the file access mode, either "r", "rw", "rws" or "rwd".
      Throws:
      FileNotFoundException - if the file cannot be opened or created according to mode.
      IllegalArgumentException - if mode is not "r", "rw", "rws" or "rwd".

    • RandomAccessFile

      public RandomAccessFile​(String fileName, String mode) throws FileNotFoundException
      Constructs a new RandomAccessFile based on the file named fileName and opens it according to the access string in mode. The file path may be specified absolutely or relative to the system property "user.dir".
      Parameters:
      fileName - the name of the file to open.
      mode - the file access mode, either "r", "rw", "rws" or "rwd".
      Throws:
      FileNotFoundException - if the file cannot be opened or created according to mode.
      IllegalArgumentException - if mode is not "r", "rw", "rws" or "rwd".

  • Method Details

    • close

      public void close() throws IOException
      Closes this file.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if an error occurs while closing this file.

    • finalize

      protected void finalize() throws Throwable
      Description copied from class: Object
      Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

      Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

      If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

      Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

      Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • getChannel

      public final FileChannel getChannel()
      Gets this file's FileChannel object.

      The file channel's position is the same as this file's file pointer offset (see getFilePointer()). Any changes made to this file's file pointer offset are also visible in the file channel's position and vice versa.

      Returns:
      this file's file channel instance.

    • getFD

      public final FileDescriptor getFD() throws IOException
      Gets this file's FileDescriptor. This represents the operating system resource for this random access file.
      Returns:
      this file's file descriptor object.
      Throws:
      IOException - if an error occurs while getting the file descriptor of this file.

    • getFilePointer

      public long getFilePointer() throws IOException
      Gets the current position within this file. All reads and writes take place at the current file pointer position.
      Returns:
      the current offset in bytes from the beginning of the file.
      Throws:
      IOException - if an error occurs while getting the file pointer of this file.

    • length

      public long length() throws IOException
      Returns the length of this file in bytes.
      Returns:
      the file's length in bytes.
      Throws:
      IOException - if this file is closed or some other I/O error occurs.

    • read

      public int read() throws IOException
      Reads a single byte from the current position in this file and returns it as an integer in the range from 0 to 255. Returns -1 if the end of the file has been reached. Blocks until one byte has been read, the end of the file is detected, or an exception is thrown.
      Returns:
      the byte read or -1 if the end of the file has been reached.
      Throws:
      IOException - if this file is closed or another I/O error occurs.

    • read

      public int read​(byte[] buffer) throws IOException
      Reads bytes from the current position in this file and stores them in the byte array buffer. The maximum number of bytes read corresponds to the size of buffer. Blocks until at least one byte has been read, the end of the file is detected, or an exception is thrown. Returns the number of bytes actually read or -1 if the end of the file has been reached. See also readFully(byte[]).
      Throws:
      IOException - if this file is closed or another I/O error occurs.

    • read

      public int read​(byte[] buffer, int byteOffset, int byteCount) throws IOException
      Reads up to byteCount bytes from the current position in this file and stores them in the byte array buffer starting at byteOffset. Blocks until at least one byte has been read, the end of the file is detected, or an exception is thrown. Returns the number of bytes actually read or -1 if the end of the stream has been reached. See also readFully(byte[]).
      Throws:
      IndexOutOfBoundsException - if byteOffset < 0 || byteCount < 0 || byteOffset + byteCount > buffer.length.
      IOException - if this file is closed or another I/O error occurs.

    • readBoolean

      public final boolean readBoolean() throws IOException
      Reads a boolean from the current position in this file. Blocks until one byte has been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readBoolean in interface DataInput
      Returns:
      the next boolean value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeBoolean(boolean)

    • readByte

      public final byte readByte() throws IOException
      Reads an 8-bit byte from the current position in this file. Blocks until one byte has been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readByte in interface DataInput
      Returns:
      the next signed 8-bit byte value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeBoolean(boolean)

    • readChar

      public final char readChar() throws IOException
      Reads a big-endian 16-bit character from the current position in this file. Blocks until two bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readChar in interface DataInput
      Returns:
      the next char value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeChar(int)

    • readDouble

      public final double readDouble() throws IOException
      Reads a big-endian 64-bit double from the current position in this file. Blocks until eight bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readDouble in interface DataInput
      Returns:
      the next double value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeDouble(double)

    • readFloat

      public final float readFloat() throws IOException
      Reads a big-endian 32-bit float from the current position in this file. Blocks until four bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readFloat in interface DataInput
      Returns:
      the next float value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeFloat(float)

    • readFully

      public final void readFully​(byte[] dst) throws IOException
      Equivalent to readFully(dst, 0, dst.length);.
      Specified by:
      readFully in interface DataInput
      Throws:
      IOException

    • readFully

      public final void readFully​(byte[] dst, int offset, int byteCount) throws IOException
      Reads byteCount bytes from this stream and stores them in the byte array dst starting at offset. If byteCount is zero, then this method returns without reading any bytes. Otherwise, this method blocks until byteCount bytes have been read. If insufficient bytes are available, EOFException is thrown. If an I/O error occurs, IOException is thrown. When an exception is thrown, some bytes may have been consumed from the stream and written into the array.
      Specified by:
      readFully in interface DataInput
      Parameters:
      dst - the byte array into which the data is read.
      offset - the offset in dst at which to store the bytes.
      byteCount - the number of bytes to read.
      Throws:
      EOFException - if the end of the source stream is reached before enough bytes have been read.
      IndexOutOfBoundsException - if offset < 0 or byteCount < 0, or offset + byteCount > dst.length.
      IOException - if a problem occurs while reading from this stream.
      NullPointerException - if dst is null.

    • readInt

      public final int readInt() throws IOException
      Reads a big-endian 32-bit integer from the current position in this file. Blocks until four bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readInt in interface DataInput
      Returns:
      the next int value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeInt(int)

    • readLine

      public final String readLine() throws IOException
      Reads a line of text form the current position in this file. A line is represented by zero or more characters followed by '\n', '\r', "\r\n" or the end of file marker. The string does not include the line terminating sequence.

      Blocks until a line terminating sequence has been read, the end of the file is reached or an exception is thrown.

      Specified by:
      readLine in interface DataInput
      Returns:
      the contents of the line or null if no characters have been read before the end of the file has been reached.
      Throws:
      IOException - if this file is closed or another I/O error occurs.

    • readLong

      public final long readLong() throws IOException
      Reads a big-endian 64-bit long from the current position in this file. Blocks until eight bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readLong in interface DataInput
      Returns:
      the next long value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeLong(long)

    • readShort

      public final short readShort() throws IOException
      Reads a big-endian 16-bit short from the current position in this file. Blocks until two bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readShort in interface DataInput
      Returns:
      the next short value from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeShort(int)

    • readUnsignedByte

      public final int readUnsignedByte() throws IOException
      Reads an unsigned 8-bit byte from the current position in this file and returns it as an integer. Blocks until one byte has been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readUnsignedByte in interface DataInput
      Returns:
      the next unsigned byte value from this file as an int.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeByte(int)

    • readUnsignedShort

      public final int readUnsignedShort() throws IOException
      Reads an unsigned big-endian 16-bit short from the current position in this file and returns it as an integer. Blocks until two bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readUnsignedShort in interface DataInput
      Returns:
      the next unsigned short value from this file as an int.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      writeShort(int)

    • readUTF

      public final String readUTF() throws IOException
      Reads a string that is encoded in modified UTF-8 from this file. The number of bytes that must be read for the complete string is determined by the first two bytes read from the file. Blocks until all required bytes have been read, the end of the file is reached or an exception is thrown.
      Specified by:
      readUTF in interface DataInput
      Returns:
      the next string encoded in modified UTF-8 from this file.
      Throws:
      EOFException - if the end of this file is detected.
      IOException - if this file is closed or another I/O error occurs.
      UTFDataFormatException - if the bytes read cannot be decoded into a character string.
      See Also:
      writeUTF(String)

    • seek

      public void seek​(long offset) throws IOException
      Moves this file's file pointer to a new position, from where following read, write or skip operations are done. The position may be greater than the current length of the file, but the file's length will only change if the moving of the pointer is followed by a write operation.
      Parameters:
      offset - the new file pointer position.
      Throws:
      IOException - if this file is closed, pos < 0 or another I/O error occurs.

    • setLength

      public void setLength​(long newLength) throws IOException
      Sets the length of this file to newLength. If the current file is smaller, it is expanded but the contents from the previous end of the file to the new end are undefined. The file is truncated if its current size is bigger than newLength. If the current file pointer position is in the truncated part, it is set to the end of the file.
      Parameters:
      newLength - the new file length in bytes.
      Throws:
      IllegalArgumentException - if newLength < 0.
      IOException - if this file is closed or another I/O error occurs.

    • skipBytes

      public int skipBytes​(int count) throws IOException
      Skips over count bytes in this file. Less than count bytes are skipped if the end of the file is reached or an exception is thrown during the operation. Nothing is done if count is negative.
      Specified by:
      skipBytes in interface DataInput
      Parameters:
      count - the number of bytes to skip.
      Returns:
      the number of bytes actually skipped.
      Throws:
      IOException - if this file is closed or another I/O error occurs.

    • write

      public void write​(byte[] buffer) throws IOException
      Writes the entire contents of the byte array buffer to this file, starting at the current file pointer.
      Specified by:
      write in interface DataOutput
      Parameters:
      buffer - the buffer to write.
      Throws:
      IOException - if an I/O error occurs while writing to this file.

    • write

      public void write​(byte[] buffer, int byteOffset, int byteCount) throws IOException
      Writes byteCount bytes from the byte array buffer to this file, starting at the current file pointer and using byteOffset as the first position within buffer to get bytes.
      Specified by:
      write in interface DataOutput
      Parameters:
      buffer - the buffer to write.
      byteOffset - the index of the first byte in buffer to write.
      byteCount - the number of bytes from the buffer to write.
      Throws:
      IndexOutOfBoundsException - if byteCount < 0, byteOffset < 0 or byteCount + byteOffset is greater than the size of buffer.
      IOException - if an I/O error occurs while writing to this file.

    • write

      public void write​(int oneByte) throws IOException
      Writes a byte to this file, starting at the current file pointer. Only the least significant byte of the integer oneByte is written.
      Specified by:
      write in interface DataOutput
      Parameters:
      oneByte - the byte to write to this file.
      Throws:
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      read()

    • writeBoolean

      public final void writeBoolean​(boolean val) throws IOException
      Writes a boolean to this file as a single byte (1 for true, 0 for false), starting at the current file pointer.
      Specified by:
      writeBoolean in interface DataOutput
      Parameters:
      val - the boolean to write to this file.
      Throws:
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      readBoolean()

    • writeByte

      public final void writeByte​(int val) throws IOException
      Writes an 8-bit byte to this file, starting at the current file pointer. Only the least significant byte of the integer val is written.
      Specified by:
      writeByte in interface DataOutput
      Parameters:
      val - the byte to write to this file.
      Throws:
      IOException - if this file is closed or another I/O error occurs.
      See Also:
      readByte(), readUnsignedByte()

    • writeBytes

      public final void writeBytes​(String str) throws IOException
      Writes the low order 8-bit bytes from a string to this file, starting at the current file pointer.
      Specified by:
      writeBytes in interface DataOutput
      Parameters:
      str - the string containing the bytes to write to this file
      Throws:
      IOException - if an I/O error occurs while writing to this file.

    • writeChar

      public final void writeChar​(int val) throws IOException
      Writes a big-endian 16-bit character to this file, starting at the current file pointer. Only the two least significant bytes of the integer val are written, with the high byte first.
      Specified by:
      writeChar in interface DataOutput
      Parameters:
      val - the char to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readChar()

    • writeChars

      public final void writeChars​(String str) throws IOException
      Writes big-endian 16-bit characters from str to this file, starting at the current file pointer.
      Specified by:
      writeChars in interface DataOutput
      Parameters:
      str - the string to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readChar()

    • writeDouble

      public final void writeDouble​(double val) throws IOException
      Writes a big-endian 64-bit double to this file, starting at the current file pointer. The bytes are those returned by Double.doubleToLongBits(double), meaning a canonical NaN is used.
      Specified by:
      writeDouble in interface DataOutput
      Parameters:
      val - the double to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readDouble()

    • writeFloat

      public final void writeFloat​(float val) throws IOException
      Writes a big-endian 32-bit float to this file, starting at the current file pointer. The bytes are those returned by Float.floatToIntBits(float), meaning a canonical NaN is used.
      Specified by:
      writeFloat in interface DataOutput
      Parameters:
      val - the float to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readFloat()

    • writeInt

      public final void writeInt​(int val) throws IOException
      Writes a big-endian 32-bit integer to this file, starting at the current file pointer.
      Specified by:
      writeInt in interface DataOutput
      Parameters:
      val - the int to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readInt()

    • writeLong

      public final void writeLong​(long val) throws IOException
      Writes a big-endian 64-bit long to this file, starting at the current file pointer.
      Specified by:
      writeLong in interface DataOutput
      Parameters:
      val - the long to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readLong()

    • writeShort

      public final void writeShort​(int val) throws IOException
      Writes a big-endian 16-bit short to this file, starting at the current file pointer. Only the two least significant bytes of the integer val are written.
      Specified by:
      writeShort in interface DataOutput
      Parameters:
      val - the short to write to this file.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      See Also:
      readShort(), DataInput.readUnsignedShort()

    • writeUTF

      public final void writeUTF​(String str) throws IOException
      Writes a string encoded with modified UTF-8 to this file, starting at the current file pointer.
      Specified by:
      writeUTF in interface DataOutput
      Parameters:
      str - the string to write in modified UTF-8 format.
      Throws:
      IOException - if an I/O error occurs while writing to this file.
      UTFDataFormatException - if the encoded string is longer than 65535 bytes.
      See Also:
      readUTF()