datasource
Class DataSource

java.lang.Object
  datasource.DataSource

Direct Known Subclasses:

FileSource, NetSource, NullSource

public abstract class DataSource
extends java.lang.Object

DataSource: abstract base class for components that provide data through read() calls by their client.

A DataSource contains a thread of its own. When created, the thread is started, and goes into a loop reading data from its source and putting into a buffer. A client thread call to the read() method takes data out of the buffer, if there is any, and blocks until there is some if the buffer is currently empty. Thre read() interface operates on bytes -- the client asks for some maximum number of bytes. However, reading data a byte at a time from data sources (like files or network connections) is slow. Instead, the DataSource wants to read bigger chunks for its own source. For that reason, the internal data buffer kept by a DataSource is an array of DataRecords. Each DataRecord is a byte[], of some reasonable size. The read thread in the DataSource tries to fetch a full DataRecord from its data source whenever it does a read.

Version:

$Id: DataSource.java,v 1.11 2010/01/05 19:02:15 zahorjan Exp $

Nested Class Summary

private class

DataSource.ReceiveHelper Helper class to implement reading thread.

Field Summary

private static int	BUFFER_SIZE Size of dataBuffer;
private java.util.concurrent.Semaphore	bufferSemaphore A semaphore to coordinate access to the dataBuffer.
static int	CLOSED
static int	CONNECTED
private java.util.concurrent.ArrayBlockingQueue<DataRecord>	dataBuffer The data buffer between the local, reader thread and the client thread.
private java.lang.Thread	reader The reader thread (fetches data from this object's source and puts it in dataBuffer).
private static int	RECORD_SIZE Size of each DataRecord in the buffer.
private DataRecordManager	recordManager Object that knows how to create/cache DataRecords.
static int	STARTING We need to keep track of what state the input source is in.
protected int	state

Constructor Summary

protected

DataSource() Creates a new DataSource.

Method Summary

int	read(byte[] buf, int maxLength) Reads up to maxLength bytes and returns them via argument buf, starting at position 0.
protected abstract int	readFromSrc(byte[] buf, int len) The ReceiveHelper implemented here depends on this abstract method being implemented by the instantiated class.
void	readyToRead() Function to initialize (called by derived class constructor).
abstract void	reInit() All derived classes must be capable of reinitializing themselves.

Methods inherited from class java.lang.Object

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

Field Detail

dataBuffer

private java.util.concurrent.ArrayBlockingQueue<DataRecord> dataBuffer

The data buffer between the local, reader thread and the client thread. (Accessed by client via the read() method.)

bufferSemaphore

private java.util.concurrent.Semaphore bufferSemaphore

A semaphore to coordinate access to the dataBuffer.

recordManager

private DataRecordManager recordManager

Object that knows how to create/cache DataRecords.

BUFFER_SIZE

private static final int BUFFER_SIZE

Size of dataBuffer;

See Also:

Constant Field Values

RECORD_SIZE

private static final int RECORD_SIZE

Size of each DataRecord in the buffer.

See Also:

Constant Field Values

reader

private java.lang.Thread reader

The reader thread (fetches data from this object's source and puts it in dataBuffer).

STARTING

public static final int STARTING

We need to keep track of what state the input source is in.

• STARTING: object created but not yet connected to its own input
• CONNECTED: object created and connected to its input
• CLOSE_WAIT: object's source is out of data, but there is still data in the data buffer available to the client via read()
• CLOSED: out of data. Further read() invocations are errors.

  See Also:

  Constant Field Values

CONNECTED

public static final int CONNECTED

See Also:

Constant Field Values

CLOSED

public static final int CLOSED

See Also:

Constant Field Values

state

protected int state

Constructor Detail

DataSource

protected DataSource()

Creates a new DataSource.

Method Detail

readFromSrc

protected abstract int readFromSrc(byte[] buf,
                                   int len)
                            throws java.io.IOException

The ReceiveHelper implemented here depends on this abstract method being implemented by the instantiated class. That method should read from the DataSource's input source, returning the number of bytes read or 0 if there are no more.

Throws:

java.io.IOException

reInit

public abstract void reInit()
                     throws java.io.IOException,
                            java.io.FileNotFoundException

All derived classes must be capable of reinitializing themselves.

Throws:

java.io.IOException

java.io.FileNotFoundException

readyToRead

public void readyToRead()

Function to initialize (called by derived class constructor).

read

public int read(byte[] buf,
                int maxLength)
         throws java.io.IOException,
                java.lang.InterruptedException

Reads up to maxLength bytes and returns them via argument buf, starting at position 0. This method is synchronized because it performs read/update/write on the head element of the list. If the client were multithreaded (which it's not) that could lead to trouble.

Throws:

java.io.IOException

java.lang.InterruptedException