public class

RandomAccessFile

extends Object
implements Closeable DataInput DataOutput
java.lang.Object
   ↳ java.io.RandomAccessFile

Class Overview

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.

Summary

Public Constructors
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.
Public Methods
void close()
Closes this file.
synchronized final FileChannel getChannel()
Gets this file's FileChannel object.
final 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(byte[] buffer, int byteOffset, int byteCount)
Reads at most byteCount bytes from the current position in this file and stores them in the byte array buffer starting at byteOffset.
int read(byte[] buffer)
Reads bytes from the current position in this file and stores them in the byte array buffer.
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.
final boolean readBoolean()
Reads a boolean from the current position in this file.
final byte readByte()
Reads an 8-bit byte from the current position in this file.
final char readChar()
Reads a big-endian 16-bit character from the current position in this file.
final double readDouble()
Reads a big-endian 64-bit double from the current position in this file.
final float readFloat()
Reads a big-endian 32-bit float from the current position in this file.
final void readFully(byte[] dst)
Equivalent to readFully(dst, 0, dst.length);.
final 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.
final int readInt()
Reads a big-endian 32-bit integer from the current position in this file.
final String readLine()
Reads a line of text form the current position in this file.
final long readLong()
Reads a big-endian 64-bit long from the current position in this file.
final short readShort()
Reads a big-endian 16-bit short from the current position in this file.
final String readUTF()
Reads a string that is encoded in modified UTF-8 from this file.
final int readUnsignedByte()
Reads an unsigned 8-bit byte from the current position in this file and returns it as an integer.
final int readUnsignedShort()
Reads an unsigned big-endian 16-bit short from the current position in this file and returns it as an integer.
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(int oneByte)
Writes a byte 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(byte[] buffer)
Writes the entire contents of the byte array buffer to this file, starting at the current file pointer.
final 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.
final void writeByte(int val)
Writes an 8-bit byte to this file, starting at the current file pointer.
final void writeBytes(String str)
Writes the low order 8-bit bytes from a string to this file, starting at the current file pointer.
final void writeChar(int val)
Writes a big-endian 16-bit character to this file, starting at the current file pointer.
final void writeChars(String str)
Writes big-endian 16-bit characters from str to this file, starting at the current file pointer.
final void writeDouble(double val)
Writes a big-endian 64-bit double to this file, starting at the current file pointer.
final void writeFloat(float val)
Writes a big-endian 32-bit float to this file, starting at the current file pointer.
final void writeInt(int val)
Writes a big-endian 32-bit integer to this file, starting at the current file pointer.
final void writeLong(long val)
Writes a big-endian 64-bit long to this file, starting at the current file pointer.
final void writeShort(int val)
Writes a big-endian 16-bit short to this file, starting at the current file pointer.
final void writeUTF(String str)
Writes a string encoded with modified UTF-8 to this file, starting at the current file pointer.
Protected Methods
void finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.io.DataInput
From interface java.io.DataOutput

Public Constructors

public RandomAccessFile (File file, String mode)

Since: API Level 1

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

public RandomAccessFile (String fileName, String mode)

Since: API Level 1

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

Public Methods

public void close ()

Since: API Level 1

Closes this file.

Throws
IOException if an error occurs while closing this file.

public final synchronized FileChannel getChannel ()

Since: API Level 1

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.

public final FileDescriptor getFD ()

Since: API Level 1

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.

public long getFilePointer ()

Since: API Level 1

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.

public long length ()

Since: API Level 1

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.

public int read (byte[] buffer, int byteOffset, int byteCount)

Since: API Level 1

Reads at most 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.
Throws
IndexOutOfBoundsException if byteOffset < 0 or byteCount < 0, or if byteOffset + byteCount is greater than the size of buffer.
IOException if this file is closed or another I/O error occurs.

public int read (byte[] buffer)

Since: API Level 1

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.

Parameters
buffer the byte array in which to store the bytes read.
Returns
  • the number of bytes actually 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.

public int read ()

Since: API Level 1

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.

public final boolean readBoolean ()

Since: API Level 1

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.

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.

public final byte readByte ()

Since: API Level 1

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.

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.

public final char readChar ()

Since: API Level 1

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.

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

public final double readDouble ()

Since: API Level 1

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.

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.

public final float readFloat ()

Since: API Level 1

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.

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.

public final void readFully (byte[] dst)

Since: API Level 1

Equivalent to readFully(dst, 0, dst.length);.

Throws
IOException

public final void readFully (byte[] dst, int offset, int byteCount)

Since: API Level 1

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.

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.

public final int readInt ()

Since: API Level 1

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.

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

public final String readLine ()

Since: API Level 1

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.

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.

public final long readLong ()

Since: API Level 1

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.

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

public final short readShort ()

Since: API Level 1

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.

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

public final String readUTF ()

Since: API Level 1

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.

Returns
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

public final int readUnsignedByte ()

Since: API Level 1

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.

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

public final int readUnsignedShort ()

Since: API Level 1

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.

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

public void seek (long offset)

Since: API Level 1

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.

public void setLength (long newLength)

Since: API Level 1

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.

public int skipBytes (int count)

Since: API Level 1

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.

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.

public void write (int oneByte)

Since: API Level 1

Writes a byte to this file, starting at the current file pointer. Only the least significant byte of the integer oneByte is written.

Parameters
oneByte the byte to write to this file.
Throws
IOException if this file is closed or another I/O error occurs.
See Also

public void write (byte[] buffer, int byteOffset, int byteCount)

Since: API Level 1

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.

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.

public void write (byte[] buffer)

Since: API Level 1

Writes the entire contents of the byte array buffer to this file, starting at the current file pointer.

Parameters
buffer the buffer to write.
Throws
IOException if an I/O error occurs while writing to this file.

public final void writeBoolean (boolean val)

Since: API Level 1

Writes a boolean to this file as a single byte (1 for true, 0 for false), starting at the current file pointer.

Parameters
val the boolean to write to this file.
Throws
IOException if this file is closed or another I/O error occurs.
See Also

public final void writeByte (int val)

Since: API Level 1

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.

Parameters
val the byte to write to this file.
Throws
IOException if this file is closed or another I/O error occurs.

public final void writeBytes (String str)

Since: API Level 1

Writes the low order 8-bit bytes from a string to this file, starting at the current file pointer.

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.

public final void writeChar (int val)

Since: API Level 1

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.

Parameters
val the char to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeChars (String str)

Since: API Level 1

Writes big-endian 16-bit characters from str to this file, starting at the current file pointer.

Parameters
str the string to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeDouble (double val)

Since: API Level 1

Writes a big-endian 64-bit double to this file, starting at the current file pointer. The bytes are those returned by doubleToLongBits(double), meaning a canonical NaN is used.

Parameters
val the double to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeFloat (float val)

Since: API Level 1

Writes a big-endian 32-bit float to this file, starting at the current file pointer. The bytes are those returned by floatToIntBits(float), meaning a canonical NaN is used.

Parameters
val the float to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeInt (int val)

Since: API Level 1

Writes a big-endian 32-bit integer to this file, starting at the current file pointer.

Parameters
val the int to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeLong (long val)

Since: API Level 1

Writes a big-endian 64-bit long to this file, starting at the current file pointer.

Parameters
val the long to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

public final void writeShort (int val)

Since: API Level 1

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.

Parameters
val the short to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.

public final void writeUTF (String str)

Since: API Level 1

Writes a string encoded with modified UTF-8 to this file, starting at the current file pointer.

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

Protected Methods

protected void finalize ()

Since: API Level 1

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.

Throws
Throwable