Module org.refcodes.serial

Package org.refcodes.serial

Class AsciizSegment

java.lang.Object

org.refcodes.serial.AbstractPayloadSegment<String>

org.refcodes.serial.AsciizSegment

All Implemented Interfaces:

Serializable, org.refcodes.mixin.AliasAccessor, org.refcodes.mixin.LengthAccessor, org.refcodes.mixin.PayloadAccessor<String>, org.refcodes.mixin.PayloadAccessor.PayloadBuilder<String,PayloadTransmission<String>>, org.refcodes.mixin.PayloadAccessor.PayloadMutator<String>, org.refcodes.mixin.PayloadAccessor.PayloadProperty<String>, org.refcodes.mixin.Schemable<SerialSchema>, EndOfStringByteAccessor, PayloadSegment<String>, PayloadTransmission<String>, Segment, Segment.SegmentMixin, Transmission, Transmission.TransmissionMixin

public class AsciizSegment
extends AbstractPayloadSegment<String>
implements PayloadSegment<String>, EndOfStringByteAccessor

The AsciizSegment is an implementation of a Segment carrying an ASCII encoded String as payload, terminated by a 0 ("zero") indicating its end. A 0 terminated is called ACIIZ or CString. Termination with 0 is done by the AsciizSegment and must not be handled by the programmer, though it is up to the developer to make sure no 0 value is contained within the provided String.

See Also:

• Serialized Form

Nested Class Summary

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

org.refcodes.mixin.AliasAccessor.AliasBuilder<B extends org.refcodes.mixin.AliasAccessor.AliasBuilder<B>>, org.refcodes.mixin.AliasAccessor.AliasMutator, org.refcodes.mixin.AliasAccessor.AliasProperty

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

EndOfStringByteAccessor.EndOfStringByteBuilder<B extends EndOfStringByteAccessor.EndOfStringByteBuilder<B>>, EndOfStringByteAccessor.EndOfStringByteMutator, EndOfStringByteAccessor.EndOfStringByteProperty

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.mixin.PayloadAccessor

org.refcodes.mixin.PayloadAccessor.PayloadBuilder<P extends Object,B extends org.refcodes.mixin.PayloadAccessor.PayloadBuilder<P,B>>, org.refcodes.mixin.PayloadAccessor.PayloadMutator<P extends Object>, org.refcodes.mixin.PayloadAccessor.PayloadProperty<P extends Object>

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

Segment.SegmentMixin

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

Transmission.TransmissionMixin

Field Summary

Fields inherited from class org.refcodes.serial.AbstractPayloadSegment

_alias, _payload

Constructor Summary

Constructors

Constructor	Description
AsciizSegment()	Constructs an empty AsciizSegment.
AsciizSegment(byte aEndOfStringByte)	Constructs an empty AsciizSegment.
AsciizSegment(byte[] aValue)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(byte[] aValue, byte aEndOfStringByte)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(String aValue)	Constructs an AsciizSegment with the given String payload.
AsciizSegment(String aValue, byte aEndOfStringByte)	Constructs an AsciizSegment with the given String payload.
AsciizSegment(String aAlias, byte[] aValue)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(String aAlias, byte[] aValue, byte aEndOfStringByte)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(String aAlias, String aValue)	Constructs an AsciizSegment with the given String payload.
AsciizSegment(String aAlias, String aValue, byte aEndOfStringByte)	Constructs an AsciizSegment with the given String payload.
AsciizSegment(String aAlias, TransmissionMetrics aTransmissionMetrics, byte[] aValue)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(String aAlias, TransmissionMetrics aTransmissionMetrics, String aValue)	Constructs an AsciizSegment with the given String payload.
AsciizSegment(TransmissionMetrics aTransmissionMetrics)	Constructs an empty AsciizSegment.
AsciizSegment(TransmissionMetrics aTransmissionMetrics, byte[] aValue)	Constructs an AsciizSegment with the given (ASCII encoded) bytes payload.
AsciizSegment(TransmissionMetrics aTransmissionMetrics, String aValue)	Constructs an AsciizSegment with the given String payload.

Method Summary

Modifier and Type	Method	Description
int	fromTransmission(Sequence aSequence, int aOffset)	(Re-)initializes this instance with the the given Sequence data.
byte	getEndOfStringByte()	Retrieves the end of string byte from the end of string byte property.
int	getLength()	Determines the overall length of this Transmission.
void	receiveFrom(InputStream aInputStream, OutputStream aReturnStream)	(Re-)initializes this instance by receiving the according Sequence from the given InputStream.
void	setPayload(byte[] aValue)	Sets the given (ASCII encoded) bytes payload.
SerialSchema	toSchema()	Retrieves the SerialSchema representing the Transmission.
Sequence	toSequence()	Provides the Sequence representation of this Transmission.
AsciizSegment	withPayload(byte[] aValue)	Sets the given (ASCII encoded) bytes payload.
AsciizSegment	withPayload(String aValue)

Methods inherited from class org.refcodes.serial.AbstractPayloadSegment

equals, getAlias, getPayload, hashCode, setPayload, toSimpleTypeMap, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.refcodes.mixin.AliasAccessor

getAlias

Methods inherited from interface org.refcodes.mixin.PayloadAccessor

getPayload, getPayloadOr

Methods inherited from interface org.refcodes.mixin.PayloadAccessor.PayloadMutator

setPayload

Methods inherited from interface org.refcodes.mixin.PayloadAccessor.PayloadProperty

letPayload

Methods inherited from interface org.refcodes.serial.Segment

fromTransmission, fromTransmission, fromTransmission, receiveFrom, receiveFrom

Methods inherited from interface org.refcodes.serial.Transmission

toSimpleTypeMap, transmitTo, transmitTo

Methods inherited from interface org.refcodes.serial.Transmission.TransmissionMixin

transmitTo

Constructor Details

AsciizSegment

public AsciizSegment()

Constructs an empty AsciizSegment. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString).

AsciizSegment

public AsciizSegment(TransmissionMetrics aTransmissionMetrics)

Constructs an empty AsciizSegment. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString).

Parameters:

aTransmissionMetrics - The TransmissionMetrics to be used for configuring this instance.

AsciizSegment

public AsciizSegment(TransmissionMetrics aTransmissionMetrics,
 String aValue)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aTransmissionMetrics - The TransmissionMetrics to be used for configuring this instance.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(TransmissionMetrics aTransmissionMetrics,
 byte[] aValue)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aTransmissionMetrics - The TransmissionMetrics to be used for configuring this instance.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(String aAlias,
 TransmissionMetrics aTransmissionMetrics,
 byte[] aValue)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aTransmissionMetrics - The TransmissionMetrics to be used for configuring this instance.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(String aAlias,
 TransmissionMetrics aTransmissionMetrics,
 String aValue)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aTransmissionMetrics - The TransmissionMetrics to be used for configuring this instance.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(String aValue)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(byte[] aValue)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(String aAlias,
 byte[] aValue)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(String aAlias,
 String aValue)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aValue - The payload to be contained by this AsciizSegment.

AsciizSegment

public AsciizSegment(byte aEndOfStringByte)

Constructs an empty AsciizSegment. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString).

Parameters:

aEndOfStringByte - The alternate value instead of 0 "zero" identifying the end of the string.

AsciizSegment

public AsciizSegment(String aValue,
 byte aEndOfStringByte)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aValue - The payload to be contained by this AsciizSegment.

aEndOfStringByte - The alternate value instead of 0 "zero" identifying the end of the string.

AsciizSegment

public AsciizSegment(byte[] aValue,
 byte aEndOfStringByte)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aValue - The payload to be contained by this AsciizSegment.

aEndOfStringByte - The alternate value instead of 0 "zero" identifying the end of the string.

AsciizSegment

public AsciizSegment(String aAlias,
 byte[] aValue,
 byte aEndOfStringByte)

Constructs an AsciizSegment with the given (ASCII encoded) bytes payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the bytes do not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aValue - The payload to be contained by this AsciizSegment.

aEndOfStringByte - The alternate value instead of 0 "zero" identifying the end of the string.

AsciizSegment

public AsciizSegment(String aAlias,
 String aValue,
 byte aEndOfStringByte)

Constructs an AsciizSegment with the given String payload. The serialized content (as of toSequence() or Transmission.transmitTo(java.io.OutputStream)) of an AsciizSegment represents an an ASCIIZ String (also known as CString). It is in the responsibility of the programmer to make sure that the String does not contain any 0 ("zero") values as a value of 0 unintendedly terminates the resulting String.

Parameters:

aAlias - The alias which identifies the content of this segment.

aValue - The payload to be contained by this AsciizSegment.

aEndOfStringByte - The alternate value instead of 0 "zero" identifying the end of the string.

Method Details

toSequence

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

Specified by:

toSequence in interface Transmission

Returns:

The according instance's Sequence.

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

Specified by:

receiveFrom in interface Segment.SegmentMixin

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.

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

toSchema

public SerialSchema toSchema()

Retrieves the SerialSchema representing the Transmission. Retrieving a SerialSchema 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 org.refcodes.mixin.Schemable<SerialSchema>

Specified by:

toSchema in interface Transmission

Returns:

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

withPayload

public AsciizSegment withPayload(String aValue)

Specified by:

withPayload in interface org.refcodes.mixin.PayloadAccessor.PayloadBuilder<String,PayloadTransmission<String>>

setPayload

public void setPayload(byte[] aValue)

Sets the given (ASCII encoded) bytes payload.

Parameters:

aValue - The payload to set.

withPayload

public AsciizSegment withPayload(byte[] aValue)

Sets the given (ASCII encoded) bytes payload.

Parameters:

aValue - The payload to set.

Returns:

THis instance as of the builder pattern.

getEndOfStringByte

public byte getEndOfStringByte()

Retrieves the end of string byte from the end of string byte property.

Specified by:

getEndOfStringByte in interface EndOfStringByteAccessor

Returns:

The end of string byte stored by the end of string byte property.