public final class ChannelAccessValueCodec extends Object
Encoder and decoder for ChannelAccessValue
s.
Values can be encoded (serialized) using one of the encode
methods. They can be decoded (deserialized) using one of the
decode
methods.
The calculatePayloadSize(ChannelAccessValueType, int)
method can be
used to determine the space the serialized form of a value will need in a
Channel Access message. The
calculateMaxCount(ChannelAccessValueType, int)
method can be used to
determine the maximum number of elements that will fit into a message of a
limited size.
Encoding and decoding is not completely symmetrical: Decoding and then encoding a binary representation of a value should result in the same binary representation. However, encoding and then decoding a value might result in a different value because due to limitations of the Channel Access protocol some information (in particular long strings) cannot be transported.
Modifier and Type | Method and Description |
---|---|
static int |
calculateMaxCount(ChannelAccessValueType type,
int maxDataSize)
Calculates the maximum number of elements a value of the specified type
can have, if it has to fit in the specified space.
|
static int |
calculatePayloadSize(ChannelAccessValueType type,
int count)
Calculates the serialized size of a value of the specified type having
the specified number of elements.
|
static ChannelAccessGettableValue<?> |
decodeGettableValue(ByteSource byteSource,
ChannelAccessValueType type,
int dataSize,
int count,
Charset charset)
Decodes a gettable ChannelAccess value from its serialized form.
|
static ChannelAccessPuttableValue<?> |
decodePuttableValue(ByteSource byteSource,
ChannelAccessValueType type,
int dataSize,
int count,
Charset charset)
Decodes a puttable ChannelAccess value from its serialized form.
|
static ChannelAccessValue<?> |
decodeValue(ByteSource byteSource,
ChannelAccessValueType type,
int dataSize,
int count,
Charset charset)
Decodes a ChannelAccess value from its serialized form.
|
static void |
encodeGettableValue(ByteSink byteSink,
ChannelAccessGettableValue<?> value,
int count)
Encodes a gettable ChannelAccess value into its serialized form.
|
static void |
encodePuttableValue(ByteSink byteSink,
ChannelAccessPuttableValue<?> value,
int count)
Encodes a puttable ChannelAccess value into its serialized form.
|
static void |
encodeValue(ByteSink byteSink,
ChannelAccessValue<?> value,
int count)
Encodes a ChannelAccess value into its serialized form.
|
public static ChannelAccessGettableValue<?> decodeGettableValue(ByteSource byteSource, ChannelAccessValueType type, int dataSize, int count, Charset charset)
byteSource
- byte source for reading the value's date.type
- type of the value (never null
).dataSize
- size of the available data (in bytes). If this is greater than
the amount of data needed for a value of the specified type
with the specified number of elements, the extra data is read
and discarded. If this is less than the data needed for a
value of the specified type with the specified number of
elements, an IllegalArgumentException
is thrown.count
- number of elements in the value. Must not be negative.charset
- character-set to use for decoding strings (never
null
).type
, created by reading
dataSize
bytes from byteSource
.BufferUnderflowException
- if the byteSource provides less than dataSize
bytes of data and thus throws a
BufferUnderflowException
.IllegalArgumentException
- if count
is negative, if dataSize
is too small for the specified type and number of elements,
and if type
is not a gettable type.public static ChannelAccessPuttableValue<?> decodePuttableValue(ByteSource byteSource, ChannelAccessValueType type, int dataSize, int count, Charset charset)
byteSource
- byte source for reading the value's date.type
- type of the value (never null
).dataSize
- size of the available data (in bytes). If this is greater than
the amount of data needed for a value of the specified type
with the specified number of elements, the extra data is read
and discarded. If this is less than the data needed for a
value of the specified type with the specified number of
elements, an IllegalArgumentException
is thrown.count
- number of elements in the value. Must not be negative.charset
- character-set to use for decoding strings (never
null
).type
, created by reading
dataSize
bytes from byteSource
.BufferUnderflowException
- if the byteSource provides less than dataSize
bytes of data and thus throws a
BufferUnderflowException
.IllegalArgumentException
- if count
is negative, if dataSize
is too small for the specified type and number of elements,
and if type
is not a puttable type.public static ChannelAccessValue<?> decodeValue(ByteSource byteSource, ChannelAccessValueType type, int dataSize, int count, Charset charset)
byteSource
- byte source for reading the value's date.type
- type of the value (never null
).dataSize
- size of the available data (in bytes). If this is greater than
the amount of data needed for a value of the specified type
with the specified number of elements, the extra data is read
and discarded. If this is less than the data needed for a
value of the specified type with the specified number of
elements, an IllegalArgumentException
is thrown.count
- number of elements in the value. Must not be negative.charset
- character-set to use for decoding strings (never
null
).type
, created by reading
dataSize
bytes from byteSource
.BufferUnderflowException
- if the byteSource provides less than dataSize
bytes of data and thus throws a
BufferUnderflowException
.IllegalArgumentException
- if count
is negative and if
dataSize
is too small for the specified type and
number of elements.public static void encodeGettableValue(ByteSink byteSink, ChannelAccessGettableValue<?> value, int count)
Encodes a gettable ChannelAccess value into its serialized form. Gettable
values are values that can be used in get operations (sending data from a
server to a client). If strings have to be serialized, the value's
encoding as specified by the return value of its
getCharset()
method is used.
The specified value must have been created by
ChannelAccessValueCodec
or ChannelAccessValueFactory
,
because this method expects a certain implementation. If the
implementation is not the expected one, a ClassCastException
is
thrown.
The serialization is limited to the specified number elements, even if
the value contains more elements. Therefore, the number of bytes written
is always equal to the number returned by
calculatePayloadSize(ChannelAccessValueType, int)
.
This method throws an BufferOverflowException
if there is not
enough space left in the byte sink to write the complete value. If this
method throws an exception, the byte sink will remain in a state as if no
data had been written.
This method simply delegates to
encodeValue(ByteSink, ChannelAccessValue, int)
and is mainly
provided for symmetry with
decodeGettableValue(ByteSource, ChannelAccessValueType, int, int, Charset)
.
byteSink
- byte sink the value's data is written to (never
null
).value
- value that should be serialized to the byte sink (never
null
).count
- number of elements that should be serialized. This number must
not be negative and must be less than or equal to the number
of elements that the value has.BufferOverflowException
- if the value cannot be written to the byte source completely,
because it throws a BufferOverflowException
.ClassCastException
- if the specified value
has not been created by
ChannelAccessValueCodec
or
ChannelAccessValueFactory
and thus is an
implementation unknown to this class.IllegalArgumentException
- if count is negative or greater than the number of elements
in the value.public static void encodePuttableValue(ByteSink byteSink, ChannelAccessPuttableValue<?> value, int count)
Encodes a puttable ChannelAccess value into its serialized form. Puttable
values are values that can be used in put operations (sending data from a
client to a server). If strings have to be serialized, the value's
encoding as specified by the return value of its
getCharset()
method is used.
The specified value must have been created by
ChannelAccessValueCodec
or ChannelAccessValueFactory
,
because this method expects a certain implementation. If the
implementation is not the expected one, a ClassCastException
is
thrown.
The serialization is limited to the specified number elements, even if
the value contains more elements. Therefore, the number of bytes written
is always equal to the number returned by
calculatePayloadSize(ChannelAccessValueType, int)
.
This method throws an BufferOverflowException
if there is not
enough space left in the byte sink to write the complete value. If this
method throws an exception, the byte sink will remain in a state as if no
data had been written.
This method simply delegates to
encodeValue(ByteSink, ChannelAccessValue, int)
and is mainly
provided for symmetry with
decodePuttableValue(ByteSource, ChannelAccessValueType, int, int, Charset)
.
byteSink
- byte sink the value's data is written to (never
null
).value
- value that should be serialized to the byte sink (never
null
).count
- number of elements that should be serialized. This number must
not be negative and must be less than or equal to the number
of elements that the value has.BufferOverflowException
- if the value cannot be written to the byte source completely,
because it throws a BufferOverflowException
.ClassCastException
- if the specified value
has not been created by
ChannelAccessValueCodec
or
ChannelAccessValueFactory
and thus is an
implementation unknown to this class.IllegalArgumentException
- if count is negative or greater than the number of elements
in the value.public static void encodeValue(ByteSink byteSink, ChannelAccessValue<?> value, int count)
Encodes a ChannelAccess value into its serialized form. If strings have
to be serialized, the value's encoding as specified by the return value
of its getCharset()
method is used.
The specified value must have been created by
ChannelAccessValueCodec
or ChannelAccessValueFactory
,
because this method expects a certain implementation. If the
implementation is not the expected one, a ClassCastException
is
thrown.
The serialization is limited to the specified number elements, even if
the value contains more elements. Therefore, the number of bytes written
is always equal to the number returned by
calculatePayloadSize(ChannelAccessValueType, int)
.
This method throws an BufferOverflowException
if there is not
enough space left in the byte sink to write the complete value. If this
method throws an exception, the byte sink will remain in a state as if no
data had been written.
byteSink
- byte sink the value's data is written to (never
null
).value
- value that should be serialized to the byte sink (never
null
).count
- number of elements that should be serialized. This number must
not be negative and must be less than or equal to the number
of elements that the value has.BufferOverflowException
- if the value cannot be written to the byte source completely,
because it throws a BufferOverflowException
.ClassCastException
- if the specified value
has not been created by
ChannelAccessValueCodec
or
ChannelAccessValueFactory
and thus is an
implementation unknown to this class.IllegalArgumentException
- if count is negative or greater than the number of elements
in the value.public static int calculatePayloadSize(ChannelAccessValueType type, int count)
type
- value type to calculate size for (never null
).count
- number of elements in the value. Must not be negative.IllegalArgumentException
- if count
is negative or the return value would
exceed Integer.MAX_VALUE
.public static int calculateMaxCount(ChannelAccessValueType type, int maxDataSize)
type
- ChannelAccess value type to check.maxDataSize
- size of the space (in bytes) in which the serialized value has
to fit.0
if the specified type cannot fit into the
specified space.Copyright © 2014–2017 aquenos GmbH. All rights reserved.