22.23 The Class java.io.RandomAccessFile

A random access file behaves like a large array of bytes stored in the file system. There is a kind of cursor, or index into the implied array, called the file pointer; input operations read bytes starting at the file pointer and advance the file pointer past the bytes read. If the random access file is created in read/write mode, then output operations are also available; output operations write bytes starting at the file pointer and advance the file pointer past the bytes written. Output operations that write past the current end of the implied array cause the array to be extended. The file pointer can be read by the getFilePointer method and set by the seek method.

public class RandomAccessFile implements DataOutput, DataInput {
	public RandomAccessFile(String path, String mode)
		throws SecurityException, IOException,
			IllegalArgumentException;
	public RandomAccessFile(File file, String mode)
		throws SecurityException, IOException,
			IllegalArgumentException;
	public final FileDescriptor getFD() throws IOException;
	public native long getFilePointer() throws IOException;
	public native void seek(long pos) throws IOException;
	public native long length() throws IOException;
	public native void close() throws IOException;
	public native int read() throws IOException;
	public int read(byte[] b)
		throws IOException, NullPointerException;
	public int read(byte[] b, int off, int len)
		throws IOException, NullPointerException,
			IndexOutOfBoundsException;
	// The methods that implement interface DataInput:
	public final void readFully(byte[] b)
		throws IOException, NullPointerException;
	public final void readFully(byte[] b, int off, int len)
		throws IOException, NullPointerException,
			IndexOutOfBoundsException;
	public int skipBytes(int n) throws IOException;
	public final boolean readBoolean() throws IOException;
	public final byte readByte() throws IOException;
	public final int readUnsignedByte() throws IOException;
	public final short readShort() throws IOException;
	public final int readUnsignedShort() throws IOException;
	public final char readChar() throws IOException;
	public final int readInt() throws IOException;
	public final long readLong() throws IOException;
	public final float readFloat() throws IOException;
	public final double readDouble() throws IOException;
	public final String readLine() throws IOException;
	public final String readUTF() throws IOException;
	// The methods that implement interface DataOutput:
	public native void write(int b) throws IOException;
	public void write(byte[] b)
		throws IOException, NullPointerException;
	public void write(byte[] b, int off, int len)
		throws IOException, NullPointerException,
			IndexOutOfBoundsException;
	public final void writeBoolean(boolean v) throws IOException;
	public final void writeByte(int v) throws IOException;
	public final void writeShort(int v) throws IOException;
	public final void writeChar(int v) throws IOException;
	public final void writeInt(int v) throws IOException;
	public final void writeLong(long v) throws IOException;
	public final void writeFloat(float v) throws IOException;
	public final void writeDouble(double v) throws IOException;
	public final void writeBytes(String s) throws IOException;
	public final void writeChars(String s) throws IOException;
	public final void writeUTF(String str) throws IOException;
}

It is generally true of all the reading routines in this class that if end of file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the stream has been closed (§22.23.7).

22.23.1 public RandomAccessFile(String path, String mode)
throws SecurityException, IOException, IllegalArgumentException

This constructor initializes a newly created RandomAccessFile by opening a connection to an actual file, the file named by the path name path in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path argument as its argument.

Next, if mode is "rw" and there is a security manager, its checkWrite method (§20.17.21) is called with the path argument as its argument.

If mode is "rw", then the file may be both read and written. If mode is "r", then the file may be read but may not be written (every write method for this object will simply throw an IOException). If mode is not "r" or "rw", then this constructor throws an IllegalArgumentException.

22.23.2 public RandomAccessFile(File file, String mode)
throws SecurityException, IOException, IllegalArgumentException

This constructor initializes a newly created RandomAccessFile by opening a connection to an actual file, the file named by file in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by the file argument as its argument.

Next, if mode is "rw" and there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by the file argument as its argument.

If mode is "rw", then the file may be both read and written. If mode is "r", then the file may be read but may not be written (every write method for this object will simply throw an IOException). If mode is not "r" or "rw", then this constructor throws an IllegalArgumentException.

22.23.3 public final FileDescriptor getFD() throws IOException

This method returns the FileDescriptor object (§22.26) that represents the connection to the actual file in the file system being used by this RandomAccessFile.

22.23.4 public long getFilePointer() throws IOException

The current file pointer for this random access file is returned. An IOException is thrown if the file pointer cannot be read for any reason.

22.23.5 public void seek(long pos) throws IOException

The file pointer for this random access file is set to pos, which is a position within the file, measured in bytes. Position 0 is the start of the file. An IOException is thrown if pos is less than zero or greater than the length of the file, or if the file pointer cannot be set for any other reason.

22.23.6 public long length() throws IOException

The length of this random access file, measured in bytes, is returned.

An IOException is thrown if the length cannot be read for any reason.

22.23.7 public void close() throws IOException

This random access file is closed. A closed random access file cannot perform input or output operations and cannot be reopened.

22.23.8 public int read() throws IOException

This method reads one byte from the random access file. The byte is returned as an integer in the range 0 to 255 (0x00-0xff). If no byte is available because the file pointer is at end of file, the value -1 is returned.

If the byte cannot be read for any reason other than end of file, an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed (§22.23.7).

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.1).

22.23.9 public int read(byte[] b)
throws IOException, NullPointerException

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.2).

22.23.10 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.3).

22.23.11 public final void readFully(byte[] b)
throws IOException, NullPointerException

See the general contract of the readFully method of DataInput (§22.1.1).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.12 public final void readFully(byte[] b, int off, int len) throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the readFully method of DataInput (§22.1.2).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.13 public int skipBytes(int n) throws IOException

See the general contract of the skipBytes method of DataInput (§22.1.3).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.14 public final boolean readBoolean() throws IOException

See the general contract of the readBoolean method of DataInput (§22.1.4).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.15 public final byte readByte() throws IOException

See the general contract of the readByte method of DataInput (§22.1.5).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.16 public final int readUnsignedByte() throws IOException

See the general contract of the readUnsignedByte method of DataInput (§22.1.6).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.17 public final short readShort() throws IOException

See the general contract of the readShort method of DataInput (§22.1.7).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.18 public final int readUnsignedShort() throws IOException

See the general contract of the readUnsignedShort method of DataInput (§22.1.8).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.19 public final char readChar() throws IOException

See the general contract of the readChar method of DataInput (§22.1.9).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.20 public final int readInt() throws IOException

See the general contract of the readInt method of DataInput (§22.1.10).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.21 public final long readLong() throws IOException

See the general contract of the readLong method of DataInput (§22.1.11).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.22 public final float readFloat() throws IOException

See the general contract of the readFloat method of DataInput (§22.1.12).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.23 public final double readDouble() throws IOException

See the general contract of the readDouble method of DataInput (§22.1.13).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.24 public final String readLine() throws IOException

See the general contract of the readLine method of DataInput (§22.1.14).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.25 public final String readUTF() throws IOException

See the general contract of the readUTF method of DataInput (§22.1.15).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.26 public void write(int b) throws IOException;

See the general contract of the write method of DataOutput (§22.2.1).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.27 public void write(byte[] b)
throws IOException, NullPointerException

See the general contract of the write method of DataOutput (§22.2.2).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.28 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the write method of DataOutput (§22.2.3).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.29 public final void writeBoolean(boolean v)
throws IOException

See the general contract of the writeBoolean method of DataOutput (§22.2.4).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.30 public final void writeByte(int v) throws IOException

See the general contract of the writeByte method of DataOutput (§22.2.5).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.31 public final void writeShort(int v) throws IOException

See the general contract of the writeShort method of DataOutput (§22.2.6).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.32 public final void writeChar(int v) throws IOException

See the general contract of the writeChar method of DataOutput (§22.2.7).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.33 public final void writeInt(int v) throws IOException

See the general contract of the writeInt method of DataOutput (§22.2.8).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.34 public final void writeLong(long v) throws IOException

See the general contract of the writeLong method of DataOutput (§22.2.9).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.35 public final void writeFloat(float v) throws IOException

See the general contract of the writeFloat method of DataOutput (§22.2.10).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.36 public final void writeDouble(double v)
throws IOException

See the general contract of the writeDouble method of DataOutput (§22.2.11).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.37 public final void writeBytes(String s) throws IOException

See the general contract of the writeBytes method of DataOutput (§22.2.12).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.38 public final void writeChars(String s) throws IOException

See the general contract of the writeChars method of DataOutput (§22.2.13).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.39 public final void writeUTF(String str) throws IOException

See the general contract of the writeUTF method of DataOutput (§22.2.14).

Bytes for this operation are written to the random access file, starting at the current file pointer.