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 offset, int count)
Reads at most count bytes from the current position in this file and stores them in the byte array buffer starting at offset.
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.
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 16-bit character from the current position in this file.
final double readDouble()
Reads a 64-bit double from the current position in this file.
final float readFloat()
Reads a 32-bit float from the current position in this file.
final void readFully(byte[] buffer, int offset, int count)
Read bytes from this file into buffer starting at offset offset.
final void readFully(byte[] buffer)
Reads bytes from this file into buffer.
final int readInt()
Reads a 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 64-bit long from the current position in this file.
final short readShort()
Reads a 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 16-bit short from the current position in this file and returns it as an integer.
void seek(long pos)
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, int offset, int count)
Writes count bytes from the byte array buffer to this file, starting at the current file pointer and using offset 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 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, 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 16-bit character to this file, starting at the current file pointer.
final void writeChars(String str)
Writes the 16-bit characters from a string to this file, starting at the current file pointer.
final void writeDouble(double val)
Writes a 64-bit double to this file, starting at the current file pointer.
final void writeFloat(float val)
Writes a 32-bit float to this file, starting at the current file pointer.
final void writeInt(int val)
Writes a 32-bit integer to this file, starting at the current file pointer.
final void writeLong(long val)
Writes a 64-bit long to this file, starting at the current file pointer.
final void writeShort(int val)
Writes a 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.
[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".
SecurityException if a SecurityManager is installed and it denies access request according to mode.
See Also

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".
SecurityException if a SecurityManager is installed and it denies access request according to mode.
See Also

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 offset, int count)

Since: API Level 1

Reads at most count bytes from the current position in this file and stores them in the byte array buffer starting at offset. Blocks until count bytes have been read, the end of the file is reached or an exception is thrown.

Parameters
buffer the array in which to store the bytes read from this file.
offset the initial position in buffer to store the bytes read from this file.
count the maximum number of bytes to store in buffer.
Returns
  • the number of bytes actually read or -1 if the end of the stream has been reached.
Throws
IndexOutOfBoundsException if offset < 0 or count < 0, or if offset + count is greater than the size of buffer.
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 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.

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 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.
See Also

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.
See Also

public final char readChar ()

Since: API Level 1

Reads a 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 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.
See Also

public final float readFloat ()

Since: API Level 1

Reads a 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.
See Also

public final void readFully (byte[] buffer, int offset, int count)

Since: API Level 1

Read bytes from this file into buffer starting at offset offset. This method blocks until count number of bytes have been read.

Parameters
buffer the buffer to read bytes into.
offset the initial position in buffer to store the bytes read from this file.
count the maximum number of bytes to store in buffer.
Throws
EOFException if the end of this file is detected.
IndexOutOfBoundsException if offset < 0 or count < 0, or if offset + count is greater than the length of buffer.
IOException if this file is closed or another I/O error occurs.
NullPointerException if buffer is null.

public final void readFully (byte[] buffer)

Since: API Level 1

Reads bytes from this file into buffer. Blocks until buffer.length number of bytes have been read, the end of the file is reached or an exception is thrown.

Parameters
buffer the buffer to read bytes into.
Throws
EOFException if the end of this file is detected.
IOException if this file is closed or another I/O error occurs.
NullPointerException if buffer is null.

public final int readInt ()

Since: API Level 1

Reads a 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 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 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 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 pos)

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
pos 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 (byte[] buffer, int offset, int count)

Since: API Level 1

Writes count bytes from the byte array buffer to this file, starting at the current file pointer and using offset as the first position within buffer to get bytes.

Parameters
buffer the buffer to write to this file.
offset the index of the first byte in buffer to write.
count the number of bytes from buffer to write.
Throws
IndexOutOfBoundsException if count < 0, offset < 0 or count + offset is greater than the size of buffer.
IOException if an I/O error occurs while writing to this file.
See Also

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)

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.
See Also

public final void writeBoolean (boolean val)

Since: API Level 1

Writes a boolean to this file, 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.
See Also

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.
See Also

public final void writeChar (int val)

Since: API Level 1

Writes a 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 the 16-bit characters from a string to this file, starting at the current file pointer. Each character is written in the same way as with writeChar(int), with its high byte first.

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 64-bit double to this file, starting at the current file pointer. The eight bytes returned by doubleToLongBits(double) are written to this file.

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 32-bit float to this file, starting at the current file pointer. The four bytes returned by floatToIntBits(float) are written to this file.

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 32-bit integer to this file, starting at the current file pointer. The four bytes of the integer are written with the highest byte first.

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 64-bit long to this file, starting at the current file pointer. The eight bytes of the long are written with the highest byte first.

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 16-bit short 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 short to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.
See Also

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