info.guardianproject.iocipher

Class RandomAccessFile

java.lang.Object

info.guardianproject.iocipher.RandomAccessFile

All Implemented Interfaces:

java.io.Closeable, java.io.DataInput, java.io.DataOutput, java.lang.AutoCloseable

public class RandomAccessFile
extends java.lang.Object
implements java.io.DataInput, java.io.DataOutput, java.io.Closeable

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.

Constructor Summary

Constructors

Constructor and Description
RandomAccessFile(File file, java.lang.String mode) Constructs a new RandomAccessFile based on file and opens it according to the access string in mode.
RandomAccessFile(java.lang.String fileName, java.lang.String mode) Constructs a new RandomAccessFile based on the file named fileName and opens it according to the access string in mode.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this file.
protected void	finalize()
IOCipherFileChannel	getChannel() Gets this file's IOCipherFileChannel object.
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() 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.
int	read(byte[] buffer, int byteOffset, int byteCount) Reads at most byteCount bytes from the current position in this file and stores them in the byte array buffer starting at byteOffset.
boolean	readBoolean() Reads a boolean from the current position in this file.
byte	readByte() Reads an 8-bit byte from the current position in this file.
char	readChar() Reads a big-endian 16-bit character from the current position in this file.
double	readDouble() Reads a big-endian 64-bit double from the current position in this file.
float	readFloat() Reads a big-endian 32-bit float from the current position in this file.
void	readFully(byte[] dst) Equivalent to readFully(dst, 0, dst.length);.
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.
int	readInt() Reads a big-endian 32-bit integer from the current position in this file.
java.lang.String	readLine() Reads a line of text form the current position in this file.
long	readLong() Reads a big-endian 64-bit long from the current position in this file.
short	readShort() Reads a big-endian 16-bit short from the current position in this file.
int	readUnsignedByte() Reads an unsigned 8-bit byte from the current position in this file and returns it as an integer.
int	readUnsignedShort() Reads an unsigned big-endian 16-bit short from the current position in this file and returns it as an integer.
java.lang.String	readUTF() Reads a string that is encoded in modified UTF-8 from this file.
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(byte[] buffer) Writes the entire contents of the byte array buffer 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(int oneByte) Writes a byte to this file, starting at the current file pointer.
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.
void	writeByte(int val) Writes an 8-bit byte to this file, starting at the current file pointer.
void	writeBytes(java.lang.String str) Writes the low order 8-bit bytes from a string to this file, starting at the current file pointer.
void	writeChar(int val) Writes a big-endian 16-bit character to this file, starting at the current file pointer.
void	writeChars(java.lang.String str) Writes big-endian 16-bit characters from str to this file, starting at the current file pointer.
void	writeDouble(double val) Writes a big-endian 64-bit double to this file, starting at the current file pointer.
void	writeFloat(float val) Writes a big-endian 32-bit float to this file, starting at the current file pointer.
void	writeInt(int val) Writes a big-endian 32-bit integer to this file, starting at the current file pointer.
void	writeLong(long val) Writes a big-endian 64-bit long to this file, starting at the current file pointer.
void	writeShort(int val) Writes a big-endian 16-bit short to this file, starting at the current file pointer.
void	writeUTF(java.lang.String str) Writes a string encoded with modified UTF-8 to this file, starting at the current file pointer.

Methods inherited from class java.lang.Object

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

Constructor Detail

RandomAccessFile

public RandomAccessFile(File file,
                        java.lang.String mode)
                 throws java.io.FileNotFoundException

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:

java.io.FileNotFoundException - if the file cannot be opened or created according to mode.

java.lang.IllegalArgumentException - if mode is not "r", "rw", "rws" or "rwd".

RandomAccessFile

public RandomAccessFile(java.lang.String fileName,
                        java.lang.String mode)
                 throws java.io.FileNotFoundException

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:

java.io.FileNotFoundException - if the file cannot be opened or created according to mode.

java.lang.IllegalArgumentException - if mode is not "r", "rw", "rws" or "rwd".

Method Detail

close

public void close()
           throws java.io.IOException

Closes this file.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - if an error occurs while closing this file.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getChannel

public final IOCipherFileChannel getChannel()

Gets this file's IOCipherFileChannel 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.

getFD

public final FileDescriptor getFD()
                           throws java.io.IOException

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

Returns:

this file's file descriptor object.

Throws:

java.io.IOException - if an error occurs while getting the file descriptor of this file.

getFilePointer

public long getFilePointer()
                    throws java.io.IOException

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:

java.io.IOException - if an error occurs while getting the file pointer of this file.

length

public long length()
            throws java.io.IOException

Returns the length of this file in bytes.

Returns:

the file's length in bytes.

Throws:

java.io.IOException - if this file is closed or some other I/O error occurs.

read

public int read()
         throws java.io.IOException

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:

java.io.IOException - if this file is closed or another I/O error occurs.

read

public int read(byte[] buffer)
         throws java.io.IOException

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.

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:

java.io.IOException - if this file is closed or another I/O error occurs.

read

public int read(byte[] buffer,
                int byteOffset,
                int byteCount)
         throws java.io.IOException

Reads at most 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.

Throws:

java.lang.IndexOutOfBoundsException - if byteOffset < 0 or byteCount < 0, or if byteOffset + byteCount is greater than the size of buffer.

java.io.IOException - if this file is closed or another I/O error occurs.

readBoolean

public final boolean readBoolean()
                          throws java.io.IOException

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.

Specified by:

readBoolean in interface java.io.DataInput

Returns:

the next boolean value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeBoolean(boolean)

readByte

public final byte readByte()
                    throws java.io.IOException

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.

Specified by:

readByte in interface java.io.DataInput

Returns:

the next signed 8-bit byte value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeBoolean(boolean)

readChar

public final char readChar()
                    throws java.io.IOException

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.

Specified by:

readChar in interface java.io.DataInput

Returns:

the next char value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeChar(int)

readDouble

public final double readDouble()
                        throws java.io.IOException

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.

Specified by:

readDouble in interface java.io.DataInput

Returns:

the next double value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeDouble(double)

readFloat

public final float readFloat()
                      throws java.io.IOException

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.

Specified by:

readFloat in interface java.io.DataInput

Returns:

the next float value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeFloat(float)

readFully

public final void readFully(byte[] dst)
                     throws java.io.IOException

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

Specified by:

readFully in interface java.io.DataInput

Throws:

java.io.IOException

readFully

public final void readFully(byte[] dst,
                            int offset,
                            int byteCount)
                     throws java.io.IOException

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.

Specified by:

readFully in interface java.io.DataInput

Parameters:

dst - the byte array into which the data is read.

offset - the offset in dst at which to store the bytes.

byteCount - the number of bytes to read.

Throws:

java.io.EOFException - if the end of the source stream is reached before enough bytes have been read.

java.lang.IndexOutOfBoundsException - if offset < 0 or byteCount < 0, or offset + byteCount > dst.length.

java.io.IOException - if a problem occurs while reading from this stream.

java.lang.NullPointerException - if dst is null.

readInt

public final int readInt()
                  throws java.io.IOException

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.

Specified by:

readInt in interface java.io.DataInput

Returns:

the next int value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeInt(int)

readLine

public final java.lang.String readLine()
                                throws java.io.IOException

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.

Specified by:

readLine in interface java.io.DataInput

Returns:

the contents of the line or null if no characters have been read before the end of the file has been reached.

Throws:

java.io.IOException - if this file is closed or another I/O error occurs.

readLong

public final long readLong()
                    throws java.io.IOException

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.

Specified by:

readLong in interface java.io.DataInput

Returns:

the next long value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeLong(long)

readShort

public final short readShort()
                      throws java.io.IOException

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.

Specified by:

readShort in interface java.io.DataInput

Returns:

the next short value from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeShort(int)

readUnsignedByte

public final int readUnsignedByte()
                           throws java.io.IOException

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.

Specified by:

readUnsignedByte in interface java.io.DataInput

Returns:

the next unsigned byte value from this file as an int.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeByte(int)

readUnsignedShort

public final int readUnsignedShort()
                            throws java.io.IOException

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.

Specified by:

readUnsignedShort in interface java.io.DataInput

Returns:

the next unsigned short value from this file as an int.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

writeShort(int)

readUTF

public final java.lang.String readUTF()
                               throws java.io.IOException

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.

Specified by:

readUTF in interface java.io.DataInput

Returns:

the next string encoded in modified UTF-8 from this file.

Throws:

java.io.EOFException - if the end of this file is detected.

java.io.IOException - if this file is closed or another I/O error occurs.

java.io.UTFDataFormatException - if the bytes read cannot be decoded into a character string.

See Also:

writeUTF(String)

seek

public void seek(long offset)
          throws java.io.IOException

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 - the new file pointer position.

Throws:

java.io.IOException - if this file is closed, pos < 0 or another I/O error occurs.

setLength

public void setLength(long newLength)
               throws java.io.IOException

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:

java.lang.IllegalArgumentException - if newLength < 0.

java.io.IOException - if this file is closed or another I/O error occurs.

skipBytes

public int skipBytes(int count)
              throws java.io.IOException

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.

Specified by:

skipBytes in interface java.io.DataInput

Parameters:

count - the number of bytes to skip.

Returns:

the number of bytes actually skipped.

Throws:

java.io.IOException - if this file is closed or another I/O error occurs.

write

public void write(byte[] buffer)
           throws java.io.IOException

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

Specified by:

write in interface java.io.DataOutput

Parameters:

buffer - the buffer to write.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

write

public void write(byte[] buffer,
                  int byteOffset,
                  int byteCount)
           throws java.io.IOException

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.

Specified by:

write in interface java.io.DataOutput

Throws:

java.lang.IndexOutOfBoundsException - if byteCount < 0, byteOffset < 0 or byteCount + byteOffset is greater than the size of buffer.

java.io.IOException - if an I/O error occurs while writing to this file.

write

public void write(int oneByte)
           throws java.io.IOException

Writes a byte to this file, starting at the current file pointer. Only the least significant byte of the integer oneByte is written.

Specified by:

write in interface java.io.DataOutput

Parameters:

oneByte - the byte to write to this file.

Throws:

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

read()

writeBoolean

public final void writeBoolean(boolean val)
                        throws java.io.IOException

Writes a boolean to this file as a single byte (1 for true, 0 for false), starting at the current file pointer.

Specified by:

writeBoolean in interface java.io.DataOutput

Parameters:

val - the boolean to write to this file.

Throws:

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

readBoolean()

writeByte

public final void writeByte(int val)
                     throws java.io.IOException

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.

Specified by:

writeByte in interface java.io.DataOutput

Parameters:

val - the byte to write to this file.

Throws:

java.io.IOException - if this file is closed or another I/O error occurs.

See Also:

readByte(), readUnsignedByte()

writeBytes

public final void writeBytes(java.lang.String str)
                      throws java.io.IOException

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

Specified by:

writeBytes in interface java.io.DataOutput

Parameters:

str - the string containing the bytes to write to this file

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

writeChar

public final void writeChar(int val)
                     throws java.io.IOException

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.

Specified by:

writeChar in interface java.io.DataOutput

Parameters:

val - the char to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readChar()

writeChars

public final void writeChars(java.lang.String str)
                      throws java.io.IOException

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

Specified by:

writeChars in interface java.io.DataOutput

Parameters:

str - the string to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readChar()

writeDouble

public final void writeDouble(double val)
                       throws java.io.IOException

Writes a big-endian 64-bit double to this file, starting at the current file pointer. The bytes are those returned by Double.doubleToLongBits(double), meaning a canonical NaN is used.

Specified by:

writeDouble in interface java.io.DataOutput

Parameters:

val - the double to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readDouble()

writeFloat

public final void writeFloat(float val)
                      throws java.io.IOException

Writes a big-endian 32-bit float to this file, starting at the current file pointer. The bytes are those returned by Float.floatToIntBits(float), meaning a canonical NaN is used.

Specified by:

writeFloat in interface java.io.DataOutput

Parameters:

val - the float to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readFloat()

writeInt

public final void writeInt(int val)
                    throws java.io.IOException

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

Specified by:

writeInt in interface java.io.DataOutput

Parameters:

val - the int to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readInt()

writeLong

public final void writeLong(long val)
                     throws java.io.IOException

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

Specified by:

writeLong in interface java.io.DataOutput

Parameters:

val - the long to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readLong()

writeShort

public final void writeShort(int val)
                      throws java.io.IOException

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.

Specified by:

writeShort in interface java.io.DataOutput

Parameters:

val - the short to write to this file.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

See Also:

readShort(), DataInput.readUnsignedShort()

writeUTF

public final void writeUTF(java.lang.String str)
                    throws java.io.IOException

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

Specified by:

writeUTF in interface java.io.DataOutput

Parameters:

str - the string to write in modified UTF-8 format.

Throws:

java.io.IOException - if an I/O error occurs while writing to this file.

java.io.UTFDataFormatException - if the encoded string is longer than 65535 bytes.

See Also:

readUTF()