org.entityfs
Interface RandomAccess

All Superinterfaces:

DataSink, DataSource

All Known Implementing Classes:

ByteArrayRandomAccess, DataInputOutputRandomAccessAdapter, EmptyRandomAccess, InputStreamBackedRandomAccess, LockAwareRandomAccess, RandomAccessAdapter, RandomAccessToDataInputOutputAdapter, RangeRandomAccess, TempFileBackedRandomAccess

public interface RandomAccess
extends DataSink, DataSource

This is EntityFS' take on a random access file. Objects of this type can be had from file entities for randomly accessing their contents. Just like a RandomAccessFile, the RandomAccess object has a file pointer that stores the current offset in the file.

Unlike the RandomAccessFile, this interface does not extend the DataInput or DataOutput interfaces that define methods for reading and writing primitive data types. Any RandomAccess implementation can be adapted to those interfaces by RandomAccessToDataInputOutputAdapter.

For java.io.File-backed file entities, an ordinary java.io.RandomAccessFile can be opened by calling FCFileBacked methods.

Implementations of this interface are not thread safe. Use the ordinary EntityFS locking to restrict concurrent access to objects of this type. Files has methods for opening lock-aware implementations of this interface.

Since:

1.0

Author:

Karl Gustafsson

See Also:

RandomAccessToDataInputOutputAdapter

Method Summary

void	addCloseObserver(RandomAccessCloseObserver raco) Add an observer that is notified when this RandomAccess is closed.
long	getFilePointer() Get the current offset in the file.
RandomAccessMode	getMode() Get the mode that this RandomAccess was opened in.
long	length() Get the file's current length.
void	seek(long pos) Set the file pointer offset, measured from the beginning of the file.
void	setLength(long l) Set the length of the file.

Methods inherited from interface org.entityfs.DataSink

close, flush, write, write, write

Methods inherited from interface org.entityfs.DataSource

available, close, read, read, read, skipBytes

Method Detail

getMode

RandomAccessMode getMode()

Get the mode that this RandomAccess was opened in.

This method does not throw an IllegalStateException if it is called after the RandomAccess has been closed.

Returns:

The mode that this RandomAccess was opened in.

addCloseObserver

void addCloseObserver(RandomAccessCloseObserver raco)

Add an observer that is notified when this RandomAccess is closed. The observers are called just after the RandomAccess has been closed.

Parameters:

raco - The observer.

getFilePointer

long getFilePointer()
                    throws IllegalStateException

Get the current offset in the file.

Returns:

The offset from the beginning of the file.

Throws:

IllegalStateException - If the random access file is closed.

length

long length()
            throws IllegalStateException

Get the file's current length.

Returns:

The file's current length.

Throws:

IllegalStateException - If the random access file is closed.

seek

void seek(long pos)
          throws FileSystemException,
                 IllegalStateException

Set the file pointer offset, measured from the beginning of the file. If the offset is set beyond the end of the file does not change the file length until something is written to it.

Parameters:

pos - The new file pointer offset, measured from the beginning of the file.

Throws:

FileSystemException - If pos < 0.

IllegalStateException - If the random access file is closed.

See Also:

DataSource.skipBytes(long)

setLength

void setLength(long l)
               throws ReadOnlyException,
                      IllegalStateException

Set the length of the file.

If the present length of the file is greater than the l argument, the file will be truncated.

If the new length is bigger than the current length of the file, the file will be extended. The contents of the extended portion of the file are not defined.

The current file pointer is not changed, unless the file pointer offset is greater than the new file length. If so, it will be set to the new length.

Parameters:

l - The new length of the file.

Throws:

IllegalStateException - If the random access file is closed.

ReadOnlyException - If the file is opened read only.

FileSystemException - If the new length is less than 0.