Package org.refcodes.io

Class AbstractShortReceiver

java.lang.Object

org.refcodes.component.AbstractConnectableAutomaton

org.refcodes.io.AbstractShortReceiver

All Implemented Interfaces:

org.refcodes.component.Closable, org.refcodes.component.Closable.CloseAutomaton, org.refcodes.component.ClosedAccessor, org.refcodes.component.ConnectableComponent, org.refcodes.component.ConnectableComponent.ConnectableAutomaton, org.refcodes.component.ConnectionStatusAccessor, org.refcodes.component.OpenedAccessor, Receivable, ShortBlockProvider, ShortBlockReceiver, ShortDatagramProvider, ShortDatagramReceiver, ShortProvider, ShortReceiver, org.refcodes.mixin.Releaseable

Direct Known Subclasses:

LoopbackShortReceiverImpl, LoopbackShortTransceiverImpl, ShortArrayReceiverImpl, ShortReceiverDecorator

public abstract class AbstractShortReceiver
extends org.refcodes.component.AbstractConnectableAutomaton
implements ShortReceiver

The AbstractShortReceiver is a base abstract implementation of the ShortReceiver interface providing common functionality for concrete real live ShortDatagramReceiver and ShortBlockReceiver (= ShortReceiver) implementations. A blocking queue is used internally to which received datagrams are put via pushDatagram(short) and which can be retrieved via readDatagram(). The pushDatagram(short) 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(short) to the queue is blocked until elements are taken from the queue via readDatagram(). So cautions are taken to prevent a memory leak.

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.component.Closable

org.refcodes.component.Closable.CloseAutomaton, org.refcodes.component.Closable.CloseBuilder<B extends org.refcodes.component.Closable.CloseBuilder<B>>

Nested classes/interfaces inherited from interface org.refcodes.component.ClosedAccessor

org.refcodes.component.ClosedAccessor.ClosedMutator, org.refcodes.component.ClosedAccessor.ClosedProperty

Nested classes/interfaces inherited from interface org.refcodes.component.ConnectableComponent

org.refcodes.component.ConnectableComponent.ConnectableAutomaton

Nested classes/interfaces inherited from interface org.refcodes.component.ConnectionStatusAccessor

org.refcodes.component.ConnectionStatusAccessor.ConnectionStatusMutator, org.refcodes.component.ConnectionStatusAccessor.ConnectionStatusProperty

Nested classes/interfaces inherited from interface org.refcodes.component.OpenedAccessor

org.refcodes.component.OpenedAccessor.OpenedMutator, org.refcodes.component.OpenedAccessor.OpenedProperty

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
AbstractShortReceiver()	Constructs a AbstractShortReceiver 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.
AbstractShortReceiver(int aCapacity)	Constructs a AbstractShortReceiver 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
void	close()
boolean	hasDatagram()	Determines whether a datagram is available from a DatagramSender.
protected void	pushDatagram(short aDatagram)	Pushes a datagram into the receiver and puts it into the blocking queue containing the so far received datagrams.
protected void	pushDatagrams(short[] aDatagrams)	Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams.
protected void	pushDatagrams(short[] aDatagrams, int aOffset, int aLength)	Pushes datagrams into the receiver and puts them into the blocking queue containing the so far received datagrams.
short	readDatagram()	Reads (receives) the next short passed from a DatagramSender counterpart.
short[]	readDatagrams()	Caution: Reads till an OpenException (or an InterruptedException in case of blocking till more data is available) occurs.
short[]	readDatagrams(int aBlockSize)	Similar to ShortBlockProvider.readDatagrams() though at maximum the amount of data as provided by the block-size is returned.
void	releaseAll()

Methods inherited from class org.refcodes.component.AbstractConnectableAutomaton

getConnectionStatus, isClosable, isClosed, isOpenable, isOpened, open, setConnectionStatus

Methods inherited from interface org.refcodes.component.Closable

closeIn, closeQuietly, closeUnchecked

Methods inherited from interface org.refcodes.component.Closable.CloseAutomaton

isClosable

Methods inherited from interface org.refcodes.component.ClosedAccessor

isClosed

Methods inherited from interface org.refcodes.component.ConnectionStatusAccessor

getConnectionStatus, isConnectionOpened

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.refcodes.component.OpenedAccessor

isOpened

Field Detail

DATAGRAM_QUEUE_SIZE

public static final int DATAGRAM_QUEUE_SIZE

See Also:

Constant Field Values

_datagramQueue

protected LinkedBlockingQueue<Short> _datagramQueue

Constructor Detail

AbstractShortReceiver

public AbstractShortReceiver()

Constructs a AbstractShortReceiver 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(short) to the queue is blocked until elements are taken from the queue via readDatagram().

AbstractShortReceiver

public AbstractShortReceiver(int aCapacity)

Constructs a AbstractShortReceiver 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(short) 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 short readDatagram()
                   throws org.refcodes.component.OpenException,
                          InterruptedException

Reads (receives) the next short passed from a DatagramSender counterpart. In case none short is available, then this method blocks until one is available. To prevent blocking, use the ShortDatagramReceiver 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 short to be read and Thread.interrupt() is being called, then the operation is aborted and an InterruptedException is thrown.

Specified by:

readDatagram in interface ShortDatagramProvider

Returns:

The next short sent from the ShortDatagramSender 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 short[] 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 short block passed from a BlockSender or DatagramSender counterpart. In case none short block is available, then this method blocks until one is available. When a Thread is waiting for a short to be read and Thread.interrupt() is being called, then the operation is aborted and an InterruptedException is thrown.

Specified by:

readDatagrams in interface ShortBlockProvider

Specified by:

readDatagrams in interface ShortProvider

Specified by:

readDatagrams in interface ShortReceiver

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.

readDatagrams

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

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

Specified by:

readDatagrams in interface ShortBlockProvider

Specified by:

readDatagrams in interface ShortProvider

Specified by:

readDatagrams in interface ShortReceiver

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 ShortBlockProvider.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.

hasDatagram

public boolean hasDatagram()
                    throws org.refcodes.component.OpenException

Determines whether a datagram is available from a DatagramSender. Use the DatagramProvider extenison's DatagramProvider.readDatagram() method for retrieving the available datagram.

Specified by:

hasDatagram in interface Receivable

Returns:

True in case there is a datagram ready to be retrieved .

Throws:

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

close

public void close()
           throws org.refcodes.component.CloseException

Specified by:

close in interface org.refcodes.component.Closable

Overrides:

close in class org.refcodes.component.AbstractConnectableAutomaton

Throws:

org.refcodes.component.CloseException

releaseAll

public void releaseAll()

Specified by:

releaseAll in interface org.refcodes.mixin.Releaseable

pushDatagram

protected void pushDatagram(short 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 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(short[] 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 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(short[] 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 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