org.entityfs.util.io
Class RangeRandomAccess

java.lang.Object
  org.entityfs.util.io.RangeRandomAccess

All Implemented Interfaces:

DataSink, DataSource, RandomAccess

public class RangeRandomAccess
extends Object
implements RandomAccess

This is a RandomAccess object that reads data from and writes data to a section of another RandomAccess object. Data cannot be accessed before the section's lower limit or after the section's upper limit.

If the client attempts to write over the upper limit, the write methods throw an UnexpectedEofException.

This object is not safe to use concurrently from several threads without external synchronization.

Since:

1.1

Author:

Karl Gustafsson

See Also:

RangeInputStream

Constructor Summary

RangeRandomAccess(RandomAccess adapted, long lowerLimit, long upperLimit)
Create a new range random access.

Method Summary

void	addCloseObserver(RandomAccessCloseObserver raco) Add an observer that is notified when this RandomAccess is closed.
protected void	assertNotClosed() This method throws an IllegalStateException if this random access object has been closed.
protected void	assertNotReadOnly() This method throws a ReadOnlyException if this random access is opened read only.
int	available() Returns an estimate of the number of bytes that can be read from this data source without blocking by the next invocation of a method for this data source.
void	close() Close the sink and free all resources associated with it.
protected void	finalize()
void	flush() Flush changes made to the sink to the underlying storage.
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.
int	read() Read a byte of data from the source.
int	read(byte[] barr) Read up to b.length bytes of data from the source into the array.
int	read(byte[] barr, int off, int len) Read up to len bytes of data from the source into the array.
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.
long	skipBytes(long n) Attempt to skip over n bytes in the source.
void	write(byte[] barr) Write the contents of the array to the sink, starting at the current file pointer.
void	write(byte[] barr, int off, int len) Write len bytes from the array, starting at the offset off to this sink.
void	write(int b) Write a byte to the sink.

Methods inherited from class java.lang.Object

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

Constructor Detail

RangeRandomAccess

public RangeRandomAccess(RandomAccess adapted,
                         long lowerLimit,
                         long upperLimit)
                  throws IllegalArgumentException

Create a new range random access. The current file pointer of the created object is 0, which means that it will be at the lower limit.

The total length of the range is upperLimit - lowerLimit + 1 bytes.

The upper limit, or even the complete range, may be beyond the current end of the supplied random access object. This object will behave as expected when trying to access data beyond the end of the file; reading methods will return -1 and writing methods will extend the file.

Parameters:

adapted - The random access object to read data from and/or write data to. If this object is opened read only, this object becomes read only too.

lowerLimit - The lower limit. The byte at this position will be the first visible byte in the range.

upperLimit - The upper limit. The byte at this position will be the last visible byte in the range.

Throws:

IllegalArgumentException - If the lower limit is negative or if the upper limit is less than the lower limit.

Method Detail

assertNotClosed

protected void assertNotClosed()
                        throws IllegalStateException

This method throws an IllegalStateException if this random access object has been closed.

Throws:

IllegalStateException - If this random access object has been closed.

assertNotReadOnly

protected void assertNotReadOnly()
                          throws ReadOnlyException

This method throws a ReadOnlyException if this random access is opened read only.

Throws:

ReadOnlyException - If this random access is opened read only.

addCloseObserver

public void addCloseObserver(RandomAccessCloseObserver raco)

Description copied from interface: RandomAccess

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

Specified by:

addCloseObserver in interface RandomAccess

Parameters:

raco - The observer.

getMode

public RandomAccessMode getMode()

Description copied from interface: RandomAccess

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.

Specified by:

getMode in interface RandomAccess

Returns:

The mode that this RandomAccess was opened in.

flush

public void flush()
           throws ReadOnlyException,
                  IllegalStateException

Description copied from interface: DataSink

Flush changes made to the sink to the underlying storage. This is optional to implement, but read only sinks should always throw ReadOnlyException.

Specified by:

flush in interface DataSink

Throws:

ReadOnlyException - If the sink is opened read only.

IllegalStateException - If the sink is closed.

getFilePointer

public long getFilePointer()
                    throws IllegalStateException

Description copied from interface: RandomAccess

Get the current offset in the file.

Specified by:

getFilePointer in interface RandomAccess

Returns:

The offset from the beginning of the file.

Throws:

IllegalStateException - If the random access file is closed.

available

public int available()

Description copied from interface: DataSource

Returns an estimate of the number of bytes that can be read from this data source without blocking by the next invocation of a method for this data source.

Specified by:

available in interface DataSource

Returns:

An estimate of the number of bytes that can be read without blocking.

See Also:

InputStream.available()

length

public long length()
            throws IllegalStateException

Description copied from interface: RandomAccess

Get the file's current length.

Specified by:

length in interface RandomAccess

Returns:

The file's current length.

Throws:

IllegalStateException - If the random access file is closed.

read

public int read()
         throws IllegalStateException

Description copied from interface: DataSource

Read a byte of data from the source. The byte is returned as an integer in the range 0 to 255 (0x00-0x0ff).

Specified by:

read in interface DataSource

Returns:

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

Throws:

IllegalStateException - If the source is closed.

read

public int read(byte[] barr)
         throws IllegalStateException

Description copied from interface: DataSource

Read up to b.length bytes of data from the source into the array.

Specified by:

read in interface DataSource

Parameters:

barr - The byte array into which data is read.

Returns:

The total number of bytes read into the array, or -1 if no data could be read because the the end of the source was reached before the read started.

Throws:

IllegalStateException - If the source is closed.

read

public int read(byte[] barr,
                int off,
                int len)
         throws IllegalStateException

Description copied from interface: DataSource

Read up to len bytes of data from the source into the array.

Specified by:

read in interface DataSource

Parameters:

barr - The byte array into which data is read.

off - The start offset in the array b at which data is written.

len - The maximum number of bytes to read.

Returns:

The total number of bytes read into the array, or -1 if no data could be read because the end of the source was reached before the read started.

Throws:

IllegalStateException - If the source is closed.

seek

public void seek(long pos)
          throws FileSystemException,
                 IllegalStateException

Description copied from interface: RandomAccess

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.

Specified by:

seek in interface RandomAccess

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

public void setLength(long l)
               throws ReadOnlyException,
                      IllegalStateException,
                      FileSystemException

Description copied from interface: RandomAccess

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.

Specified by:

setLength in interface RandomAccess

Parameters:

l - The new length of the file.

Throws:

ReadOnlyException - If the file is opened read only.

IllegalStateException - If the random access file is closed.

FileSystemException - If the new length is less than 0.

skipBytes

public long skipBytes(long n)
               throws IllegalStateException

Description copied from interface: DataSource

Attempt to skip over n bytes in the source. If n is negative, no bytes are skipped.

The pointer in the source cannot be moved beyond EOF using this method (unlike RandomAccess.seek(long)).

Specified by:

skipBytes in interface DataSource

Parameters:

n - The number of bytes to increment the source pointer with.

Returns:

The number of bytes actually skipped.

Throws:

IllegalStateException - If the source is closed.

See Also:

RandomAccess.seek(long)

write

public void write(byte[] barr)
           throws ReadOnlyException,
                  IllegalStateException,
                  UnexpectedEofException

Description copied from interface: DataSink

Write the contents of the array to the sink, starting at the current file pointer.

Specified by:

write in interface DataSink

Parameters:

barr - The array to write.

Throws:

UnexpectedEofException - If the client tries to write beyond the upper limit.

ReadOnlyException - If the sink is opened read only.

IllegalStateException - If the sink is closed.

write

public void write(byte[] barr,
                  int off,
                  int len)
           throws ReadOnlyException,
                  IllegalStateException,
                  UnexpectedEofException

Description copied from interface: DataSink

Write len bytes from the array, starting at the offset off to this sink.

Specified by:

write in interface DataSink

Parameters:

barr - The byte array.

off - The starting offset in the array.

len - The number of bytes to write.

Throws:

UnexpectedEofException - If the client tries to write beyond the upper limit.

ReadOnlyException - If the sink is opened read only.

IllegalStateException - If the sink file is closed.

write

public void write(int b)
           throws ReadOnlyException,
                  IllegalStateException,
                  UnexpectedEofException

Description copied from interface: DataSink

Write a byte to the sink.

Specified by:

write in interface DataSink

Parameters:

b - The byte to write.

Throws:

UnexpectedEofException - If the client tries to write beyond the upper limit.

ReadOnlyException - If the sink is opened read only.

IllegalStateException - If the random access file is closed.

close

public void close()

Description copied from interface: DataSink

Close the sink and free all resources associated with it. If the object is already closed, this method does nothing.

Specified by:

close in interface DataSink

Specified by:

close in interface DataSource

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable