Package org.refcodes.io

Class AbstractByteProvider

java.lang.Object

org.refcodes.io.AbstractByteProvider

All Implemented Interfaces:

ByteBlockProvider, ByteDatagramProvider, ByteProvider

Direct Known Subclasses:

AbstractByteReceiver, ByteArrayProviderImpl

public abstract class AbstractByteProvider
extends Object
implements ByteProvider

The AbstractByteProvider is a base abstract implementation of the ByteReceiver interface providing common functionality for concrete real live ByteDatagramReceiver and ByteBlockReceiver (= ByteReceiver) implementations. A blocking queue is used internally to which received datagrams are put via pushDatagram(byte) and which can be retrieved via readDatagram(). The pushDatagram(byte) method is your hook when extending this class. Make sure your code fetches the datagrams quick enough to prevent filling up of the queue. In case the queue is filled up, adding elements via pushDatagram(byte) to the queue is blocked until elements are taken from the queue via readDatagram(). So cautions are taken to prevent a memory leak.

Field Summary

Fields

Modifier and Type	Field	Description
protected LinkedBlockingQueue<Byte>	_datagramQueue
static int	DATAGRAM_QUEUE_SIZE

Constructor Summary

Constructors

Constructor	Description
AbstractByteProvider()	Constructs a AbstractByteProvider with a default sized blocking queue enabling a maximum of DATAGRAM_QUEUE_SIZE datagrams. ------------------------------------------------------------------------- Make sure your code fetches the datagrams quick enough to prevent filling up of the queue.
AbstractByteProvider(int aCapacity)	Constructs a AbstractByteProvider with a custom sized blocking queue enabling a maximum of datagrams as specified by the capacity parameter. ------------------------------------------------------------------------- Make sure your code fetches the datagrams quick enough to prevent filling up of the queue.

Method Summary

Modifier and Type	Method	Description
protected void	pushDatagram(byte aDatagram)	Pushes a datagram into the receiver and puts it into the blocking queue containing the so far received datagrams.
protected void	pushDatagrams(byte[] aDatagrams)	Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams.
protected void	pushDatagrams(byte[] aDatagrams, int aOffset, int aLength)	Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams.
byte	readDatagram()	Reads (receives) the next byte passed from a DatagramSender counterpart.
byte[]	readDatagrams()	Caution: Reads till an OpenException (or an InterruptedException in case of blocking till more data is available) occurs.
byte[]	readDatagrams(int aBlockSize)	Similar to ByteBlockProvider.readDatagrams() though at maximum the amount of data as provided by the block-size is returned.

Methods inherited from class java.lang.Object

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

Field Detail

DATAGRAM_QUEUE_SIZE

public static final int DATAGRAM_QUEUE_SIZE

See Also:

Constant Field Values

_datagramQueue

protected LinkedBlockingQueue<Byte> _datagramQueue

Constructor Detail

AbstractByteProvider

public AbstractByteProvider()

Constructs a AbstractByteProvider with a default sized blocking queue enabling a maximum of DATAGRAM_QUEUE_SIZE datagrams. ------------------------------------------------------------------------- Make sure your code fetches the datagrams quick enough to prevent filling up of the queue. In case the queue is filled up, adding elements via pushDatagram(byte) to the queue is blocked until elements are taken from the queue via readDatagram().

AbstractByteProvider

public AbstractByteProvider(int aCapacity)

Constructs a AbstractByteProvider with a custom sized blocking queue enabling a maximum of datagrams as specified by the capacity parameter. ------------------------------------------------------------------------- Make sure your code fetches the datagrams quick enough to prevent filling up of the queue. In case the queue is filled up, adding elements via pushDatagram(byte) to the queue is blocked until elements are taken from the queue via readDatagram().

Parameters:

aCapacity - The capacity of the queue holding the received datagrams.

Method Detail

readDatagram

public byte readDatagram()
                  throws org.refcodes.component.OpenException,
                         InterruptedException

Reads (receives) the next byte passed from a DatagramSender counterpart. In case none byte is available, then this method blocks until one is available. To prevent blocking, use the ByteDatagramReceiver extension's Receivable.hasDatagram() method to test beforehand whether a byte is available (in a multi-threaded usage scenario, Receivable.hasDatagram() is not a reliable indicator whether this method will block or not). When a Thread is waiting for a byte to be read and Thread.interrupt() is being called, then the operation is aborted and an InterruptedException is thrown.

Specified by:

readDatagram in interface ByteDatagramProvider

Returns:

The next byte sent from the ByteDatagramSender counterpart.

Throws:

org.refcodes.component.OpenException - Thrown in case opening or accessing an open line (connection, junction, link) caused problems.

InterruptedException - Thrown when a Thread is waiting, sleeping, or otherwise occupied, and the Thread is interrupted, either before or during the activity.

readDatagrams

public byte[] readDatagrams()
                     throws org.refcodes.component.OpenException,
                            InterruptedException

Caution: Reads till an OpenException (or an InterruptedException in case of blocking till more data is available) occurs. Reads (receives) the next byte block passed from a BlockSender or DatagramSender counterpart. In case none byte block is available, then this method blocks until one is available. When a Thread is waiting for a byte to be read and Thread.interrupt() is being called, then the operation is aborted and an InterruptedException is thrown.

Specified by:

readDatagrams in interface ByteBlockProvider

Specified by:

readDatagrams in interface ByteProvider

Returns:

The next byte block sent from the BlockSender or DatagramReceiver counterpart.

Throws:

org.refcodes.component.OpenException - Thrown in case opening or accessing an open line (connection, junction, link) caused problems.

InterruptedException - Thrown when a Thread is waiting, sleeping, or otherwise occupied, and the Thread is interrupted, either before or during the activity.

readDatagrams

public byte[] readDatagrams(int aBlockSize)
                     throws org.refcodes.component.OpenException,
                            InterruptedException

Similar to ByteBlockProvider.readDatagrams() though at maximum the amount of data as provided by the block-size is returned.

Specified by:

readDatagrams in interface ByteBlockProvider

Specified by:

readDatagrams in interface ByteProvider

Parameters:

aBlockSize - The block-size which is not to exceeded by the returned data. A value of -1 specifies to retrieve all available datagrams (same behavior as method ByteBlockProvider.readDatagrams().

Returns:

The next short block sent from the BlockSender or DatagramReceiver counterpart.

Throws:

org.refcodes.component.OpenException - Thrown in case opening or accessing an open line (connection, junction, link) caused problems.

InterruptedException - Thrown when a Thread is waiting, sleeping, or otherwise occupied, and the Thread is interrupted, either before or during the activity.

pushDatagram

protected void pushDatagram(byte aDatagram)
                     throws org.refcodes.component.OpenException

Pushes a datagram into the receiver and puts it into the blocking queue containing the so far received datagrams. Them datagrams can be retrieved via readDatagram(): Use AbstractByteReceiver extension's AbstractByteReceiver.hasDatagram() to test beforehand whether there is a datagram available.

Parameters:

aDatagram - The datagram to be pushed at the end of the blocking queue; to be retrieved with the readDatagram() method.

Throws:

org.refcodes.component.OpenException - the open exception

pushDatagrams

protected void pushDatagrams(byte[] aDatagrams)
                      throws org.refcodes.component.OpenException

Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams. Them datagrams can be retrieved via readDatagram(): Use AbstractByteReceiver extension's AbstractByteReceiver.hasDatagram() to test beforehand whether there is a datagram available.

Parameters:

aDatagrams - The datagrams to be pushed at the end of the blocking queue; to be retrieved with the readDatagram() method.

Throws:

org.refcodes.component.OpenException - the open exception

pushDatagrams

protected void pushDatagrams(byte[] aDatagrams,
                             int aOffset,
                             int aLength)
                      throws org.refcodes.component.OpenException

Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams. Them datagrams can be retrieved via readDatagram(): Use AbstractByteReceiver extension's AbstractByteReceiver.hasDatagram() to test beforehand whether there is a datagram available.

Parameters:

aDatagrams - The datagrams to be pushed at the end of the blocking queue; to be retrieved with the readDatagram() method.

aOffset - The offset to start taking data from to be pushed.

aLength - The number of elements to be pushed from the offset onwards.

Throws:

org.refcodes.component.OpenException - the open exception