Package org.refcodes.io

Class AbstractByteReceiver

java.lang.Object

org.refcodes.io.AbstractByteProvider

org.refcodes.io.AbstractByteReceiver

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, ByteBlockProvider, ByteBlockReceiver, ByteDatagramProvider, ByteDatagramReceiver, ByteProvider, ByteReceiver, Receivable, org.refcodes.mixin.Loggable, org.refcodes.mixin.Releaseable

Direct Known Subclasses:

AbstractPrefetchInputStreamByteReceiver, ByteArrayReceiverImpl, ByteReceiverDecorator, LoopbackByteReceiverImpl, LoopbackByteTransceiverImpl

public abstract class AbstractByteReceiver
extends AbstractByteProvider
implements ByteReceiver

The AbstractByteReceiver 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 AbstractByteProvider.pushDatagram(byte) and which can be retrieved via readDatagram(). The AbstractByteProvider.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 AbstractByteProvider.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	AbstractByteReceiver.ConnectableAutomaton	The Class ConnectableAutomaton.

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.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 AbstractByteReceiver.ConnectableAutomaton	_automaton

Fields inherited from class org.refcodes.io.AbstractByteProvider

_datagramQueue, DATAGRAM_QUEUE_SIZE

Fields inherited from interface org.refcodes.mixin.Loggable

RUNTIME_LOGGER_CLASS, RUNTIME_LOGGER_FACTORY_CLASS, RUNTIME_LOGGER_FACTORY_METHOD

Constructor Summary

Constructors

Constructor	Description
AbstractByteReceiver()	Constructs a AbstractByteReceiver with a default sized blocking queue enabling a maximum of AbstractByteProvider.DATAGRAM_QUEUE_SIZE datagrams. ------------------------------------------------------------------------- Make sure your code fetches the datagrams quick enough to prevent filling up of the queue.
AbstractByteReceiver(int aCapacity)	Constructs a AbstractByteReceiver 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()
org.refcodes.component.ConnectionStatus	getConnectionStatus()
boolean	hasDatagram()	Determines whether a datagram is available from a DatagramSender.
boolean	isClosable()
boolean	isClosed()
protected boolean	isOpenable()	Checks if is openable.
boolean	isOpened()
protected void	open()	Open.
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.
void	releaseAll()
protected void	setConnectionStatus(org.refcodes.component.ConnectionStatus aConnectionStatus)	Sets the connection status.

Methods inherited from class org.refcodes.io.AbstractByteProvider

pushDatagram, pushDatagrams, pushDatagrams

Methods inherited from interface org.refcodes.component.Closable

closeIn, closeQuietly, closeUnchecked

Methods inherited from interface org.refcodes.component.ConnectionStatusAccessor

isConnectionOpened

Methods inherited from interface org.refcodes.mixin.Loggable

alert, alert, critical, critical, debug, error, info, notice, panic, trace, warn, warn

Methods inherited from class java.lang.Object

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

Field Detail

_automaton

protected AbstractByteReceiver.ConnectableAutomaton _automaton

Constructor Detail

AbstractByteReceiver

public AbstractByteReceiver()

Constructs a AbstractByteReceiver with a default sized blocking queue enabling a maximum of AbstractByteProvider.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 AbstractByteProvider.pushDatagram(byte) to the queue is blocked until elements are taken from the queue via readDatagram().

AbstractByteReceiver

public AbstractByteReceiver(int aCapacity)

Constructs a AbstractByteReceiver 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 AbstractByteProvider.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

Overrides:

readDatagram in class AbstractByteProvider

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

Specified by:

readDatagrams in interface ByteReceiver

Overrides:

readDatagrams in class AbstractByteProvider

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

Specified by:

readDatagrams in interface ByteReceiver

Overrides:

readDatagrams in class AbstractByteProvider

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.

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

Throws:

org.refcodes.component.CloseException

releaseAll

public void releaseAll()

Specified by:

releaseAll in interface org.refcodes.mixin.Releaseable

isOpened

public boolean isOpened()

Specified by:

isOpened in interface org.refcodes.component.OpenedAccessor

isClosable

public boolean isClosable()

Specified by:

isClosable in interface org.refcodes.component.Closable.CloseAutomaton

isClosed

public boolean isClosed()

Specified by:

isClosed in interface org.refcodes.component.ClosedAccessor

getConnectionStatus

public org.refcodes.component.ConnectionStatus getConnectionStatus()

Specified by:

getConnectionStatus in interface org.refcodes.component.ConnectionStatusAccessor

open

protected void open()
             throws org.refcodes.component.OpenException

Open.

Throws:

org.refcodes.component.OpenException - the open exception

setConnectionStatus

protected void setConnectionStatus(org.refcodes.component.ConnectionStatus aConnectionStatus)

Sets the connection status.

Parameters:

aConnectionStatus - the new connection status

isOpenable

protected boolean isOpenable()

Checks if is openable.

Returns:

true, if is openable