com.aquenos.epics.jackie.common.protocol

Class ChannelAccessMessageCodec

java.lang.Object

com.aquenos.epics.jackie.common.protocol.ChannelAccessMessageCodec

public class ChannelAccessMessageCodec
extends Object

Encoder and decoder for Channel Access messages.

Messages can be encoded (serialized) using one of the encode methods. They can be decoded (deserialized) using one of the decode methods. These methods are safe for concurrent use by multiple threads.

Problems that occur while encoding or decoding a message a signaled by exceptions. When an exception is encoutered while trying to decode a message, the corresponding message may be discarded from the byte source using the discardNextMessage(ByteSource) or discardNextMessageCompletely(ByteSource) method. In general, the discardNextMessage(ByteSource) method is preferrable because it will work, even if the message is too large to fit in the buffer backing the byte source. However, in contrast to the discardNextMessageCompletely(ByteSource) method, the calling code has to perform additional work in order to ensure that the message is really discarded completely.

The character set that is used for encoding and decoding strings in messages can be configured with the setCharset(Charset) method. However, changing the configuration is not thread safe, therefore the calling code must ensure that no other thread uses the message codec at the same time. By default, a newly created codec uses the UTF-8 encoding or, if this encoding is not available on the platform, the platform's default encoding.

The maximum allowed payload size can be configured separately for received messages (that are decoded) and sent messages (that are encoded) using the setMaxPayloadReceiveSize(int) and setMaxPayloadSendSize(int) methods. However, changing the configuration is not thread safe, therefore the calling code must ensure that no other thread uses the message codec at the same time. By default, a maximum payload size of 16384 bytes is used. This is also the smallest maximum payload size that can be configured. The Channel Access C library (as of EPICS 3.15.0) uses the same default setting. The upper limit for the maximum payload size is 2147483616 bytes. This limit comes from the fact that this library used 32-bit signed integers for dealing with message sizes. The Channel Access protocol uses 32-bit unsigned integers and thus would allow a greater limit, however no reasonable message sent via Channel Access should exceed limit of this implementation (which is roughly equivalent to a payload size of 2 GB) anyway.

While this class's encode and decode methods are thread-safe, the methods for changing the configuration are not thread-safe (not even with respect to the encode and decode methods). Therefore, a thread has to ensure that it has exclusive access to a message codec before changing its configuration. Typically, the configuration is only changed once after creating a message codec and never touched later.

Author:

Sebastian Marsching

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_MAX_PAYLOAD_SIZE Largest valid value for the maximum payload-size option.
static int	MIN_MAX_PAYLOAD_SIZE Smallest valid value for the maximum payload-size option.

Constructor Summary

Constructors

Constructor and Description
ChannelAccessMessageCodec() Creates a message codec that uses the UTF-8 character set or, if this character set is not available on the platform, the platform's default character set.

Method Summary

Methods

Modifier and Type	Method and Description
ChannelAccessMessage	decodeMessageFromRepeater(ByteSource byteSource, ChannelAccessVersion version) Decodes a message that has been sent from a repeater to a client via UDP.
ChannelAccessMessage	decodeMessageToRepeater(ByteSource byteSource, ChannelAccessVersion version, Inet4Address originAddress) Decodes a message that has been sent to a repeater via UDP (from a client or a server).
ChannelAccessMessage	decodeMessageToTCPClient(ByteSource byteSource, ChannelAccessVersion version, Inet4Address serverAddress, int serverPort) Decodes a message that has been sent from a server to a client via TCP.
ChannelAccessMessage	decodeMessageToTCPServer(ByteSource byteSource, ChannelAccessVersion version) Decodes a message that has been sent from a client to a server via TCP.
protected static ChannelAccessMessage	decodeMessageToTCPServer(ChannelAccessMessageHeader messageHeader, ByteSource byteSource, boolean headerOnly, Charset charset, int maxPayloadSize, ChannelAccessVersion version) Decodes a message that has been sent from a client to a server via TCP.
ChannelAccessMessage	decodeMessageToUDPClient(ByteSource byteSource, ChannelAccessVersion version, Inet4Address serverAddress, int serverPort) Decodes a message that has been sent to a client via UDP (most likely by a server).
ChannelAccessMessage	decodeMessageToUDPServer(ByteSource byteSource, ChannelAccessVersion version) Decodes a message that has been sent to a server via UDP (most likely by a client).
protected static ChannelAccessMessage	decodeMessageToUDPServer(ChannelAccessMessageHeader messageHeader, ByteSource byteSource, boolean headerOnly, Charset charset, int maxPayloadSize, ChannelAccessVersion version) Decodes a message that has been sent to a server via UDP (most likely by a client).
long	discardNextMessage(ByteSource byteSource) Discards the next message in the byte source.
void	discardNextMessageCompletely(ByteSource byteSource) Completely discards the next message in the byte source.
void	encodeMessageFromRepeater(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a repeater to a client via UDP.
void	encodeMessageToRepeater(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a server or a client to a repeater via UDP.
void	encodeMessageToTCPClient(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a server to a client via TCP Only messages of type ChannelAccessVersionTCPServerMessage, ChannelAccessSubscriptionServerMessage, ChannelAccessCancelSubscriptionServerMessage, ChannelAccessReadServerMessage, ChannelAccessReadSyncMessage , ChannelAccessErrorMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyServerMessage, ChannelAccessConnectChannelServerMessage, ChannelAccessWriteNotifyServerMessage, ChannelAccessAccessRightsMessage, ChannelAccessEchoMessage, ChannelAccessConnectChannelFailedMessage, ChannelAccessChannelDisconnectedByServerMessage, ChannelAccessSearchTCPServerMessage, and ChannelAccessNotFoundMessage can be sent via this protocol.
void	encodeMessageToTCPServer(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a client to a server via TCP Only messages of type ChannelAccessVersionTCPClientMessage, ChannelAccessSubscriptionClientMessage, ChannelAccessCancelSubscriptionClientMessage, ChannelAccessReadClientMessage, ChannelAccessWriteMessage , ChannelAccessEventsOffMessage, ChannelAccessEventsOnMessage, ChannelAccessReadSyncMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyClientMessage, ChannelAccessConnectChannelClientMessage, ChannelAccessWriteNotifyClientMessage, ChannelAccessUserNameMessage, ChannelAccessHostNameMessage, ChannelAccessEchoMessage, and ChannelAccessSearchClientMessage can be sent via this protocol.
void	encodeMessageToUDPClient(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a server to a client via UDP.
void	encodeMessageToUDPServer(ByteSink byteSink, ChannelAccessMessage message, ChannelAccessVersion version) Encodes a message that shall be sent from a client to a server via UDP.
Charset	getCharset() Returns the character set used by this message codec.
int	getMaxPayloadReceiveSize() Returns the maximum payload size for received messages.
int	getMaxPayloadSendSize() Returns the maximum payload size for sent messages.
void	setCharset(Charset charset) Sets the character set used by this message codec.
void	setMaxPayloadReceiveSize(int maxPayloadReceiveSize) Sets the maximum payload size for received messages.
void	setMaxPayloadSendSize(int maxPayloadSendSize) Sets the maximum payload size for sent messages.
void	verifyMessageFromRepeater(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a repeater to a client via UDP.
void	verifyMessageToRepeater(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a server or a client to a repeater via UDP.
void	verifyMessageToTCPClient(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a server to a client via TCP Only messages of type ChannelAccessVersionTCPServerMessage, ChannelAccessSubscriptionServerMessage, ChannelAccessCancelSubscriptionServerMessage, ChannelAccessReadServerMessage, ChannelAccessReadSyncMessage , ChannelAccessErrorMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyServerMessage, ChannelAccessConnectChannelServerMessage, ChannelAccessWriteNotifyServerMessage, ChannelAccessAccessRightsMessage, ChannelAccessEchoMessage, ChannelAccessConnectChannelFailedMessage, ChannelAccessChannelDisconnectedByServerMessage, ChannelAccessSearchTCPServerMessage, and ChannelAccessNotFoundMessage can be sent via this protocol.
void	verifyMessageToTCPServer(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a client to a server via TCP Only messages of type ChannelAccessVersionTCPClientMessage, ChannelAccessSubscriptionClientMessage, ChannelAccessCancelSubscriptionClientMessage, ChannelAccessReadClientMessage, ChannelAccessWriteMessage , ChannelAccessEventsOffMessage, ChannelAccessEventsOnMessage, ChannelAccessReadSyncMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyClientMessage, ChannelAccessConnectChannelClientMessage, ChannelAccessWriteNotifyClientMessage, ChannelAccessUserNameMessage, ChannelAccessHostNameMessage, ChannelAccessEchoMessage, and ChannelAccessSearchClientMessage can be sent via this protocol.
void	verifyMessageToUDPClient(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a server to a client via UDP.
void	verifyMessageToUDPServer(ChannelAccessMessage message, ChannelAccessVersion version) Verifies a message that shall be sent from a client to a server via UDP.

Methods inherited from class java.lang.Object

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

Field Detail

MIN_MAX_PAYLOAD_SIZE

public static final int MIN_MAX_PAYLOAD_SIZE

Smallest valid value for the maximum payload-size option.

See Also:

Constant Field Values

MAX_MAX_PAYLOAD_SIZE

public static final int MAX_MAX_PAYLOAD_SIZE

Largest valid value for the maximum payload-size option.

See Also:

Constant Field Values

Constructor Detail

ChannelAccessMessageCodec

public ChannelAccessMessageCodec()

Creates a message codec that uses the UTF-8 character set or, if this character set is not available on the platform, the platform's default character set. The maximum payload send and receive sizes are initialized to their smallest possible values (16384 bytes).

Method Detail

getMaxPayloadReceiveSize

public int getMaxPayloadReceiveSize()

Returns the maximum payload size for received messages. If a received message's payload exceeds this size, the deserialization routine will throw a ReceivedMessageTooLargeException. The default value is 16384.

Returns:

maximum payload size for received Channel Access messages (in bytes). This number is always a multiple of ChannelAccessConstants.MESSAGE_SIZE_ALIGNMENT.

setMaxPayloadReceiveSize

public void setMaxPayloadReceiveSize(int maxPayloadReceiveSize)

Sets the maximum payload size for received messages. If a received message's payload exceeds this size, the deserialization routine will throw a ReceivedMessageTooLargeException. The default value is 16384 which is also the smallest allowed value.

Caution: This method is not thread-safe. It should be called at initialization time, before the message codec is used. If the value is supposed to be changed later, it has to be ensured that no other thread is using this message codec concurrently.

Parameters:

maxPayloadReceiveSize - new maxium payload size for received Channel Access messages (in bytes). Must be at least 16384. Must not be greater than 2147483616. If this number is not a multiple of ChannelAccessConstants.MESSAGE_SIZE_ALIGNMENT, the next smaller number that is a multiple of MESSAGE_SIZE_ALIGNMENT is used.

Throws:

IllegalArgumentException - if maxPayloadReceiveSize is less than 16384 or greater than 2147483616.

getMaxPayloadSendSize

public int getMaxPayloadSendSize()

Returns the maximum payload size for sent messages. If a message's payload exceeds this size, the serialization routine will throw a SerializedPayloadTooLargeException. The default value is 16384.

Returns:

maximum payload size for sent Channel Access messages (in bytes). This number is always a multiple of ChannelAccessConstants.MESSAGE_SIZE_ALIGNMENT.

setMaxPayloadSendSize

public void setMaxPayloadSendSize(int maxPayloadSendSize)

Sets the maximum payload size for sent messages. If a message's payload exceeds this size, the serialization routine will throw a SerializedPayloadTooLargeException. The default value is 16384 which is also the smallest allowed value.

Caution: This method is not thread-safe. It should be called at initialization time, before the message codec is used. If the value is supposed to be changed later, it has to be ensured that no other thread is using this message codec concurrently.

Parameters:

maxPayloadSendSize - new maxium payload size for sent Channel Access messages (in bytes). Must be at least 16384. Must not be greater than 2147483616. If this number is not a multiple of ChannelAccessConstants.MESSAGE_SIZE_ALIGNMENT, the next smaller number that is a multiple of MESSAGE_SIZE_ALIGNMENT is used.

Throws:

IllegalArgumentException - if maxPayloadSendSize is less than 16384 or greater than 2147483616.

getCharset

public Charset getCharset()

Returns the character set used by this message codec. The character set determines how strings are converted to bytes and the other-way round. This affects the over-the-wire format of channel names, error strings and string values. The default is the UTF-8 charset. If this charset is not available, the default is the platform's default charset.

Returns:

character-set used for encoding and decoding strings.

setCharset

public void setCharset(Charset charset)

Sets the character set used by this message codec. The character set determines how strings are converted to bytes and the other-way round. This affects the over-the-wire format of channel names, error strings and string values. The default is the UTF-8 charset. If this charset is not available, the default is the platform's default charset.

Caution: This method is not thread-safe. It should be called at initialization time, before the message codec is used. If the value is supposed to be changed later, it has to be ensured that no other thread is using this message codec concurrently.

Parameters:

charset - new character-set to use for encoding and decoding strings.

encodeMessageToUDPServer

public void encodeMessageToUDPServer(ByteSink byteSink,
                            ChannelAccessMessage message,
                            ChannelAccessVersion version)

Encodes a message that shall be sent from a client to a server via UDP. Only messages of type ChannelAccessVersionUDPMessage and ChannelAccessSearchClientMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent from a client to a server via UDP.

SerializedChannelNameTooLargeException - if a channel name has to be serialized and the serialized form of the channel name is too long.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

encodeMessageToUDPClient

public void encodeMessageToUDPClient(ByteSink byteSink,
                            ChannelAccessMessage message,
                            ChannelAccessVersion version)

Encodes a message that shall be sent from a server to a client via UDP. Only messages of type ChannelAccessVersionUDPMessage and ChannelAccessSearchUDPServerMessage, ChannelAccessEchoMessage, ChannelAccessErrorMessage, and ChannelAccessNotFoundMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent from a server to a client via UDP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

encodeMessageToRepeater

public void encodeMessageToRepeater(ByteSink byteSink,
                           ChannelAccessMessage message,
                           ChannelAccessVersion version)

Encodes a message that shall be sent from a server or a client to a repeater via UDP. Only messages of type ChannelAccessBeaconMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent to a repeater.

encodeMessageFromRepeater

public void encodeMessageFromRepeater(ByteSink byteSink,
                             ChannelAccessMessage message,
                             ChannelAccessVersion version)

Encodes a message that shall be sent from a repeater to a client via UDP. Only messages of type ChannelAccessVersionUDPMessage, ChannelAccessRepeaterConfirmMessage, and ChannelAccessBeaconMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent from a repeater to a client via UDP.

encodeMessageToTCPServer

public void encodeMessageToTCPServer(ByteSink byteSink,
                            ChannelAccessMessage message,
                            ChannelAccessVersion version)

Encodes a message that shall be sent from a client to a server via TCP Only messages of type ChannelAccessVersionTCPClientMessage, ChannelAccessSubscriptionClientMessage, ChannelAccessCancelSubscriptionClientMessage, ChannelAccessReadClientMessage, ChannelAccessWriteMessage , ChannelAccessEventsOffMessage, ChannelAccessEventsOnMessage, ChannelAccessReadSyncMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyClientMessage, ChannelAccessConnectChannelClientMessage, ChannelAccessWriteNotifyClientMessage, ChannelAccessUserNameMessage, ChannelAccessHostNameMessage, ChannelAccessEchoMessage, and ChannelAccessSearchClientMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent from a client to a server via TCP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

encodeMessageToTCPClient

public void encodeMessageToTCPClient(ByteSink byteSink,
                            ChannelAccessMessage message,
                            ChannelAccessVersion version)

Encodes a message that shall be sent from a server to a client via TCP Only messages of type ChannelAccessVersionTCPServerMessage, ChannelAccessSubscriptionServerMessage, ChannelAccessCancelSubscriptionServerMessage, ChannelAccessReadServerMessage, ChannelAccessReadSyncMessage , ChannelAccessErrorMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyServerMessage, ChannelAccessConnectChannelServerMessage, ChannelAccessWriteNotifyServerMessage, ChannelAccessAccessRightsMessage, ChannelAccessEchoMessage, ChannelAccessConnectChannelFailedMessage, ChannelAccessChannelDisconnectedByServerMessage, ChannelAccessSearchTCPServerMessage, and ChannelAccessNotFoundMessage can be sent via this protocol.

Parameters:

byteSink - byte sink the encoded message is written to. The message is written in an atomic operation, so it is either written completely or nothing is written at all.

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

BufferOverflowException - if this exception is thrown by the byte sink and thus the message cannot be written completely.

IllegalArgumentException - if this message is of a type that cannot be sent from a server to a client via TCP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

discardNextMessage

public long discardNextMessage(ByteSource byteSource)

Discards the next message in the byte source. If the message is larger than the remaining bytes in the byte source, all bytes remaining in the byte source are discarded and the number of extra bytes is returned. The calling code should discard these extra bytes as soon as they are received.

Parameters:

byteSource - byte source from which the message headers are read and whose data is discarded.

Returns:

the number of bytes that could not be discarded because the byte source was empty. Those bytes should be discarded when they are received, so that the next bytes that are actually processed mark the start of the next message.

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the message headers. In this case no bytes are discarded at all and the byte source is left in the state it was in before calling this method.

discardNextMessageCompletely

public void discardNextMessageCompletely(ByteSource byteSource)

Completely discards the next message in the byte source. Unlike the discardNextMessage(ByteSource) method, this method will not discard any bytes if the number of bytes remaining in the byte source are less than the number of bytes that is expected according to the message headers.

Parameters:

byteSource - byte source from which the message headers are read and whose data is discarded.

Throws:

BufferUnderflowException - if the message headers cannot be read completely or there are not enough bytes remaining in the byte source for discarding the whole message.

decodeMessageToUDPServer

public ChannelAccessMessage decodeMessageToUDPServer(ByteSource byteSource,
                                            ChannelAccessVersion version)

Decodes a message that has been sent to a server via UDP (most likely by a client). The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole message.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToUDPServer

protected static ChannelAccessMessage decodeMessageToUDPServer(ChannelAccessMessageHeader messageHeader,
                                            ByteSource byteSource,
                                            boolean headerOnly,
                                            Charset charset,
                                            int maxPayloadSize,
                                            ChannelAccessVersion version)

Decodes a message that has been sent to a server via UDP (most likely by a client). This method might read partial data and thus leave the byte source in an undefined state. Therefore, it is only intended for internal use and should only be called within an atomic get transaction. This method will always read the payload specified in the message header, even if the message type expects a smaller payload or no payload at all.

Parameters:

messageHeader - headers of the message that is supposed to be decoded.

byteSource - byte source from which the message's payload is read (never null).

headerOnly - if true, only the message header is read. This option is useful when the message that was attached to an error message is reconstructed, because in this case only the header is available. If this option is set, no data is read from the byte source.

charset - character set that is used to decode strings in the message (never null).

maxPayloadSize - maximum size the message's payload may have. If the message's header specifies a payload size that exceeds this limit, a ReceivedMessageTooLargeException exception is thrown.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Returns:

message decoded from the message header and the payload read from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole payload.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than maxPayloadSize.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToUDPClient

public ChannelAccessMessage decodeMessageToUDPClient(ByteSource byteSource,
                                            ChannelAccessVersion version,
                                            Inet4Address serverAddress,
                                            int serverPort)

Decodes a message that has been sent to a client via UDP (most likely by a server). The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

serverAddress - IP address of the server that sent the message (never null).

serverPort - UDP port of the server that sent the message.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole message.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToTCPServer

public ChannelAccessMessage decodeMessageToTCPServer(ByteSource byteSource,
                                            ChannelAccessVersion version)

Decodes a message that has been sent from a client to a server via TCP. The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole message.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

ShortPayloadException - if the payload size specified in the message's header is too small considering the message type and the other parameters in the message's header.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToTCPServer

protected static ChannelAccessMessage decodeMessageToTCPServer(ChannelAccessMessageHeader messageHeader,
                                            ByteSource byteSource,
                                            boolean headerOnly,
                                            Charset charset,
                                            int maxPayloadSize,
                                            ChannelAccessVersion version)

Decodes a message that has been sent from a client to a server via TCP. This method might read partial data and thus leave the byte source in an undefined state. Therefore, it is only intended for internal use and should only be called within an atomic get transaction. This method will always read the payload specified in the message header, even if the message type expects a smaller payload or no payload at all.

Parameters:

messageHeader - headers of the message that is supposed to be decoded.

byteSource - byte source from which the message's payload is read (never null).

headerOnly - if true, only the message header is read. This option is useful when the message that was attached to an error message is reconstructed, because in this case only the header is available. If this option is set, no data is read from the byte source.

charset - character set that is used to decode strings in the message (never null).

maxPayloadSize - maximum size the message's payload may have. If the message's header specifies a payload size that exceeds this limit, a ReceivedMessageTooLargeException exception is thrown.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Returns:

message decoded from the message header and the payload read from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole payload.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than maxPayloadSize.

ShortPayloadException - if the payload size specified in the message's header is too small considering the message type and the other parameters in the message's header.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToTCPClient

public ChannelAccessMessage decodeMessageToTCPClient(ByteSource byteSource,
                                            ChannelAccessVersion version,
                                            Inet4Address serverAddress,
                                            int serverPort)

Decodes a message that has been sent from a server to a client via TCP. The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

serverAddress - IP address of the server that sent the message (never null).

serverPort - TCP port of the server that sent the message.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the whole message.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

ShortPayloadException - if the payload size specified in the message's header is too small considering the message type and the other parameters in the message's header.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageToRepeater

public ChannelAccessMessage decodeMessageToRepeater(ByteSource byteSource,
                                           ChannelAccessVersion version,
                                           Inet4Address originAddress)

Decodes a message that has been sent to a repeater via UDP (from a client or a server). The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

originAddress - IP address of the host that the message originated from.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the message header.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

decodeMessageFromRepeater

public ChannelAccessMessage decodeMessageFromRepeater(ByteSource byteSource,
                                             ChannelAccessVersion version)

Decodes a message that has been sent from a repeater to a client via UDP. The message is read from the specified byte source. This method either succeeds, returning the decoded message, or fails completely, leaving the byte source in its original state.

Parameters:

byteSource - byte source from which the message is read (never null). The message is read in an atomic operation, thus it is either read completely or no data is read at all, leaving the byte source in its original state.

version - protocol version that shall be used (never null). This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Returns:

message read and decoded from the byte source (never null).

Throws:

BufferUnderflowException - if the byte source does not contain enough data to read the message header.

MalformedMessageException - if the message's size is not well aligned.

ReceivedMessageTooLargeException - if the message's payload is larger than the configured maximum payload receive size.

UnsupportedMessageTypeException - if the message type specified in the header is not supported by this implementation (for example because it is only expected to be received over a different transport).

verifyMessageToUDPServer

public void verifyMessageToUDPServer(ChannelAccessMessage message,
                            ChannelAccessVersion version)

Verifies a message that shall be sent from a client to a server via UDP. Only messages of type ChannelAccessVersionUDPMessage and ChannelAccessSearchClientMessage can be sent via this protocol. This verification ensures that encodeMessageToUDPServer(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be verified.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent from a client to a server via UDP.

SerializedChannelNameTooLargeException - if a channel name has to be serialized and the serialized form of the channel name is too long.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

verifyMessageToUDPClient

public void verifyMessageToUDPClient(ChannelAccessMessage message,
                            ChannelAccessVersion version)

Verifies a message that shall be sent from a server to a client via UDP. Only messages of type ChannelAccessVersionUDPMessage and ChannelAccessSearchUDPServerMessage, ChannelAccessEchoMessage, ChannelAccessErrorMessage, and ChannelAccessNotFoundMessage can be sent via this protocol. This verification ensures that encodeMessageToUDPClient(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent from a server to a client via UDP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

verifyMessageToRepeater

public void verifyMessageToRepeater(ChannelAccessMessage message,
                           ChannelAccessVersion version)

Verifies a message that shall be sent from a server or a client to a repeater via UDP. Only messages of type ChannelAccessBeaconMessage can be sent via this protocol. This verification ensures that encodeMessageToRepeater(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent to a repeater.

verifyMessageFromRepeater

public void verifyMessageFromRepeater(ChannelAccessMessage message,
                             ChannelAccessVersion version)

Verifies a message that shall be sent from a repeater to a client via UDP. Only messages of type ChannelAccessVersionUDPMessage, ChannelAccessRepeaterConfirmMessage, and ChannelAccessBeaconMessage can be sent via this protocol. This verification ensures that encodeMessageFromRepeater(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent from a repeater to a client via UDP.

verifyMessageToTCPServer

public void verifyMessageToTCPServer(ChannelAccessMessage message,
                            ChannelAccessVersion version)

Verifies a message that shall be sent from a client to a server via TCP Only messages of type ChannelAccessVersionTCPClientMessage, ChannelAccessSubscriptionClientMessage, ChannelAccessCancelSubscriptionClientMessage, ChannelAccessReadClientMessage, ChannelAccessWriteMessage , ChannelAccessEventsOffMessage, ChannelAccessEventsOnMessage, ChannelAccessReadSyncMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyClientMessage, ChannelAccessConnectChannelClientMessage, ChannelAccessWriteNotifyClientMessage, ChannelAccessUserNameMessage, ChannelAccessHostNameMessage, ChannelAccessEchoMessage, and ChannelAccessSearchClientMessage can be sent via this protocol. This verification ensures that encodeMessageToTCPServer(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent from a client to a server via TCP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.

verifyMessageToTCPClient

public void verifyMessageToTCPClient(ChannelAccessMessage message,
                            ChannelAccessVersion version)

Verifies a message that shall be sent from a server to a client via TCP Only messages of type ChannelAccessVersionTCPServerMessage, ChannelAccessSubscriptionServerMessage, ChannelAccessCancelSubscriptionServerMessage, ChannelAccessReadServerMessage, ChannelAccessReadSyncMessage , ChannelAccessErrorMessage, ChannelAccessDisconnectChannelMessage, ChannelAccessReadNotifyServerMessage, ChannelAccessConnectChannelServerMessage, ChannelAccessWriteNotifyServerMessage, ChannelAccessAccessRightsMessage, ChannelAccessEchoMessage, ChannelAccessConnectChannelFailedMessage, ChannelAccessChannelDisconnectedByServerMessage, ChannelAccessSearchTCPServerMessage, and ChannelAccessNotFoundMessage can be sent via this protocol. This verification ensures that encodeMessageToTCPClient(ByteSink, ChannelAccessMessage, ChannelAccessVersion) does not throw an exception (except for a BufferOverflowException ).

Parameters:

message - message to be encoded.

version - protocol version that shall be used. This implementation only supports protocol versions equal to or greater than ChannelAccessVersion.V4_4.

Throws:

IllegalArgumentException - if this message is of a type that cannot be sent from a server to a client via TCP.

SerializedPayloadTooLargeException - if the message cannot be sent because the payload would be larger than the configured maximum payload send size or the specified protocol version is older than Channel Access version 4.9 and the payload would be larger than 65528 bytes or the count exceeds 65535 elements.

UnsupportedInThisVersionException - if this message is not support in the protocol version specified by version.

UnsupportedOperationException - if this message has been constructed by deserializing it from headers only and thus it is incomplete.

UnsupportedProtocolVersionException - if the specified version is older than the oldest supported protocol version for this message. In general, all Channel Access versions since version 4.4 should be supported.