ewe.io
Class RandomStreamObject

java.lang.Object
  ewe.util.Errorable
      ewe.io.BasicStreamObject
          ewe.io.StreamObject
              ewe.io.RandomStreamObject

All Implemented Interfaces:

BasicRandomAccessStream, BasicStream, RandomAccessStream, Stream, Streamable

Direct Known Subclasses:

MemoryFile, RandomAccessFile, RandomStreamAdapter, RewindableStream

public abstract class RandomStreamObject

extends StreamObject

implements RandomAccessStream

Use this to implement a RandomAccessStream object. To do this you must override: setStreamLength(), getStreamLength(), seekPosition(), tellPosition() and the other methods specified in StreamObject.

Field Summary

Fields inherited from class ewe.io.StreamObject

napIterations, napTime, READWRITE_CLOSED, READWRITE_ERROR, READWRITE_WOULDBLOCK

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

RandomStreamObject()

Method Summary

int	getFilePosition() Get the file position.
int	getLength() Gets the length of the open stream.
long	getStreamLength() Gets the length of the open stream.
long	length() Get the current length of the stream.
int	nonBlockingRead(long location, byte[] dest, int offset, int length) Non-blocking read at a particular location.
int	nonBlockingWrite(long location, byte[] src, int offset, int length) Non-blocking write at a particular location.
boolean	seek(int position) Set the file position.
void	seek(long position) Set the stream position.
boolean	seekPosition(long pos) Tell the Stream to move to the specific position.
void	setLength(long length) Set the length of the RandomAccessStream if possible.
boolean	setStreamLength(long length) Set the length of the RandomAccessStream if possible.
long	tell() Get the current stream position.
long	tellPosition() Retrieve the file position.
RandomStream	toRandomStream()

Methods inherited from class ewe.io.StreamObject

close, closeStream, doRead, doWrite, flush, isOpen, nap, nap, nonBlockingRead, nonBlockingWrite, read, readAByte, readBytes, readBytes, write, writeAByte, writeBytes, writeBytes

Methods inherited from class ewe.io.BasicStreamObject

getException, getName, read, read, throwIOException, toInputStream, toOutputStream, toStream, write, write

Methods inherited from class ewe.util.Errorable

returnError, returnError, returnError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Methods inherited from interface ewe.io.BasicRandomAccessStream

canWrite

Methods inherited from interface ewe.io.BasicStream

close, closeStream, flushStream, isOpen, nonBlockingRead, nonBlockingWrite

Methods inherited from interface ewe.io.Stream

flush, read, read, read, readBytes, readBytes, toInputStream, toOutputStream, write, write, write, writeBytes, writeBytes

Constructor Detail

RandomStreamObject

public RandomStreamObject()

Method Detail

setStreamLength

public boolean setStreamLength(long length)
                        throws IOException

Description copied from interface: BasicRandomAccessStream

Set the length of the RandomAccessStream if possible. This is non-blocking, it will return false if the operation is still continuing and true if the operation completed. If the operation could not be performed at all an IOException will be thrown.

Make no assumptions about the success of this method. Not all RAS objects will support setStreamLength() or setLength() - not even all Files on all systems will support this. For example, PersonalJava/Java 1.1 does not support this feature and will throw an IOException.

What happens to the file position pointer after this method is called is unpredictable, especially if you are truncating the file. You should ALWAYS reset the file position pointer after calling this method to be where you wish it to be.

Specified by:

setStreamLength in interface BasicRandomAccessStream

Throws:

IOException

setLength

public void setLength(long length)
               throws IOException

Description copied from interface: RandomAccessStream

Set the length of the RandomAccessStream if possible. This is a blocking call. If the operation could not be performed at all an IOException will be thrown.

Make no assumptions about the success of this method. Not all RAS objects will support setStreamLength() or setLength() - not even all Files on all systems will support this. For example, PersonalJava/Java 1.1 does not support this feature and will throw an IOException.

What happens to the file position pointer after this method is called is unpredictable, especially if you are truncating the file. You should ALWAYS reset the file position pointer after calling this method to be where you wish it to be.

Specified by:

setLength in interface RandomAccessStream

Throws:

IOException

length

public long length()
            throws IOException

Description copied from interface: RandomAccessStream

Get the current length of the stream. This is a blocking call.

Specified by:

length in interface RandomAccessStream

Returns:

the current length of the stream.

Throws:

IOException - if an error occurs.

getLength

public int getLength()

Description copied from interface: RandomAccessStream

Gets the length of the open stream. This is a blocking call

Specified by:

getLength in interface RandomAccessStream

Returns:

the length of the stream.

tell

public long tell()
          throws IOException

Description copied from interface: RandomAccessStream

Get the current stream position. This is a blocking call.

Specified by:

tell in interface RandomAccessStream

Returns:

the current stream position.

Throws:

IOException - if an error occurs.

getFilePosition

public int getFilePosition()

Description copied from interface: RandomAccessStream

Get the file position. This is a blocking call.

Specified by:

getFilePosition in interface RandomAccessStream

Returns:

The file position.

seek

public void seek(long position)
          throws IOException

Description copied from interface: RandomAccessStream

Set the stream position. This is a blocking call.

Specified by:

seek in interface RandomAccessStream

Parameters:

position - The position to seek to.

Throws:

IOException - if an error occurs while seeking.

seek

public boolean seek(int position)

Description copied from interface: RandomAccessStream

Set the file position. This is a blocking call.

Specified by:

seek in interface RandomAccessStream

Parameters:

position - The new file position to set.

Returns:

true on success, false on failure or error.

seekPosition

public boolean seekPosition(long pos)
                     throws IOException

Tell the Stream to move to the specific position. This is a non-blocking call.

Specified by:

seekPosition in interface BasicRandomAccessStream

Parameters:

pos - The position to seek to.

Returns:

true if the seek completed successfully, false if the seek did not complete yet.

Throws:

IOException - if an error occured during the seek.

tellPosition

public long tellPosition()
                  throws IOException

Retrieve the file position. This is non-blocking

Specified by:

tellPosition in interface BasicRandomAccessStream

Returns:

the position of the stream or -1 if the position is not known yet.

Throws:

IOException - if an error occured while getting the position.

getStreamLength

public long getStreamLength()
                     throws IOException

Gets the length of the open stream. This is non-blocking.

Specified by:

getStreamLength in interface BasicRandomAccessStream

Returns:

the length of the stream or -1 if the length is not known yet.

Throws:

IOException - if an error occured while getting the length.

nonBlockingRead

public int nonBlockingRead(long location,
                           byte[] dest,
                           int offset,
                           int length)
                    throws IOException

Description copied from interface: BasicRandomAccessStream

Non-blocking read at a particular location. Used if there are multiple threads reading/writing to a RandomAccessStream.

Specified by:

nonBlockingRead in interface BasicRandomAccessStream

Parameters:

location - The location to read from.

dest - The destination buffer.

offset - The location in the buffer to hold the data.

length - The number of bytes to read.

Returns:

0 = No bytes available now, -1 = End of stream, >0 = Number of bytes read.

Throws:

IOException - if an error occured during reading.

nonBlockingWrite

public int nonBlockingWrite(long location,
                            byte[] src,
                            int offset,
                            int length)
                     throws IOException

Description copied from interface: BasicRandomAccessStream

Non-blocking write at a particular location. Used if there are multiple threads reading/writing to a RandomAccessStream.

Specified by:

nonBlockingWrite in interface BasicRandomAccessStream

Parameters:

location - The location to write to.

src - The source buffer.

offset - The location in the buffer that holds the data.

length - The number of bytes to write.

Returns:

0 = No bytes can be written now, >0 = Number of bytes written.

Throws:

IOException - if an error occured during writing.

toRandomStream

public RandomStream toRandomStream()

Specified by:

toRandomStream in interface RandomAccessStream