Module org.refcodes.serial

Package org.refcodes.serial

Interface Transmission

All Superinterfaces:

org.refcodes.mixin.LengthAccessor, Serializable

All Known Subinterfaces:

ArraySection<ARRAY>, ArraySegment<SEGMENT>, ArrayTransmission<ARRAY>, DecoratorSection<DECORATEE>, DecoratorSegment<DECORATEE>, DynamicTypeTransmission, ErrorCorrectionTransmission, PayloadSection<T>, PayloadSegment<T>, PayloadTransmission<T>, ReadyToReceiveTransmission, ReadyToSendTransmission, Section, Section.SectionMixin, Segment, Segment.SegmentMixin, StopAndWaitPacketStreamTransmission, StopAndWaitTransmission, Transmission.TransmissionMixin, TransmissionComposite<CHILD>

All Known Implementing Classes:

AbstractArrayTransmission, AbstractCipherTransmissionDecorator, AbstractCrcTransmissionDecorator, AbstractErrorCorrectionTransmissionDecorator, AbstractInvertibleTransmissionDecorator, AbstractLengthDecoratorSegment, AbstractMagicBytesTransmission, AbstractMagicBytesTransmissionDecorator, AbstractMagicBytesTransmissionMultiplexer, AbstractPayloadSection, AbstractPayloadSegment, AbstractReadyToReceiveTransmissionDecorator, AbstractReadyToSendTransmissionDecorator, AbstractReferenceeLengthSegment, AbstractSectionDecorator, AbstractSegmentDecorator, AbstractStopAndWaitPacketStreamTransmissionDecorator, AbstractStopAndWaitTransmissionDecorator, AbstractTransmissionComposite, AbstractTransmissionDecorator, AllocSectionDecoratorSegment, AllocSegmentBody, AllocSegmentHead, AsciizArraySegment, AsciizSegment, AssertMagicBytesSectionDecorator, AssertMagicBytesSegment, AssertMagicBytesSegmentDecorator, BooleanArraySection, BooleanSegment, BreakerSectionDecorator, BreakerSegmentDecorator, ByteArraySection, ByteSegment, CharArraySection, CharSection, CipherSectionDecorator, CipherSegmentDecorator, ComplexTypeSegment, CrcSectionDecorator, CrcSegmentDecorator, DoubleArraySection, DoubleSegment, DynamicTypeSection, DynamicTypeSegment, FileSection, FixedLengthSequenceSegment, FixedSegmentArraySection, FloatArraySection, FloatSegment, IntArraySection, IntSegment, InvertibleSectionDecorator, InvertibleSegmentDecorator, LengthSegment, LengthSegmentDecoratorSegment, LongArraySection, LongSegment, MagicBytesSectionDecorator, MagicBytesSectionMultiplexer, MagicBytesSegment, MagicBytesSegmentDecorator, MagicBytesSegmentMultiplexer, NullSegment, NumberSegment, PropertiesSection, ReadyToReceiveSectionDecorator, ReadyToReceiveSegmentDecorator, ReadyToSendSectionDecorator, ReadyToSendSegmentDecorator, SectionComposite, SegmentArraySection, SegmentComposite, SequenceNumberSegment, SequenceSection, ShortArraySection, ShortSegment, StopAndWaitPacketStreamSectionDecorator, StopAndWaitPacketStreamSegmentDecorator, StopAndWaitSectionDecorator, StopAndWaitSegmentDecorator, StringArraySection, StringSection, StringSegment

public interface Transmission
extends org.refcodes.mixin.LengthAccessor, Serializable

The Transmission interface enables an implementing type to provide a Sequence representation of itself or to transmit its Sequence representation through an OutputStream (with an optional feedback InputStream) as of transmitTo(OutputStream, InputStream). Usually, an implementation of the Transmission interface actually either implements the Segment interface or the Section interface which both share the Transmission super-interface. (this interface is Serializable in order to achieve a deep copy the easy way which is required by the ComplexTypeSegment and the FixedSegmentArraySection).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Transmission.TransmissionMixin	Default implementation of the Transmission interface providing an implementation of the Transmission.TransmissionMixin.transmitTo(OutputStream, InputStream) method using the toSequence() method.

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

Method Summary

Modifier and Type	Method	Description
static byte[]	fromInputStream(InputStream aInputStream, int aLength)	Retrieves the number of bytes from the given InputStream by also trying to read the required number of bytes in chunks (in case not all bytes can be read in one take).
int	getLength()	Determines the overall length of this Transmission.
Schema	toSchema()	Retrieves the Schema representing the Transmission.
Sequence	toSequence()	Provides the Sequence representation of this Transmission.
org.refcodes.struct.SimpleTypeMap	toSimpleTypeMap()	Returns the SimpleTypeMap representation of this Transmission.
default void	transmitTo(OutputStream aOutputStream)	Transmits the Sequence representing the implementing type's instance to the given OutputStream.
void	transmitTo(OutputStream aOutputStream, InputStream aReturnStream)	Transmits the Sequence representing the implementing type's instance to the given OutputStream.
default void	transmitTo(SerialTransceiver aSerialTransceiver)	Transmits the Sequence representing the implementing type's instance to the given SerialTransceiver's OutputStream.

Method Detail

getLength

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

Returns:

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

toSequence

Sequence toSequence()

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. Caution, the Transmission (or its nested Transmission instances) may be backed by the returned Sequence.

Returns:

The according instance's Sequence.

transmitTo

default void transmitTo(OutputStream aOutputStream)
                 throws IOException

Transmits the Sequence representing the implementing type's instance to the given OutputStream. This is a convenience method in case there is no feedback InputStream available (actually the transmitTo(OutputStream, InputStream) method is invoked with null for the feedback InputStream). Override transmitTo(OutputStream, InputStream) for your custom transmitting functionality.

Parameters:

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

Throws:

IOException - thrown in case writing data to the OutputStream caused problems.

transmitTo

default void transmitTo(SerialTransceiver aSerialTransceiver)
                 throws IOException

Transmits the Sequence representing the implementing type's instance to the given SerialTransceiver's OutputStream. Implementations providing error correction methods use the provided SerialTransceiver's feedback InputStream to do some sort of "stop-and-wait ARQ" or apply similar methods to ensure correctness of the transmitted data.This is a convenience method (actually the transmitTo(OutputStream, InputStream) method is invoked). Override transmitTo(OutputStream, InputStream) for your custom transmitting functionality.

Parameters:

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

Throws:

IOException - thrown in case writing data to the OutputStream caused problems.

transmitTo

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.

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

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.

Returns:

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

toSimpleTypeMap

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.

Returns:

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

fromInputStream

static byte[] fromInputStream(InputStream aInputStream,
                              int aLength)
                       throws IOException

Retrieves the number of bytes from the given InputStream by also trying to read the required number of bytes in chunks (in case not all bytes can be read in one take).

Parameters:

aInputStream - The byte array data from which to retrieve the bytes.

aLength - The number of bytes to be retrieved.

Returns:

An array containing the number of bytes.

Throws:

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