Module org.refcodes.serial

Package org.refcodes.serial

Class EnvelopeSegment

java.lang.Object

org.refcodes.serial.EnvelopeSegment

All Implemented Interfaces:

Serializable, org.refcodes.mixin.LengthAccessor, org.refcodes.mixin.MagicBytesAccessor, MagicBytesAccessor, Segment, SequenceNumberAccessor, Transmission, Transmission.TransmissionMixin

public class EnvelopeSegment
extends Object
implements Segment, Transmission.TransmissionMixin, SequenceNumberAccessor, MagicBytesAccessor

The EnvelopeSegment represents Segment transporting a cargo and providing a sequence number, CRC checksums as well as length declarations.

See Also:

Serialized Form

Nested Class Summary

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

MagicBytesAccessor.MagicBytesBuilder<B extends MagicBytesAccessor.MagicBytesBuilder<B>>, MagicBytesAccessor.MagicBytesMutator, MagicBytesAccessor.MagicBytesProperty

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

Segment.SegmentMixin

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

SequenceNumberAccessor.SequenceNumberBuilder<B extends SequenceNumberAccessor.SequenceNumberBuilder<B>>, SequenceNumberAccessor.SequenceNumberMutator, SequenceNumberAccessor.SequenceNumberProperty

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

Transmission.TransmissionMixin

Constructor Summary

Constructors

Constructor	Description
EnvelopeSegment()	Instantiates a new EnvelopeSegment with a plain Sequence as payload.
EnvelopeSegment(Section aCargoSection, int aSequenceNumber)	Instantiates a new EnvelopeSegment containing the given cargo Section.
EnvelopeSegment(Section aCargoSection, int aSequenceNumber, TransmissionMetrics aTransmissionMetrics)	Instantiates a new EnvelopeSegment containing the given cargo Section.
EnvelopeSegment(Segment aCargoSegment, int aSequenceNumber)	Instantiates a new EnvelopeSegment containing the given cargo Segment.
EnvelopeSegment(Segment aCargoSegment, int aSequenceNumber, TransmissionMetrics aTransmissionMetrics)	Instantiates a new EnvelopeSegment containing the given cargo Segment.
EnvelopeSegment(Sequence aCargoSequence, int aSequenceNumber)	Instantiates a new EnvelopeSegment containing the given cargo Sequence.
EnvelopeSegment(Sequence aCargoSequence, int aSequenceNumber, TransmissionMetrics aTransmissionMetrics)	Instantiates a new EnvelopeSegment containing the given cargo Sequence.
EnvelopeSegment(TransmissionMetrics aTransmissionMetrics)	Instantiates a new EnvelopeSegment with a plain Sequence as payload ready to receive an according cargo.
EnvelopeSegment(T aPayload, int aSequenceNumber)	Instantiates a new EnvelopeSegment with the provided cargo'spayload.
EnvelopeSegment(T aPayload, int aSequenceNumber, TransmissionMetrics aTransmissionMetrics)	Instantiates a new EnvelopeSegment with the provided payload.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
int	fromTransmission(Sequence aSequence, int aOffset)	(Re-)initializes this instance with the the given Sequence data.
int	getLength()	Determines the overall length of this Transmission.
byte[]	getMagicBytes()
int	getSequenceNumber()	Retrieves the sequence number from the sequence number property.
int	hashCode()
void	receiveFrom(InputStream aInputStream, OutputStream aReturnStream)	(Re-)initializes this instance by receiving the according Sequence from the given InputStream.
<SEGMENT extends Segment> SEGMENT	toCargoSegment(SEGMENT aMessageSegment)	Initializes the provided Segment from this EnvelopeSegment's explicitly carried Transmission.
<T> T	toPayload(Class<T> aType)	Decodes the cargo's payload to an instance of the given type.
<SEGMENT extends PayloadSegment<T>,T> T	toPayload(SEGMENT aMessageSegment)	Extracts the payload from this EnvelopeSegment's explicitly carried Transmission as of the provided preconfigured PayloadSegment.
Schema	toSchema()	Retrieves the Schema representing the Transmission.
org.refcodes.struct.SimpleTypeMap	toSimpleTypeMap()	Returns the SimpleTypeMap representation of this Transmission.
String	toString()
Sequence	toTransmission()	Provides the Sequence representation of this Transmission.
void	transmitTo(OutputStream aOutputStream, InputStream aReturnStream)	Transmits the Sequence representing the implementing type's instance to the given OutputStream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.refcodes.serial.Segment

fromTransmission, fromTransmission, fromTransmission, receiveFrom, receiveFrom

Methods inherited from interface org.refcodes.serial.Transmission

transmitTo, transmitTo

Constructor Detail

EnvelopeSegment

public EnvelopeSegment(T aPayload,
                       int aSequenceNumber)

Instantiates a new EnvelopeSegment with the provided cargo'spayload. It is up to the EnvelopeSegment how to encode and (decode as of toPayload(Class)) the provided cargo's payload!

Type Parameters:

T - The generic type of the payload to be carried by EnvelopeSegment.

Parameters:

aPayload - The payload to be carried by the EnvelopeSegment.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

EnvelopeSegment

public EnvelopeSegment(T aPayload,
                       int aSequenceNumber,
                       TransmissionMetrics aTransmissionMetrics)

Instantiates a new EnvelopeSegment with the provided payload. It is up to the EnvelopeSegment how to encode and (decode as of toPayload(Class) the provided payload!

Type Parameters:

T - The generic type of the payload to be carried by EnvelopeSegment.

Parameters:

aPayload - The payload to be carried by the EnvelopeSegment.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

aTransmissionMetrics - The TransmissionMetrics to use.

EnvelopeSegment

public EnvelopeSegment(Section aCargoSection,
                       int aSequenceNumber)

Instantiates a new EnvelopeSegment containing the given cargo Section.

Parameters:

aCargoSection - The cargo Section to be carried.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

EnvelopeSegment

public EnvelopeSegment(Section aCargoSection,
                       int aSequenceNumber,
                       TransmissionMetrics aTransmissionMetrics)

Instantiates a new EnvelopeSegment containing the given cargo Section.

Parameters:

aCargoSection - The cargo Section to be carried.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

aTransmissionMetrics - The TransmissionMetrics to use.

EnvelopeSegment

public EnvelopeSegment(Segment aCargoSegment,
                       int aSequenceNumber)

Instantiates a new EnvelopeSegment containing the given cargo Segment.

Parameters:

aCargoSegment - The cargo Segment to be carried.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

EnvelopeSegment

public EnvelopeSegment(Segment aCargoSegment,
                       int aSequenceNumber,
                       TransmissionMetrics aTransmissionMetrics)

Instantiates a new EnvelopeSegment containing the given cargo Segment.

Parameters:

aCargoSegment - The cargo Segment to be carried.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

aTransmissionMetrics - The TransmissionMetrics to use.

EnvelopeSegment

public EnvelopeSegment(Sequence aCargoSequence,
                       int aSequenceNumber)

Instantiates a new EnvelopeSegment containing the given cargo Sequence. The cargo Sequence is automatically labeled with the according cargo's length.

Parameters:

aCargoSequence - The payload a Sequence.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

EnvelopeSegment

public EnvelopeSegment(Sequence aCargoSequence,
                       int aSequenceNumber,
                       TransmissionMetrics aTransmissionMetrics)

Instantiates a new EnvelopeSegment containing the given cargo Sequence. The cargo Sequence is automatically labeled with the according cargo's length.

Parameters:

aCargoSequence - The cargo Sequence to be carried.

aSequenceNumber - The sequence number to be assigned to the EnvelopeSegment.

aTransmissionMetrics - The TransmissionMetrics to use.

EnvelopeSegment

public EnvelopeSegment()

Instantiates a new EnvelopeSegment with a plain Sequence as payload.

EnvelopeSegment

public EnvelopeSegment(TransmissionMetrics aTransmissionMetrics)

Instantiates a new EnvelopeSegment with a plain Sequence as payload ready to receive an according cargo.

Parameters:

aTransmissionMetrics - The TransmissionMetrics to use.

Method Detail

getLength

public int getLength()

Determines the overall length of this Transmission. In case of nested Transmission instances, all length values from all sub-segments are accumulated to the result as well.

Specified by:

getLength in interface org.refcodes.mixin.LengthAccessor

Specified by:

getLength in interface Transmission

Returns:

The (overall) length of the Transmission (including any sub-segments).

toTransmission

public Sequence toTransmission()

Provides the Sequence representation of this Transmission. In case of nested Transmission instances, all Sequence representations from all sub-segments are accumulated to the result as well.

Specified by:

toTransmission in interface Transmission

Returns:

The according instance's Sequence.

toString

public String toString()

Overrides:

toString in class Object

toSimpleTypeMap

public org.refcodes.struct.SimpleTypeMap toSimpleTypeMap()

Returns the SimpleTypeMap representation of this Transmission. In case this Transmission has Transmission children, then the children are queried as well and contained in the resulting SimpleTypeMap. The aliases of the according Transmission instances represent the resulting path to a Transmission's final simple type.

Specified by:

toSimpleTypeMap in interface Transmission

Returns:

The SimpleTypeMap representing this Transmission and (if any) its children, with the according aliases forming the paths to the Transmission's values.

transmitTo

public void transmitTo(OutputStream aOutputStream,
                       InputStream aReturnStream)
                throws IOException

Transmits the Sequence representing the implementing type's instance to the given OutputStream. Implementations providing error correction methods use the provided feedback InputStream to do some sort of "stop-and-wait ARQ" or apply similar methods to ensure correctness of the transmitted data.

Specified by:

transmitTo in interface Transmission

Specified by:

transmitTo in interface Transmission.TransmissionMixin

Parameters:

aOutputStream - The OutputStream where to write this instance's Sequence to.

aReturnStream - An InputStream 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 writing data to the OutputStream caused problems.

toSchema

public Schema toSchema()

Retrieves the Schema representing the Transmission. Retrieving a Schema is useful when analyzing and debugging data structures such as a AllocSectionDecoratorSegment instance to help document, learn and verify on the structure (as well as the content) of that very AllocSectionDecoratorSegment.

Specified by:

toSchema in interface Transmission

Returns:

The Schema representation of the implementing type for debugging and verification (or documentation) purposes.

fromTransmission

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

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

Specified by:

fromTransmission in interface Segment

Parameters:

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

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

Returns:

The index after the last offset into the given Sequence processed by this method.

Throws:

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

receiveFrom

public void receiveFrom(InputStream aInputStream,
                        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 Segment

Parameters:

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

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 transmission cannot be processed.

getSequenceNumber

public int getSequenceNumber()

Retrieves the sequence number from the sequence number property.

Specified by:

getSequenceNumber in interface SequenceNumberAccessor

Returns:

The sequence number stored by the sequence number property.

getMagicBytes

public byte[] getMagicBytes()

Specified by:

getMagicBytes in interface org.refcodes.mixin.MagicBytesAccessor

toCargoSegment

public <SEGMENT extends Segment> SEGMENT toCargoSegment(SEGMENT aMessageSegment)
                                                 throws TransmissionException

Initializes the provided Segment from this EnvelopeSegment's explicitly carried Transmission.

Type Parameters:

SEGMENT - The generic type of the Segment to be extracted.

Parameters:

aMessageSegment - The preconfigured Segment to be initialized from this EnvelopeSegment's explicitly carried Transmission.

Returns:

The provided Segment initialized with this EnvelopeSegment's explicitly carried Transmission.

Throws:

TransmissionException - thrown in case the Transmission cannot be processed by the provided Segment.

toPayload

public <SEGMENT extends PayloadSegment<T>,T> T toPayload(SEGMENT aMessageSegment)
                                                        throws TransmissionException

Extracts the payload from this EnvelopeSegment's explicitly carried Transmission as of the provided preconfigured PayloadSegment.

Type Parameters:

SEGMENT - The generic type of the PayloadSegment from which to extract the payload.

T - The generic type of the actual payload.

Parameters:

aMessageSegment - The preconfigured PayloadSegment to use for extracting the payload from this EnvelopeSegment

Returns:

The payload as of this EnvelopeSegment's encapsulated Transmission.

Throws:

TransmissionException - thrown in case the Transmission cannot be processed by the provided PayloadSegment.

toPayload

public <T> T toPayload(Class<T> aType)
                throws TransmissionException

Decodes the cargo's payload to an instance of the given type. The payload must be either be passed to one of the constructors EnvelopeSegment(Object, int) or EnvelopeSegment(Object, int, TransmissionMetrics) or be encoded by a ComplexTypeSegment constructed with the same TransmissionMetrics as this EnvelopeSegment instance (and passed to either the constructor EnvelopeSegment(Segment, int) or EnvelopeSegment(Segment, int, TransmissionMetrics)).

Type Parameters:

T - The generic type of the actual payload.

Parameters:

aType - The type of the payload for which to retrieve an instance created from the EnvelopeSegment instance's cargo.

Returns:

The according instance created from the EnvelopeSegment instance's cargo.

Throws:

TransmissionException - in case creating the given instance failed in case a given Transmission cannot be processed accordingly.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object