ewe.io
Interface BasicRandomAccessStream

All Superinterfaces:

BasicStream

All Known Subinterfaces:

RandomAccessStream

All Known Implementing Classes:

RandomStreamObject

public interface BasicRandomAccessStream

extends BasicStream

Method Summary

boolean	canWrite() Tests if the RandomAccessStream was opened in read-write mode as opposed to read-ony mode.
long	getStreamLength() Gets the length of the open 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	seekPosition(long pos) Tell the Stream to move to the specific position.
boolean	setStreamLength(long newLength) Set the length of the RandomAccessStream if possible.
long	tellPosition() Retrieve the file position.

Methods inherited from interface ewe.io.BasicStream

close, closeStream, flushStream, isOpen, nonBlockingRead, nonBlockingWrite

Method Detail

seekPosition

public boolean seekPosition(long pos)
                     throws IOException

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

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

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.

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.

setStreamLength

public boolean setStreamLength(long newLength)
                        throws IOException

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.

Throws:

IOException

nonBlockingRead

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

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

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

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

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.

canWrite

public boolean canWrite()

Tests if the RandomAccessStream was opened in read-write mode as opposed to read-ony mode.