Package java.io

Class 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

      All Methods Instance Methods Concrete Methods 
      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.

    • Constructor Detail

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

      • 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. Closing the channel closes the RandomAccessFile as well. The instance of FileChannel returned is always the same even if the RandomAccessFile or the FileChannel have been closed.

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