org.entityfs
Interface DataSource

All Known Subinterfaces:
RandomAccess
All Known Implementing Classes:
ByteArrayRandomAccess, CountingDataSource, DataInputOutputRandomAccessAdapter, EmptyRandomAccess, InputStreamBackedRandomAccess, InputStreamToDataSourceAdapter, LockAwareRandomAccess, RandomAccessAdapter, RandomAccessToDataInputOutputAdapter, RangeRandomAccess, TempFileBackedRandomAccess

public interface DataSource

This interface defines a source for data, i.e. something that data can be read from.

An InputStream can be adapted to a data source using the InputStreamToDataSourceAdapter.

Since:
1.1
Author:
Karl Gustafsson

Method Summary
 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 source and free all resources associated with it.
 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.
 long skipBytes(long n)
          Attempt to skip over n bytes in the source.
 

Method Detail

available

int available()
              throws IllegalStateException,
                     WrappedIOException
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.

Returns:
An estimate of the number of bytes that can be read without blocking.
Throws:
IllegalStateException - If the source is closed.
WrappedIOException - On I/O errors.
See Also:
InputStream.available()

read

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

Returns:
The next byte of data, or -1 if the end of the source has been reached.
Throws:
IllegalStateException - If the source is closed.
WrappedIOException - On I/O errors.

read

int read(byte[] barr)
         throws IllegalStateException,
                WrappedIOException
Read up to b.length bytes of data from the source into the array.

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.
WrappedIOException - On I/O errors.

read

int read(byte[] barr,
         int off,
         int len)
         throws IllegalStateException,
                WrappedIOException
Read up to len bytes of data from the source into the array.

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.
WrappedIOException - On I/O errors.

skipBytes

long skipBytes(long n)
               throws IllegalStateException
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)).

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)

close

void close()
           throws WrappedIOException
Close the source and free all resources associated with it. If the object is already closed, this method does nothing.

Throws:
WrappedIOException - On I/O errors.