Package java.io

Previous

Java API

Index

Next

Class RandomAccessFile

public  class  java.io.RandomAccessFile
    extends  java.lang.Object  
    implements java.io.DataOutput  ,
               java.io.DataInput  
{
        // Constructors
    public RandomAccessFile(File  file, String  mode);	
    public RandomAccessFile(String  name, String  mode);	

        // Methods
    public void close();	
    public final FileDescriptor getFD();	
    public long getFilePointer();	
    public long length();	
    public int read();	
    public int read(byte  b[]);	
    public int read(byte  b[], int  off, int  len);	
    public final boolean readBoolean();	
    public final byte readByte();	
    public final char readChar();	
    public final double readDouble();	
    public final float readFloat();	
    public final void readFully(byte  b[]);	
    public final void readFully(byte  b[], int  off, int  len);	
    public final int readInt();	
    public final String readLine();	
    public final long readLong();	
    public final short readShort();	
    public final int readUnsignedByte();	
    public final int readUnsignedShort();	
    public final String readUTF();	
    public void seek(long  pos);	
    public int skipBytes(int  n);	
    public void write(byte  b[]);	
    public void write(byte  b[], int  off, int  len);	
    public void write(int  b);	
    public final void writeBoolean(boolean  v);	
    public final void writeByte(int  v);	
    public final void writeBytes(String  s);	
    public final void writeChar(int  v);	
    public final void writeChars(String  s);	
    public final void writeDouble(double  v);	
    public final void writeFloat(float  v);	
    public final void writeInt(int  v);	
    public final void writeLong(long  v);	
    public final void writeShort(int  v);	
    public final void writeUTF(String  str);	
}

Instances of this class support both reading and writing to a random access file. An application can modify the position in the file at which the next read or write occurs.

Constructors

RandomAccessFile

public RandomAccessFile(File  file, String  mode) 

throws IOException 

Creates a random access file stream to read from, and optionally to write to, the file specified by the File argument.

The mode argument must either be equal to "r" or to "rw", indicating either to open the file for input, or for both input and output, respectively.

Parameter	Description
file	the file object
mode	the access mode

Throw:

IOException

If an I/O error occurs.

Throw:

IllegalArgumentException

If the mode argument is not equal to "r" or to "rw".

Throw:

SecurityException

If a security manager exists, its checkRead method is called with the path name of the File argument to see if the application is allowed read access to the file. If the mode argument is equal to "rw", its checkWrite method also is called with the path name to see if the application is allowed write access to the file.

RandomAccessFile

public RandomAccessFile(String  name, String  mode) 

throws IOException 

Creates an random access file stream to read from, and optionally to write to, a file with the specified name.

The mode argument must either be equal to "r" or "rw", indicating either to open the file for input or for both input and output.

Parameter	Description
name	the system dependent file name
mode	the access mode

Throw:

IOException

If an I/O error occurs.

Throw:

IllegalArgumentException

If the mode argument is not equal to "r" or to "rw".

Throw:

SecurityException

If a security manager exists, its checkRead method is called with the name argument to see if the application is allowed read access to the file. If the mode argument is equal to "rw", its checkWrite method also is called with the name argument to see if the application is allowed write access to the file. Either of these may result in a security security exception .

Methods

close

public void close() 

throws IOException 

Closes this random access file stream and releases any system resources associated with the stream.

Throw:

IOException

If an I/O error occurs.

getFD

public final FileDescriptor getFD() 

throws IOException 

Return Value:

Returns the file descriptor object associated with this stream.

Throw:

IOException

If an I/O error occurs.

getFilePointer

public long getFilePointer() 

throws IOException 

Returns the current offset in this file.

Return Value:

Returns the offset from the beginning of the file, in bytes, at which the next read or write occurs.

Throw:

IOException

If an I/O error occurs.

length

public long length() 

throws IOException 

Return Value:

Returns the length of this file.

Throw:

IOException

If an I/O error occurs.

read

public int read() 

throws IOException 

Reads a byte of data from this file. This method blocks if no input is yet available.

Return Value:

Returns the next byte of data, or -1 if the end of the file is reached.

Throw:

IOException

If an I/O error occurs.

read

public int read(byte  b[]) 

throws IOException 

Reads up to b.length bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Return Value:

Returns the total number of bytes read into the buffer, or -1 is there is no more data because the end of this file has been reached.

Parameter	Description
b	the buffer into which the data is read

Throw:

IOException

If an I/O error occurs.

read

public int read(byte  b[], int  off, int  len) 

throws IOException 

Reads up to len bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Return Value:

Returns the total number of bytes read into the buffer, or -1 is there is no more data because the end of the file has been reached.

Parameter	Description
b	the buffer into which the data is read
off	the start offset of the data
len	the maximum number of bytes read

Throw:

IOException

If an I/O error occurs.

readBoolean

public final boolean readBoolean() 

throws IOException 

Reads a boolean from this file. This method reads a single byte from the file. A value of 0 represents false. Any other value represents true. This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the boolean value read.

Throw:

EOFException

If this file has reached the end.

Throw:

IOException

If an I/O error occurs.

readByte

public final byte readByte() 

throws IOException 

Reads a signed 8-bit value from this file. This method reads a byte from the file. If the byte read is b, where 0 £ b £ 255, then the result is

	(byte)(b) 

This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next byte of this file as a signed 8-bit byte.

Throws:

EOFException

If this file has reached the end.

Throws:

IOException

If an I/O error occurs.

readChar

public final char readChar() 

throws IOException 

Reads a Unicode character from this file. This method reads two bytes from the file. If the bytes read, in order, are b1 and b2, where 0 £ b1,b2 £ 255, then the result is equal to

	(char)((b1 << 8) | b2) 

This method blocks until either the two bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next two bytes of this file as an Unicode character.

Throws:

EOFException

If this file reaches the end before reading two bytes.

Throws:

IOException

If an I/O error occurs.

readDouble

public final double readDouble() 

throws IOException 

Reads a double from this file. This method reads a long value as if by the readLong method and then converts that long to a double using the long-Bits-To-Double method in class Double.

This method blocks until either the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next eight bytes of this file, interpreted as a double.

Throw:

EOFException

If this file reaches the end before reading eight bytes.

Throw:

IOException

If an I/O error occurs.

readFloat

public final float readFloat() 

throws IOException 

Reads a float from this file. This method reads an int value as if by the readInt method and then converts that int to a float using the intBitsToFloat method in class Float.

This method blocks until either the four bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next four bytes of this file, interpreted as a float.

Throw:

EOFException

If this file reaches the end before reading four bytes.

Throw:

IOException

If an I/O error occurs.

readFully

public final void readFully(byte  b[]) 

throws IOException 

Reads b.length bytes from this file into the byte array. This method reads repeatedly from the file until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Parameter	Description
b	the buffer into which the data is read

Throw:

EOFException

If this file reaches the end before reading all the bytes.

Throw:

IOException

If an I/O error occurs.

readFully

public final void readFully(byte  b[], int  off, int  len) 

throws IOException 

Reads exactly len bytes from this file into the byte array. This method reads repeatedly from the file until all the bytes are read. This method blocks until either all the bytes are read, the end of the stream is detected, or an exception is thrown.

Parameter	Description
b	the buffer into which the data is read
off	the start offset of the data
len	the number of bytes to read read

Throw:

EOFException

If this file reaches the end before reading all the bytes.

Throw:

IOException

If an I/O error occurs.

readInt

public final int readInt() 

throws IOException 

Reads a signed 32-bit integer from this file. This method reads four bytes from the file. If the bytes read, in order, are b1, b2, b3, and b4 where 0 £ b1,b2,b3,b4 £ 255, then the result is equal to

	(b1 << 24) | (b2 << 16) + (b3 << 8) + b4 

This method blocks until either the four bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next four bytes of this file, interpreted as an int.

Throws:

EOFException

If this file reaches the end before reading four bytes.

Throws:

IOException

If an I/O error occurs.

readLine

public final String readLine() 

throws IOException 

Reads the next line of text from this file. This method successively reads bytes from the file until it reaches the end of a line of text.

A line of text is terminated by a carriage return character ('\r'), a newline character ('\n'), a carriage return character immediately followed by a newline character, or the end of the input stream. The line-terminating character(s), if any, are included as part of the string returned.

This method blocks until either a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next line of text from this file.

Throw:

IOException

If an I/O error occurs.

readLong

public final long readLong() 

throws IOException 

Reads a signed 64-bit integer from this file. This method reads eight bytes from the file. If the bytes read, in order, are b1, b2, b3, b4, b5, b6, b7, and b8, where 0 £ b1,b2,b3,b4,b5,b6,b7,b8 £ 255, then the result is equal to

	((long)b1 << 56) + ((long)b2 << 48) 
	+ 	((long)b3 << 40) + ((long)b4 << 32)
	+ ((long)b5 << 24) + ((long)b6 << 16) 
	+  ((long)b7 << 8) + b8 

This method blocks until either the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next eight bytes of this file, interpreted as a long.

Throws

EOFException

If this file reaches the end before reading eight bytes.

Throws:

IOException

If an I/O error occurs.

readShort

public final short readShort() 

throws IOException 

Reads a signed 16-bit number from this file. The method reads two bytes from this file. If the two bytes read, in order, are b1 and b2, where each of the two values is between 0 and 255, inclusive, then the result is equal to:

	(short)((b1 << 8) | b2) 

This method blocks until either the two bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next two bytes of this file, interpreted as a signed 16-bit number.

Throws:

EOFException

If this file reaches the end before reading two bytes.

Throws:

IOException

If an I/O error occurs.

readUnsignedByte

public final int readUnsignedByte() 

throws IOException 

Reads an unsigned 8-bit number from this filr. This method reads a byte from this file and returns that byte

This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next byte of this file, interpreted as an unsigned 8-bit number.

Throw:

EOFException

If this file has reached the end.

Throw:

IOException

If an I/O error occurs.

readUnsignedShort

public final int readUnsignedShort() 

throws IOException 

Reads an unsigned 16-bit number from this file. This method reads two bytes from the file. If the bytes read, in order, are b1 and b2, where 0 £ b1,b2 £ 255, then the result is equal to

	(b1 << 8) | b2 

This method blocks until either the two bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the next two bytes of this file, interprted as an unsigned 16-bit integer.

Throws:

EOFException

If this file reaches the end before reading two bytes.

Throws:

IOException

If an I/O error occurs.

readUTF

public final String readUTF() 

throws IOException 

Reads in a string from this file. The string has been encoded using a modified using a modified UTF-8 format.

The first two bytes from are read as if by readUnsignedShort . This values gives the number of following bytes that are in the encoded string. (Note: not the length of the resuling string). The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

This method blocks until either all the bytes are read, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns a Unicode string.

Throw:

EOFException

If this file reaches the end before reading all the bytes.

Throw:

UTFDataFormatException

If the bytes do not represent a valid UTF-8 encoding of a Unicode string.

Throw:

IOException

If an I/O error occurs.

seek

public void seek(long  pos) 

throws IOException 

Sets the offset from the beginning of this file at which the next read or write occurs.

Parameter	Description
pos	the absolute position

Throw:

IOException

If an I/O error occurs.

skipBytes

public int skipBytes(int  n) 

throws IOException 

Skips exactly n bytes of input.

This method blocks until either all the bytes are skipped, the end of the stream is detected, or an exception is thrown.

Return Value:

Returns the number of bytes skipped, which is always n.

Parameter	Description
n	the number of bytes to be skipped

Throw:

EOFException

If this file reaches the end before skipping all the bytes.

Throw:

IOException

If an I/O error occurs.

write

public void write(byte  b[]) 

throws IOException 

Writes b.length bytes from the specified byte array starting at offset off to this file.

Parameter	Description
b	the data

Throw:

IOException

If an I/O error occurs.

write

public void write(byte  b[], int  off, int  len) 

throws IOException 

Writes len bytes from the specified byte array starting at offset off to this file.

Parameter	Description
b	the data
off	the start offset in the data
len	the number of bytes to write

Throw:

IOException

If an I/O error occurs.

write

public void write(int  b) 

throws IOException 

Writes the specified byte to this file

Parameter	Description
b	the byte to be written

Throw:

IOException

If an I/O error occurs.

writeBoolean

public final void writeBoolean(boolean  v) 

throws IOException 

Writes a boolean to the file as a one-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0.

Parameter	Description
v	a boolean value to be written

Throw:

IOException

If an I/O error occurs.

writeByte

public final void writeByte(int  v) 

throws IOException 

Writes out a byte to the file as a one-byte value.

Parameter	Description
v	a byte value to be written

Throw:

IOException

If an I/O error occurs.

writeBytes

public final void writeBytes(String  s) 

throws IOException 

Writes out the string to the file as a sequence of bytes. Each character in the string is written out, in sequence, by discarding its high eight bits.

Parameter	Description
s	a string of bytes to be written

Throw:

IOException

If an I/O error occurs.

writeChar

public final void writeChar(int  v) 

throws IOException 

Writes a char to the file as a two-byte value, high byte first.

Parameter	Description
v	a char value to be written

Throw:

IOException

If an I/O error occurs.

writeChars

public final void writeChars(String  s) 

throws IOException 

Writes a string to the file as a sequence of characters. Each character is written to the data output stream as if by the writeChar method .

Parameter	Description
s	a String value to be written

Throw:

IOException

If an I/O error occurs.

writeDouble

public final void writeDouble(double  v) 

throws IOException 

Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the file as an eight-byte quantity, high-byte first.

Parameter	Description
v	a double value to be written

Throw:

IOException

If an I/O error occurs.

writeFloat

public final void writeFloat(float  v) 

throws IOException 

Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the file as a four- byte quantity, high-byte first.

Parameter	Description
v	a float value to be written

Throw:

IOException

If an I/O error occurs.

writeInt

public final void writeInt(int  v) 

throws IOException 

Writes an int to the file as four bytes, high-byte first.

Parameter	Description
v	an int to be written

Throw:

IOException

If an I/O error occurs.

writeLong

public final void writeLong(long  v) 

throws IOException 

Writes a long to the file as eight bytes, high-byte first.

Parameter	Description
v	a long to be written

Throw:

IOException

If an I/O error occurs.

writeShort

public final void writeShort(int  v) 

throws IOException 

Writes a short to the file as two bytes, high-byte first.

Parameter	Description
v	a short to be written

Throw:

IOException

If an I/O error occurs.

writeUTF

public final void writeUTF(String  str) 

throws IOException 

Writes out a string to the file using UTF-8 encoding in a machine-independent manner.

First, two bytes are written to the file as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for each character.

Parameter	Description
str	a string to be written

Throw:

IOException

If an I/O error occurs.