edu.sdsc.grid.io.irods
Class IRODSRandomAccessFile

java.lang.Object
  edu.sdsc.grid.io.GeneralRandomAccessFile
      edu.sdsc.grid.io.RemoteRandomAccessFile
          edu.sdsc.grid.io.irods.IRODSRandomAccessFile

All Implemented Interfaces:

java.io.DataInput, java.io.DataOutput

public class IRODSRandomAccessFile
extends RemoteRandomAccessFile

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

This class behaves exactly as described in GeneralRandomAccessFile

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.

Since:

JARGON1.0

Field Summary

Fields inherited from class edu.sdsc.grid.io.GeneralRandomAccessFile

fd, file, fileFormat, isClosed, mode, rw, SEEK_CURRENT, SEEK_END, SEEK_START, swapNeeded

Constructor Summary

IRODSRandomAccessFile(IRODSFile file, java.lang.String mode)
Creates a random access file stream to read from, and optionally to write to, a file with the specified name.

IRODSRandomAccessFile(IRODSFileSystem irodsFileSystem, java.lang.String filePath, java.lang.String mode)
Creates a random access file stream to read from, and optionally to write to, a file with the specified name.

Method Summary

void	close() Closes this random access file stream and releases any system resources associated with the stream.
protected void	finalize() Finalizes the object by explicitly letting go of each of its internally held values.
long	getFilePointer() Returns the current offset in this file.
GeneralFileSystem	getFileSystem() Returns the irods file system object.
long	length() Returns the length of this file.
protected void	open(GeneralFile file) Opens this file.
int	read() Reads a byte of data from this file.
protected int	readBytes(byte[] buffer, int offset, int len) Reads a sub array as a sequence of bytes.
void	seek(long position, int origin) Sets the file-pointer offset at which the next read or write occurs.
protected void	setFileSystem(GeneralFileSystem fileSystem) Sets the IRODS server used of this IRODSRandomAccessFile object.
void	setLength(long newLength) Sets the length of this file.
protected void	writeBytes(byte[] buffer, int offset, int len) Writes a sub array as a sequence of bytes.

Methods inherited from class edu.sdsc.grid.io.GeneralRandomAccessFile

getBinaryDataFormat, getFD, getFile, isClosed, read, read, readBoolean, readBooleans, readByte, readChar, readDouble, readDoubles, readFloat, readFloats, readFully, readFully, readInt, readInts, readLine, readLong, readLongDouble, readLongDoubles, readLongLong, readLongLongs, readLongs, readShort, readShorts, readUnsignedByte, readUnsignedInt, readUnsignedInts, readUnsignedLong, readUnsignedLongLong, readUnsignedLongLongs, readUnsignedLongs, readUnsignedShort, readUnsignedShorts, readUTF, rwCheck, seek, setBinaryDataFormat, skipBytes, toString, write, write, write, write, writeBoolean, writeBooleans, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeDoubles, writeFloat, writeFloats, writeInt, writeInts, writeLong, writeLongDouble, writeLongDoubles, writeLongLong, writeLongLongs, writeLongs, writeShort, writeShorts, writeUTF

Methods inherited from class java.lang.Object

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

Constructor Detail

IRODSRandomAccessFile

public IRODSRandomAccessFile(IRODSFileSystem irodsFileSystem,
                             java.lang.String filePath,
                             java.lang.String mode)
                      throws java.lang.IllegalArgumentException,
                             java.io.FileNotFoundException,
                             java.lang.SecurityException,
                             java.io.IOException

Creates a random access file stream to read from, and optionally to write to, a file with the specified name. A new file descriptor is obtained from the IRODS which represents 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 GeneralRandomAccessFile(File,String) constructor.

On construction a check is made to see if read access to the file is allowed. If the mode allows writing, write access to the file is also checked.

Parameters:

filePath - the IRODS file path

mode - the access mode

Throws:

java.lang.IllegalArgumentException - if the mode argument is not equal to one of "r", "rw", "rws", or "rwd"

java.io.IOException - If an I/O error occurs

java.io.FileNotFoundException - If the file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason

java.lang.SecurityException - If denied read access to the file or the mode is "rw" and denied write access to the file.

IRODSRandomAccessFile

public IRODSRandomAccessFile(IRODSFile file,
                             java.lang.String mode)
                      throws java.lang.IllegalArgumentException,
                             java.io.FileNotFoundException,
                             java.lang.SecurityException,
                             java.io.IOException

Creates a random access file stream to read from, and optionally to write to, a file with the specified name. A new file descriptor is obtained from the IRODS which represents the connection to the file.

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

"r"	Open for reading only. Invoking any of the write methods of the resulting object will cause an 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.

The "rws" and "rwd" modes work much like the force(boolean) method of the 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.

On construction a check is made to see if read access to the file is allowed. If the mode allows writing, write access to the file is also checked.

Parameters:

file - the file object

mode - the access mode, as described above

Throws:

java.io.IOException - If an I/O error occurs

java.lang.IllegalArgumentException - if the mode argument is not equal to one of "r", "rw", "rws", or "rwd"

java.io.FileNotFoundException - If the file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason

java.lang.SecurityException - If denied read access to the file or the mode is "rw" and denied write access to the file.

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalizes the object by explicitly letting go of each of its internally held values.

Overrides:

finalize in class GeneralRandomAccessFile

Throws:

java.lang.Throwable

open

protected void open(GeneralFile file)
             throws java.io.FileNotFoundException,
                    java.lang.SecurityException,
                    java.io.IOException

Opens this file. The file is opened in read-write mode if writeable is true, else the file is opened as read-only. If the name refers to a directory, an IOException is thrown.

Specified by:

open in class GeneralRandomAccessFile

Parameters:

file - the file to open

Throws:

java.io.IOException - If an I/O error occurs

java.io.FileNotFoundException

java.lang.SecurityException

setFileSystem

protected void setFileSystem(GeneralFileSystem fileSystem)
                      throws java.lang.IllegalArgumentException,
                             java.lang.ClassCastException

Sets the IRODS server used of this IRODSRandomAccessFile object.

Parameters:

fleServer - The IRODS server to be used.

Throws:

java.lang.IllegalArgumentException - - if the argument is null.

java.lang.ClassCastException - - if the argument is not a IRODSFileSystem object.

getFileSystem

public GeneralFileSystem getFileSystem()

Returns the irods file system object.

Overrides:

getFileSystem in class GeneralRandomAccessFile

Returns:

RemoteFileSystem

Throws:

java.lang.NullPointerException - if fileSystem is null.

read

public int read()
         throws java.io.IOException

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 IRODSRandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as java.io.InputStream.read().

Specified by:

read in class GeneralRandomAccessFile

Returns:

the next byte of data, or -1 if the end of the file has been reached.

Throws:

java.io.IOException - if an I/O error occurs. Not thrown if end-of-file has been reached.

readBytes

protected int readBytes(byte[] buffer,
                        int offset,
                        int len)
                 throws java.io.IOException

Reads a sub array as a sequence of bytes.

Specified by:

readBytes in class GeneralRandomAccessFile

Parameters:

buffer - the buffer into which the data is read.

offset - the start offset in the data

len - the maximum number of bytes read.

Throws:

java.io.IOException - If an I/O error has occurred.

writeBytes

protected void writeBytes(byte[] buffer,
                          int offset,
                          int len)
                   throws java.io.IOException

Writes a sub array as a sequence of bytes.

Specified by:

writeBytes in class GeneralRandomAccessFile

Parameters:

buffer - the data to be written

offset - the start offset in the data

len - the number of bytes that are written

Throws:

java.io.IOException - If an I/O error has occurred.

getFilePointer

public long getFilePointer()
                    throws java.io.IOException

Returns the current offset in this file.

Specified by:

getFilePointer in class GeneralRandomAccessFile

Returns:

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

Throws:

java.io.IOException - if an I/O error occurs.

seek

public void seek(long position,
                 int origin)
          throws java.io.IOException

Sets the file-pointer offset 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.

Specified by:

seek in class GeneralRandomAccessFile

Parameters:

pos - the offset position, measured in bytes from the at which to set the file pointer.

origin - a Sets offset for the beginning of the seek.
SEEK_START - sets the offset from the beginning of the file. SEEK_CURRENT - sets the offset from the current position of the filePointer.
SEEK_END - sets the offset from the end of the file.

Throws:

java.io.IOException - if pos is less than 0 or if an I/O error occurs.

length

public long length()
            throws java.io.IOException

Returns the length of this file.

Specified by:

length in class GeneralRandomAccessFile

Returns:

the length of this file, measured in bytes.

Throws:

java.io.IOException - if an I/O error occurs.

setLength

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

Sets the length of this file.

Truncating a file on the IRODS is not yet supported, so an UnsupportedOperationException will be thrown. (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.

Specified by:

setLength in class GeneralRandomAccessFile

Parameters:

newLength - The desired length of the file

Throws:

java.io.IOException - If an I/O error occurs

java.lang.UnsupportedOperationException - on truncate

close

public void close()
           throws java.io.IOException

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.

Specified by:

close in class GeneralRandomAccessFile

Throws:

java.io.IOException - if an I/O error occurs.