java::io::RandomAccessFile Class Reference

Inheritance diagram for java::io::RandomAccessFile:

Inheritance graph
java::lang::Objectjava::lang::Interfacejava::io::InputStreamjava::io::OutputStream
[legend]
Collaboration diagram for java::io::RandomAccessFile:

Collaboration graph
java::lang::Objectjava::lang::Interfacejava::lang::ObjectRefjava::io::InputStreamjava::io::OutputStreamjava::lang::Comparable
[legend]

List of all members.


Detailed Description

Instances of this class support both reading and writing to a random access file.

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.

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.

Author:
Yuh-Jye Chang
Version:
1.67, 12/03/01
Since:
JDK1.0

Public Member Functions

 RandomAccessFile (const String &name=nilString, const String &mode="rw")
 Creates a random access file stream to read from, and optionally to write to, a file with the specified name.
 RandomAccessFile (const File &file, const String &mode="rw")
 Creates a random access file stream to read from, and optionally to write to, the file specified by the File argument.
FileDescriptor getFD ()
 Returns the opaque file descriptor object associated with this stream.
virtual jint read ()
 Reads a byte of data from this file.
virtual jint read (Array< jbyte > &b, jint off=0, jint len=-1)
 Reads up to len bytes of data from this file into an array of bytes.
virtual jlong skip (jlong n)
 Skips over and discards n bytes of data from this input stream.
virtual jint available ()
 Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream.
virtual void write (jint b)
 Writes the specified byte (the low eight bits of the argument b) to the underlying output stream.
virtual void write (const Array< jbyte > &b, jint off=0, jint len=-1)
 Writes len bytes from the specified byte array starting at offset off to the underlying output stream.
virtual void flush ()
 Flushes this output stream and forces any buffered output bytes to be written out.
virtual void close ()
 Closes this random access file stream and releases any system resources associated with the stream.
jlong getFilePointer ()
 Returns the current offset in this file.
void seek (jlong pos)
 Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.
jlong length ()
 Returns the length of this file.
void setLength (jlong newLength)
 Sets the length of this file.

Constructor & Destructor Documentation

java::io::RandomAccessFile::RandomAccessFile ( const String name = nilString,
const String mode = "rw" 
)

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

A new FileDescriptor object is created to represent the connection to the file.

The mode argument specifies the access mode with which the file is to be opened. The permitted values and their meanings are as specified for the RandomAccessFile(File,String) constructor.

If there is a security manager, its checkRead method is called with the name argument as its argument to see if read access to the file is allowed. If the mode allows writing, the security manager's checkWrite method is also called with the name argument as its argument to see if write access to the file is allowed.

Parameters:
name the system-dependent filename
mode the access mode
Exceptions:
IllegalArgumentException if the mode argument is not equal to one of "r", "rw", "rws", or "rwd"
FileNotFoundException if the file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason
SecurityException if a security manager exists and its checkRead method denies read access to the file or the mode is "rw" and the security manager's checkWrite method denies write access to the file 1.4 JSR-51

java::io::RandomAccessFile::RandomAccessFile ( const File file,
const String mode = "rw" 
)

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

A new FileDescriptor object is created to represent this file connection.

The mode argument specifies the access mode in which the file is to be opened. The permitted values and their meanings are:

<blockquote>
"r" Open for reading only. Invoking any of the write methods of the resulting object will cause an java.io.IOException to be thrown.
"rw" Open for reading and writing. If the file does not already exist then an attempt will be made to create it.
"rws" Open for reading and writing, as with "rw", and also require that every update to the file's content or metadata be written synchronously to the underlying storage device.
"rwd"   Open for reading and writing, as with "rw", and also require that every update to the file's content be written synchronously to the underlying storage device.
</blockquote>

The "rws" and "rwd" modes work much like the force(boolean) method of the java.nio.channels.FileChannel class, passing arguments of true and false, respectively, except that they always apply to every I/O operation and are therefore often more efficient. If the file resides on a local storage device then when an invocation of a method of this class returns it is guaranteed that all changes made to the file by that invocation will have been written to that device. This is useful for ensuring that critical information is not lost in the event of a system crash. If the file does not reside on a local device then no such guarantee is made.

The "rwd" mode can be used to reduce the number of I/O operations performed. Using "rwd" only requires updates to the file's content to be written to storage; using "rws" requires updates to both the file's content and its metadata to be written, which generally requires at least one more low-level I/O operation.

If there is a security manager, its checkRead method is called with the pathname of the file argument as its argument to see if read access to the file is allowed. If the mode allows writing, the security manager's checkWrite method is also called with the path argument to see if write access to the file is allowed.

Parameters:
file the file object
mode the access mode, as described above
Exceptions:
IllegalArgumentException if the mode argument is not equal to one of "r", "rw", "rws", or "rwd"
FileNotFoundException if the file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason
SecurityException if a security manager exists and its checkRead method denies read access to the file or the mode is "rw" and the security manager's checkWrite method denies write access to the file 1.4 JSR-51


Member Function Documentation

FileDescriptor java::io::RandomAccessFile::getFD (  ) 

Returns the opaque file descriptor object associated with this stream.

Returns:
the file descriptor object associated with this stream.
Exceptions:
IOException if an I/O error occurs.

virtual jint java::io::RandomAccessFile::read (  )  [virtual]

Reads a byte of data from this file.

The byte is returned as an integer in the range 0 to 255 (0x00-0x0ff). This method blocks if no input is yet available.

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

Returns:
the next byte of data, or -1 if the end of the file has been reached.
Exceptions:
IOException if an I/O error occurs. Not thrown if end-of-file has been reached.

Implements java::io::InputStream.

virtual jint java::io::RandomAccessFile::read ( Array< jbyte > &  b,
jint  off = 0,
jint  len = -1 
) [virtual]

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.

Although RandomAccessFile is not a subclass of InputStream, this method behaves in the exactly the same way as the InputStream#read(byte[], int, int) method of InputStream.

Parameters:
b the buffer into which the data is read.
off the start offset of the data.
len the maximum number of bytes read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Exceptions:
IOException if an I/O error occurs.

Implements java::io::InputStream.

virtual jlong java::io::RandomAccessFile::skip ( jlong  n  )  [virtual]

Skips over and discards n bytes of data from this input stream.

The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

The skip method of InputStream creates a byte array and then repeatedly reads into it until n bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method.

Parameters:
n the number of bytes to be skipped.
Returns:
the actual number of bytes skipped.
Exceptions:
IOException if an I/O error occurs.

Implements java::io::InputStream.

virtual jint java::io::RandomAccessFile::available (  )  [virtual]

Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream.

The next caller might be the same thread or or another thread.

The available method for class InputStream always returns 0.

This method should be overridden by subclasses.

Returns:
the number of bytes that can be read from this input stream without blocking.
Exceptions:
IOException if an I/O error occurs.

Reimplemented from java::io::InputStream.

virtual void java::io::RandomAccessFile::write ( jint  b  )  [virtual]

Writes the specified byte (the low eight bits of the argument b) to the underlying output stream.

If no exception is thrown, the counter written is incremented by 1.

Implements the write method of OutputStream.

Parameters:
b the byte to be written.
Exceptions:
IOException if an I/O error occurs.

Implements java::io::OutputStream.

virtual void java::io::RandomAccessFile::write ( const Array< jbyte > &  b,
jint  off = 0,
jint  len = -1 
) [virtual]

Writes len bytes from the specified byte array starting at offset off to the underlying output stream.

If no exception is thrown, the counter written is incremented by len.

Parameters:
b the data.
off the start offset in the data.
len the number of bytes to write.
Exceptions:
IOException if an I/O error occurs.

Implements java::io::OutputStream.

virtual void java::io::RandomAccessFile::flush (  )  [virtual]

Flushes this output stream and forces any buffered output bytes to be written out.

The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination.

The flush method of OutputStream does nothing.

Exceptions:
IOException if an I/O error occurs.

Reimplemented from java::io::OutputStream.

virtual void java::io::RandomAccessFile::close (  )  [virtual]

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

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

If this file has an associated channel then the channel is closed as well.

Exceptions:
IOException if an I/O error occurs.
1.4 JSR-51

Reimplemented from java::io::InputStream.

jlong java::io::RandomAccessFile::getFilePointer (  ) 

Returns the current offset in this file.

Returns:
the offset from the beginning of the file, in bytes, at which the next read or write occurs.
Exceptions:
IOException if an I/O error occurs.

void java::io::RandomAccessFile::seek ( jlong  pos  ) 

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

The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.

Parameters:
pos the offset position, measured in bytes from the beginning of the file, at which to set the file pointer.
Exceptions:
IOException if pos is less than 0 or if an I/O error occurs.

jlong java::io::RandomAccessFile::length (  ) 

Returns the length of this file.

Returns:
the length of this file, measured in bytes.
Exceptions:
IOException if an I/O error occurs.

void java::io::RandomAccessFile::setLength ( jlong  newLength  ) 

Sets the length of this file.

If the present length of the file as returned by the length method is greater than the newLength argument then the file will be truncated. In this case, if the file offset as returned by the getFilePointer method is greater then newLength then after this method returns the offset will be equal to newLength.

If the present length of the file as returned by the length method is smaller than the newLength argument then the file will be extended. In this case, the contents of the extended portion of the file are not defined.

Parameters:
newLength The desired length of the file
Exceptions:
IOException If an I/O error occurs
Since:
1.2


The documentation for this class was generated from the following file:
Generated on Fri May 16 11:56:33 2008 for CrossPlatformJavaLikeC++API by  doxygen 1.5.3