java.io
Class RandomAccessFile

java.lang.Object
  java.io.RandomAccessFile

All Implemented Interfaces:

Closeable, DataInput, DataOutput

public class RandomAccessFile
extends Object
implements DataInput, DataOutput, Closeable

RandomAccessFile is a class which allows positioning of the next read anywhere in the file. This is useful for reading specific locations of files or following links within a file. Most input classes only support forward skipping.

Constructor Summary

RandomAccessFile(File file, String mode)
Constructs a new RandomAccessFile on the File file and opens it according to the access String in mode.

RandomAccessFile(String fileName, String mode)
Constructs a new RandomAccessFile on the file named fileName and opens it according to the access String in mode.

Method Summary

void	close() Close this RandomAccessFile.
FileChannel	getChannel() Returns the FileChannel equivalent to this stream.
FileDescriptor	getFD() Returns the FileDescriptor representing the operating system resource for this RandomAccessFile.
long	getFilePointer() Returns the current position within this RandomAccessFile.
long	length() Returns the current length of this RandomAccessFile in bytes.
int	read() Reads a single byte from this RandomAccessFile and returns the result as an int.
int	read(byte[] buffer) Reads bytes from this RandomAccessFile into the byte array buffer.
int	read(byte[] buffer, int offset, int count) Reads at most count bytes from this RandomAccessFile and stores them in byte array buffer starting at offset.
boolean	readBoolean() Reads a boolean from this stream.
byte	readByte() Reads an 8-bit byte value from this stream.
char	readChar() Reads a 16-bit character value from this stream.
double	readDouble() Reads a 64-bit double value from this stream.
float	readFloat() Reads a 32-bit float value from this stream.
void	readFully(byte[] buffer) Reads bytes from this stream into the byte array buffer.
void	readFully(byte[] buffer, int offset, int count) Read bytes from this stream and stores them in byte array buffer starting at offset offset.
int	readInt() Reads a 32-bit integer value from this stream.
String	readLine() Returns a String representing the next line of text available in this BufferedReader.
long	readLong() Reads a 64-bit long value from this stream.
short	readShort() Reads a 16-bit short value from this stream.
int	readUnsignedByte() Reads an unsigned 8-bit byte value from this stream and returns it as an int.
int	readUnsignedShort() Reads a 16-bit unsigned short value from this stream and returns it as an int.
String	readUTF() Reads a UTF format String from this Stream.
void	seek(long pos) Seeks to the position pos in this RandomAccessFile.
void	setLength(long newLength) Set the length of this file to be newLength.
int	skipBytes(int count) Skips count number of bytes in this stream.
void	write(byte[] buffer) Writes the entire contents of the byte array buffer to this RandomAccessFile starting at the current file pointer.
void	write(byte[] buffer, int offset, int count) Writes count bytes from the byte array buffer starting at offset to this RandomAccessFile starting at the current file pointer..
void	write(int oneByte) Writes the specified byte oneByte to this RandomAccessFile starting at the current file pointer.
void	writeBoolean(boolean val) Writes a boolean to this output stream.
void	writeByte(int val) Writes a 8-bit byte to this output stream.
void	writeBytes(String str) Writes the low order 8-bit bytes from a String to this output stream.
void	writeChar(int val) Writes the specified 16-bit character to the OutputStream.
void	writeChars(String str) Writes the specified 16-bit characters contained in str to the OutputStream.
void	writeDouble(double val) Writes a 64-bit double to this output stream.
void	writeFloat(float val) Writes a 32-bit float to this output stream.
void	writeInt(int val) Writes a 32-bit int to this output stream.
void	writeLong(long val) Writes a 64-bit long to this output stream.
void	writeShort(int val) Writes the specified 16-bit short to the OutputStream.
void	writeUTF(String str) Writes the specified String out in UTF format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RandomAccessFile

public RandomAccessFile(File file,
                        String mode)
                 throws FileNotFoundException

Constructs a new RandomAccessFile on the File file and opens it according to the access String in mode. The access mode may be one of "r" for read access only, or "rw" for read/write access.

Parameters:

file - the File to open.

mode - "r" for read only, or "rw" for read/write.

Throws:

FileNotFoundException - If the mode is incorrect or the File cannot be opened in the requested mode.

See Also:

SecurityManager.checkRead(FileDescriptor), SecurityManager.checkWrite(FileDescriptor)

RandomAccessFile

public RandomAccessFile(String fileName,
                        String mode)
                 throws FileNotFoundException

Constructs a new RandomAccessFile on the file named fileName and opens it according to the access String in mode. The file may be absolute or relative to the System property "user.dir". The access mode may be one of "r" for read access only, or "rw" for read/write access.

Parameters:

fileName - the filename of the file to open.

mode - "r" for read only, or "rw" for read/write.

Throws:

FileNotFoundException - If the mode is incorrect or the file cannot be opened in the requested mode.

See Also:

SecurityManager.checkRead(FileDescriptor), SecurityManager.checkWrite(FileDescriptor)

Method Detail

close

public void close()
           throws IOException

Close this RandomAccessFile.

Specified by:

close in interface Closeable

Throws:

IOException - If an error occurs attempting to close this RandomAccessFile.

getChannel

public final FileChannel getChannel()

Returns the FileChannel equivalent to this stream.

The file channel is write-only and has an initial position within the file that is the same as the current position of this FileOutputStream within the file. All changes made to the underlying file descriptor state via the channel are visible by the output stream and vice versa.

Returns:

the file channel representation for this FileOutputStream.

getFD

public final FileDescriptor getFD()
                           throws IOException

Returns the FileDescriptor representing the operating system resource for this RandomAccessFile.

Returns:

the FileDescriptor for this RandomAccessFile.

Throws:

IOException - If an error occurs attempting to get the FileDescriptor of this RandomAccessFile.

getFilePointer

public long getFilePointer()
                    throws IOException

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

Returns:

the current file pointer position.

Throws:

IOException - If an error occurs attempting to get the file pointer position of this RandomAccessFile.

length

public long length()
            throws IOException

Returns the current length of this RandomAccessFile in bytes.

Returns:

the current file length in bytes.

Throws:

IOException - If an error occurs attempting to get the file length of this RandomAccessFile.

read

public int read()
         throws IOException

Reads a single byte from this RandomAccessFile and returns the result as an int. The low-order byte is returned or -1 of the end of file was encountered.

Returns:

the byte read or -1 if end of file.

Throws:

IOException - If an error occurs attempting to read from this RandomAccessFile.

See Also:

write(byte[]), write(byte[], int, int), write(int)

read

public int read(byte[] buffer)
         throws IOException

Reads bytes from this RandomAccessFile into the byte array buffer. The number of bytes actually read is returned.

Parameters:

buffer - the buffer to read bytes into

Returns:

the number of bytes actually read or -1 if end of file.

Throws:

IOException - If an error occurs attempting to read from this RandomAccessFile.

See Also:

write(byte[]), write(byte[], int, int), write(int)

read

public int read(byte[] buffer,
                int offset,
                int count)
         throws IOException

Reads at most count bytes from this RandomAccessFile and stores them in byte array buffer starting at offset. Answer the number of bytes actually read or -1 if no bytes were read and end of file was encountered.

Parameters:

buffer - the byte array in which to store the read bytes.

offset - the offset in buffer to store the read bytes.

count - the maximum number of bytes to store in buffer.

Returns:

the number of bytes actually read or -1 if end of file.

Throws:

IOException - If an error occurs attempting to read from this RandomAccessFile.

See Also:

write(byte[]), write(byte[], int, int), write(int)

readBoolean

public final boolean readBoolean()
                          throws IOException

Reads a boolean from this stream.

Specified by:

readBoolean in interface DataInput

Returns:

boolean the next boolean value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeBoolean(boolean)

readByte

public final byte readByte()
                    throws IOException

Reads an 8-bit byte value from this stream.

Specified by:

readByte in interface DataInput

Returns:

byte the next byte value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeByte(int)

readChar

public final char readChar()
                    throws IOException

Reads a 16-bit character value from this stream.

Specified by:

readChar in interface DataInput

Returns:

char the next char value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeChar(int)

readDouble

public final double readDouble()
                        throws IOException

Reads a 64-bit double value from this stream.

Specified by:

readDouble in interface DataInput

Returns:

double the next double value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeDouble(double)

readFloat

public final float readFloat()
                      throws IOException

Reads a 32-bit float value from this stream.

Specified by:

readFloat in interface DataInput

Returns:

float the next float value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeFloat(float)

readFully

public final void readFully(byte[] buffer)
                     throws IOException

Reads bytes from this stream into the byte array buffer. This method will block until buffer.length number of bytes have been read.

Specified by:

readFully in interface DataInput

Parameters:

buffer - the buffer to read bytes into

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.write(byte[]), DataOutput.write(byte[], int, int)

readFully

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

Read bytes from this stream and stores them in byte array buffer starting at offset offset. This method blocks until count number of bytes have been read.

Specified by:

readFully in interface DataInput

Parameters:

buffer - the byte array in which to store the read bytes.

offset - the offset in buffer to store the read bytes.

count - the maximum number of bytes to store in buffer.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.write(byte[]), DataOutput.write(byte[], int, int)

readInt

public final int readInt()
                  throws IOException

Reads a 32-bit integer value from this stream.

Specified by:

readInt in interface DataInput

Returns:

int the next int value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeInt(int)

readLine

public final String readLine()
                      throws IOException

Returns a String representing the next line of text available in this BufferedReader. A line is represented by 0 or more characters followed by '\n', '\r', "\n\r" or end of stream. The String does not include the newline sequence.

Specified by:

readLine in interface DataInput

Returns:

String the contents of the line or null if no characters were read before end of stream.

Throws:

IOException - If the BufferedReader is already closed or some other IO error occurs.

readLong

public final long readLong()
                    throws IOException

Reads a 64-bit long value from this stream.

Specified by:

readLong in interface DataInput

Returns:

long the next long value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeLong(long)

readShort

public final short readShort()
                      throws IOException

Reads a 16-bit short value from this stream.

Specified by:

readShort in interface DataInput

Returns:

short the next short value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeShort(int)

readUnsignedByte

public final int readUnsignedByte()
                           throws IOException

Reads an unsigned 8-bit byte value from this stream and returns it as an int.

Specified by:

readUnsignedByte in interface DataInput

Returns:

int the next unsigned byte value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeByte(int)

readUnsignedShort

public final int readUnsignedShort()
                            throws IOException

Reads a 16-bit unsigned short value from this stream and returns it as an int.

Specified by:

readUnsignedShort in interface DataInput

Returns:

int the next unsigned short value from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeShort(int)

readUTF

public final String readUTF()
                     throws IOException

Reads a UTF format String from this Stream.

Specified by:

readUTF in interface DataInput

Returns:

String the next UTF String from the source stream.

Throws:

IOException - If a problem occurs reading from this DataInputStream.

See Also:

DataOutput.writeUTF(java.lang.String)

seek

public void seek(long pos)
          throws IOException

Seeks to the position pos in this RandomAccessFile. All read/write/skip methods sent will be relative to pos.

Parameters:

pos - the desired file pointer position

Throws:

IOException - If the stream is already closed or another IOException occurs.

setLength

public void setLength(long newLength)
               throws IOException

Set the length of this file to be newLength. If the current file is smaller, it will be expanded and the filePosition will be set to the new file length. If the newLength is smaller then the file will be truncated.

Parameters:

newLength - the desired file length

Throws:

IOException - If the stream is already closed or another IOException occurs.

skipBytes

public int skipBytes(int count)
              throws IOException

Skips count number of bytes in this stream. Subsequent read()'s will not return these bytes unless reset() is used.

Specified by:

skipBytes in interface DataInput

Parameters:

count - the number of bytes to skip.

Returns:

the number of bytes actually skipped.

Throws:

IOException - If the stream is already closed or another IOException occurs.

write

public void write(byte[] buffer)
           throws IOException

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

Specified by:

write in interface DataOutput

Parameters:

buffer - the buffer to be written.

Throws:

IOException - If an error occurs trying to write to this RandomAccessFile.

See Also:

read(), read(byte[]), read(byte[], int, int)

write

public void write(byte[] buffer,
                  int offset,
                  int count)
           throws IOException

Writes count bytes from the byte array buffer starting at offset to this RandomAccessFile starting at the current file pointer..

Specified by:

write in interface DataOutput

Parameters:

buffer - the bytes to be written

offset - offset in buffer to get bytes

count - number of bytes in buffer to write

Throws:

IOException - If an error occurs attempting to write to this RandomAccessFile.

IndexOutOfBoundsException - If offset or count are outside of bounds.

See Also:

read(), read(byte[]), read(byte[], int, int)

write

public void write(int oneByte)
           throws IOException

Writes the specified byte oneByte to this RandomAccessFile starting at the current file pointer. Only the low order byte of oneByte is written.

Specified by:

write in interface DataOutput

Parameters:

oneByte - the byte to be written

Throws:

IOException - If an error occurs attempting to write to this RandomAccessFile.

See Also:

read(), read(byte[]), read(byte[], int, int)

writeBoolean

public final void writeBoolean(boolean val)
                        throws IOException

Writes a boolean to this output stream.

Specified by:

writeBoolean in interface DataOutput

Parameters:

val - the boolean value to write to the OutputStream

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readBoolean()

writeByte

public final void writeByte(int val)
                     throws IOException

Writes a 8-bit byte to this output stream.

Specified by:

writeByte in interface DataOutput

Parameters:

val - the byte value to write to the OutputStream

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

readByte(), readUnsignedByte()

writeBytes

public final void writeBytes(String str)
                      throws IOException

Writes the low order 8-bit bytes from a String to this output stream.

Specified by:

writeBytes in interface DataOutput

Parameters:

str - the String containing the bytes to write to the OutputStream

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

read(byte[]), read(byte[],int,int), readFully(byte[]), readFully(byte[],int,int)

writeChar

public final void writeChar(int val)
                     throws IOException

Writes the specified 16-bit character to the OutputStream. Only the lower 2 bytes are written with the higher of the 2 bytes written first. This represents the Unicode value of val.

Specified by:

writeChar in interface DataOutput

Parameters:

val - the character to be written

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readChar()

writeChars

public final void writeChars(String str)
                      throws IOException

Writes the specified 16-bit characters contained in str to the OutputStream. Only the lower 2 bytes of each character are written with the higher of the 2 bytes written first. This represents the Unicode value of each character in str.

Specified by:

writeChars in interface DataOutput

Parameters:

str - the String whose characters are to be written.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readChar()

writeDouble

public final void writeDouble(double val)
                       throws IOException

Writes a 64-bit double to this output stream. The resulting output is the 8 bytes resulting from calling Double.doubleToLongBits().

Specified by:

writeDouble in interface DataOutput

Parameters:

val - the double to be written.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readDouble()

writeFloat

public final void writeFloat(float val)
                      throws IOException

Writes a 32-bit float to this output stream. The resulting output is the 4 bytes resulting from calling Float.floatToIntBits().

Specified by:

writeFloat in interface DataOutput

Parameters:

val - the float to be written.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readFloat()

writeInt

public final void writeInt(int val)
                    throws IOException

Writes a 32-bit int to this output stream. The resulting output is the 4 bytes, highest order first, of val.

Specified by:

writeInt in interface DataOutput

Parameters:

val - the int to be written.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readInt()

writeLong

public final void writeLong(long val)
                     throws IOException

Writes a 64-bit long to this output stream. The resulting output is the 8 bytes, highest order first, of val.

Specified by:

writeLong in interface DataOutput

Parameters:

val - the long to be written.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readLong()

writeShort

public final void writeShort(int val)
                      throws IOException

Writes the specified 16-bit short to the OutputStream. Only the lower 2 bytes are written with the higher of the 2 bytes written first.

Specified by:

writeShort in interface DataOutput

Parameters:

val - the short to be written

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readShort(), DataInput.readUnsignedShort()

writeUTF

public final void writeUTF(String str)
                    throws IOException

Writes the specified String out in UTF format.

Specified by:

writeUTF in interface DataOutput

Parameters:

str - the String to be written in UTF format.

Throws:

IOException - If an error occurs attempting to write to this DataOutputStream.

See Also:

DataInput.readUTF()