Module org.refcodes.serial

Package org.refcodes.serial

Class MagicBytesSectionDispatcher

java.lang.Object

org.refcodes.serial.AbstractMagicBytesTransmissionDispatcher<Section>

org.refcodes.serial.MagicBytesSectionDispatcher

All Implemented Interfaces:

Serializable, Iterable<Section>, org.refcodes.mixin.ChildrenAccessor<Section[]>, org.refcodes.mixin.LengthAccessor, Section, Transmission

public class MagicBytesSectionDispatcher
extends AbstractMagicBytesTransmissionDispatcher<Section>
implements Section, Iterable<Section>, org.refcodes.mixin.ChildrenAccessor<Section[]>

THe MagicBytesSectionDispatcher dispatches a transmission to one of the aggregated Section instances depending on the magic number provided by the transmission. A transmission is passed to each of the aggregated Section instances till one Section accepts the transmission, e.g. until a Section does not throw a BadMagicBytesException. To enforce throwing a BadMagicBytesException use a magic bytes Segment or Section which enforces the magic bytes to of a transmission to match its own magic bytes, e.e. use one of the following: AssertMagicBytesSectionDecorator, AssertMagicBytesSegment, AssertMagicBytesSegmentDecorator Attention: A Section throwing a TransmissionException other than a BadMagicBytesException is considered to be responsible for the transmission so that dispatching is *not* continued with the succeeding Section! The last Section which was responsible for a transmission's magic bytes will be the responsible Section till another Section claims responsibility for a transmsision's magic bytes. Initially the first Section passed to this instance is the responsible Section.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.mixin.ChildrenAccessor

org.refcodes.mixin.ChildrenAccessor.ChildrenBuilder<T extends Object,B extends org.refcodes.mixin.ChildrenAccessor.ChildrenBuilder<T,B>>, org.refcodes.mixin.ChildrenAccessor.ChildrenMutator<T extends Object>, org.refcodes.mixin.ChildrenAccessor.ChildrenProperty<T extends Object>

Nested classes/interfaces inherited from interface org.refcodes.mixin.LengthAccessor

org.refcodes.mixin.LengthAccessor.LengthBuilder<B extends org.refcodes.mixin.LengthAccessor.LengthBuilder<B>>, org.refcodes.mixin.LengthAccessor.LengthMutator, org.refcodes.mixin.LengthAccessor.LengthProperty

Nested classes/interfaces inherited from interface org.refcodes.serial.Section

Section.SectionMixin

Nested classes/interfaces inherited from interface org.refcodes.serial.Transmission

Transmission.TransmissionMixin

Field Summary

Fields inherited from class org.refcodes.serial.AbstractMagicBytesTransmissionDispatcher

_children, _readLimit, _responsibility, DEFAULT_READ_LIMIT

Constructor Summary

Constructors

Constructor	Description
MagicBytesSectionDispatcher()
MagicBytesSectionDispatcher(int aReadLimit, Section... aSections)
MagicBytesSectionDispatcher(Collection<Section> aSections)
MagicBytesSectionDispatcher(Collection<Section> aSections, int aReadLimit)
MagicBytesSectionDispatcher(Section... aSections)

Method Summary

Modifier and Type	Method	Description
void	fromTransmission(byte[] aChunk, int aLength)	(Re-)initializes this instance with the the given byte array data.
void	fromTransmission(byte[] aChunk, int aOffset, int aLength)	(Re-)initializes this instance with the the given byte array data.
void	fromTransmission(Sequence aSequence, int aLength)	(Re-)initializes this instance with the the given Sequence data.
void	fromTransmission(Sequence aSequence, int aOffset, int aLength)	(Re-)initializes this instance with the the given Sequence data.
void	receiveFrom(InputStream aInputStream, int aLength)	(Re-)initializes this instance by receiving the according Sequence from the given InputStream.
void	receiveFrom(InputStream aInputStream, int aLength, OutputStream aReturnStream)	(Re-)initializes this instance by receiving the according Sequence from the given InputStream.
void	receiveFrom(SerialTransceiver aSerialTransceiver, int aLength)	(Re-)initializes this instance by receiving the according Sequence from the given SerialTransceiver's InputStream.

Methods inherited from class org.refcodes.serial.AbstractMagicBytesTransmissionDispatcher

getChildren, getLength, getResponsibility, iterator, toSchema, toSimpleTypeMap, toTransmission, transmitTo, transmitTo, transmitTo

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.refcodes.mixin.ChildrenAccessor

getChildren

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Methods inherited from interface org.refcodes.serial.Transmission

getLength, toSchema, toSimpleTypeMap, toTransmission, transmitTo, transmitTo, transmitTo

Constructor Detail

MagicBytesSectionDispatcher

public MagicBytesSectionDispatcher()

MagicBytesSectionDispatcher

public MagicBytesSectionDispatcher(Collection<Section> aSections,
                                   int aReadLimit)

MagicBytesSectionDispatcher

public MagicBytesSectionDispatcher(Collection<Section> aSections)

MagicBytesSectionDispatcher

public MagicBytesSectionDispatcher(int aReadLimit,
                                   Section... aSections)

MagicBytesSectionDispatcher

public MagicBytesSectionDispatcher(Section... aSections)

Method Detail

fromTransmission

public void fromTransmission(byte[] aChunk,
                             int aLength)
                      throws TransmissionException

(Re-)initializes this instance with the the given byte array data.

Specified by:

fromTransmission in interface Section

Parameters:

aChunk - The byte array data from which to (re-)initialize this instance.

aLength - The length of data assigned by the byte array.

Throws:

TransmissionException - thrown in case a given Sequence cannot be processed.

fromTransmission

public void fromTransmission(Sequence aSequence,
                             int aLength)
                      throws TransmissionException

(Re-)initializes this instance with the the given Sequence data.

Specified by:

fromTransmission in interface Section

Parameters:

aSequence - The Sequence data from which to (re-)initialize this instance.

aLength - The length of data assigned by the Sequence.

Throws:

TransmissionException - thrown in case a given Sequence cannot be processed.

fromTransmission

public void fromTransmission(byte[] aChunk,
                             int aOffset,
                             int aLength)
                      throws TransmissionException

(Re-)initializes this instance with the the given byte array data.

Specified by:

fromTransmission in interface Section

Parameters:

aChunk - The byte array data from which to (re-)initialize this instance.

aOffset - The offset where to start processing the provided byte array.

aLength - The length of data assigned by the byte array.

Throws:

TransmissionException - thrown in case a given Sequence cannot be processed.

receiveFrom

public void receiveFrom(InputStream aInputStream,
                        int aLength)
                 throws IOException,
                        TransmissionException

(Re-)initializes this instance by receiving the according Sequence from the given InputStream. This is a convenience method in case there is no feedback OutputStream available (actually the Section.receiveFrom(InputStream, int, OutputStream ) method is invoked with null for the feedback OutputStream). Override Section.receiveFrom(InputStream, int, OutputStream) for your custom receiving functionality.

Specified by:

receiveFrom in interface Section

Parameters:

aInputStream - The InputStream from which to read the instance's (re-)initialization Sequence from.

aLength - The length of data assigned by the byte array.

Throws:

IOException - thrown in case reading data from the InputStream caused problems.

TransmissionException - thrown in case a given InputStream bytes cannot be processed.

receiveFrom

public void receiveFrom(SerialTransceiver aSerialTransceiver,
                        int aLength)
                 throws IOException,
                        TransmissionException

(Re-)initializes this instance by receiving the according Sequence from the given SerialTransceiver's InputStream. Implementations providing error correction methods use the provided SerialTransceiver's feedback OutputStream to do some sort of "stop-and-wait ARQ" or apply similar methods to ensure correctness of the received data. This is a convenience method (actually the Section.receiveFrom(InputStream, int, OutputStream ) method is invoked). Override Section.receiveFrom(InputStream, int, OutputStream) for your custom receiving functionality.

Specified by:

receiveFrom in interface Section

Parameters:

aSerialTransceiver - The SerialTransceiver providing the InputStream where to read this instance's Sequence from and providing the OutputStream being the feedback channel to handle "stop-and-wait ARQ".

aLength - The length of data assigned by the byte array.

Throws:

IOException - thrown in case reading data from the InputStream caused problems.

TransmissionException - thrown in case a given InputStream bytes cannot be processed.

fromTransmission

public void fromTransmission(Sequence aSequence,
                             int aOffset,
                             int aLength)
                      throws TransmissionException

(Re-)initializes this instance with the the given Sequence data.

Specified by:

fromTransmission in interface Section

Parameters:

aSequence - The Sequence data from which to (re-)initialize this instance.

aOffset - The offset where to start processing the provided Sequence.

aLength - The length of data assigned by the Sequence.

Throws:

TransmissionException - thrown in case a given Sequence cannot be processed.

receiveFrom

public void receiveFrom(InputStream aInputStream,
                        int aLength,
                        OutputStream aReturnStream)
                 throws IOException,
                        TransmissionException

(Re-)initializes this instance by receiving the according Sequence from the given InputStream. Implementations providing error correction methods use the provided feedback OutputStream to do some sort of "stop-and-wait ARQ" or apply similar methods to ensure correctness of the received data.

Specified by:

receiveFrom in interface Section

Parameters:

aInputStream - The InputStream from which to read the instance's (re-)initialization Sequence from.

aLength - The length of data assigned by the byte array.

aReturnStream - An OutputStream being the return channel to handle "stop-and-wait ARQ" or the like in case of a bidirectional connection. Can be null in case we have a unidirectional connection.

Throws:

IOException - thrown in case reading data from the InputStream caused problems.

TransmissionException - thrown in case a given InputStream bytes cannot be processed.