Skip to content

Most visited

Recently visited

navigation
Added in API level 1

RandomAccessFile

public class RandomAccessFile
extends Object implements DataInput, DataOutput, Closeable

java.lang.Object
   ↳ java.io.RandomAccessFile


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.

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 up to 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.

Inherited methods

From class java.lang.Object
From interface java.io.DataInput
From interface java.io.DataOutput
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Public constructors

RandomAccessFile

Added in API level 1
RandomAccessFile (File file, 
                String mode)

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 File: the file to open.
mode String: 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

Added in API level 1
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. The file path may be specified absolutely or relative to the system property "user.dir".

Parameters
fileName String: the name of the file to open.
mode String: 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

close

Added in API level 1
void close ()

Closes this file.

Throws
IOException if an error occurs while closing this file.

getChannel

Added in API level 1
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
FileChannel this file's file channel instance.

getFD

Added in API level 1
FileDescriptor getFD ()

Gets this file's FileDescriptor. This represents the operating system resource for this random access file.

Returns
FileDescriptor this file's file descriptor object.
Throws
IOException if an error occurs while getting the file descriptor of this file.

getFilePointer

Added in API level 1
long getFilePointer ()

Gets the current position within this file. All reads and writes take place at the current file pointer position.

Returns
long 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

Added in API level 1
long length ()

Returns the length of this file in bytes.

Returns
long the file's length in bytes.
Throws
IOException if this file is closed or some other I/O error occurs.

read

Added in API level 1
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. 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[]).

Parameters
buffer byte
byteOffset int
byteCount int
Returns
int
Throws
IndexOutOfBoundsException if byteOffset < 0 || byteCount < 0 || byteOffset + byteCount > buffer.length.
IOException if this file is closed or another I/O error occurs.

read

Added in API level 1
int read (byte[] buffer)

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[]).

Parameters
buffer byte
Returns
int
Throws
IOException if this file is closed or another I/O error occurs.

read

Added in API level 1
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. 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
int 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.

readBoolean

Added in API level 1
boolean readBoolean ()

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
boolean 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:

readByte

Added in API level 1
byte readByte ()

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
byte 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:

readChar

Added in API level 1
char readChar ()

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
char 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:

readDouble

Added in API level 1
double readDouble ()

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
double 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:

readFloat

Added in API level 1
float readFloat ()

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
float 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:

readFully

Added in API level 1
void readFully (byte[] dst)

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

Parameters
dst byte
Throws
IOException

readFully

Added in API level 1
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. 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 byte: the byte array into which the data is read.
offset int: the offset in dst at which to store the bytes.
byteCount int: 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

Added in API level 1
int readInt ()

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
int 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:

readLine

Added in API level 1
String readLine ()

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
String 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

Added in API level 1
long readLong ()

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
long 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:

readShort

Added in API level 1
short readShort ()

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
short 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:

readUTF

Added in API level 1
String readUTF ()

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
String 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:

readUnsignedByte

Added in API level 1
int readUnsignedByte ()

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
int 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:

readUnsignedShort

Added in API level 1
int readUnsignedShort ()

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
int 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:

seek

Added in API level 1
void seek (long offset)

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 long: the new file pointer position.
Throws
IOException if this file is closed, pos < 0 or another I/O error occurs.

setLength

Added in API level 1
void setLength (long newLength)

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 long: the new file length in bytes.
Throws
IllegalArgumentException if newLength < 0.
IOException if this file is closed or another I/O error occurs.

skipBytes

Added in API level 1
int skipBytes (int count)

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 int: the number of bytes to skip.
Returns
int the number of bytes actually skipped.
Throws
IOException if this file is closed or another I/O error occurs.

write

Added in API level 1
void write (int oneByte)

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 int: the byte to write to this file.
Throws
IOException if this file is closed or another I/O error occurs.

See also:

write

Added in API level 1
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.

Parameters
buffer byte: the buffer to write.
byteOffset int: the index of the first byte in buffer to write.
byteCount int: 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

Added in API level 1
void write (byte[] buffer)

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

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

writeBoolean

Added in API level 1
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.

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

See also:

writeByte

Added in API level 1
void writeByte (int val)

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 int: the byte to write to this file.
Throws
IOException if this file is closed or another I/O error occurs.

See also:

writeBytes

Added in API level 1
void writeBytes (String str)

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

Parameters
str String: the string containing the bytes to write to this file
Throws
IOException if an I/O error occurs while writing to this file.

writeChar

Added in API level 1
void writeChar (int val)

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 int: the char to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.

See also:

writeChars

Added in API level 1
void writeChars (String str)

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

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

See also:

writeDouble

Added in API level 1
void writeDouble (double val)

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 double: the double to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.

See also:

writeFloat

Added in API level 1
void writeFloat (float val)

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 float: the float to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.

See also:

writeInt

Added in API level 1
void writeInt (int val)

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

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

See also:

writeLong

Added in API level 1
void writeLong (long val)

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

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

See also:

writeShort

Added in API level 1
void writeShort (int val)

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 int: the short to write to this file.
Throws
IOException if an I/O error occurs while writing to this file.

See also:

writeUTF

Added in API level 1
void writeUTF (String str)

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

Parameters
str String: 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

finalize

Added in API level 1
void finalize ()

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
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.