com.aquenos.epics.jackie.common.protocol

Class ChannelAccessErrorMessage

java.lang.Object

com.aquenos.epics.jackie.common.protocol.ChannelAccessMessage

com.aquenos.epics.jackie.common.protocol.ChannelAccessErrorMessage

public final class ChannelAccessErrorMessage
extends ChannelAccessMessage

Representation of a CA_PROTO_ERROR message. This message is sent from a server to a client to signal an error condition.

Author:

Sebastian Marsching

See Also:

ChannelAccessCommand.CA_PROTO_ERROR

Field Summary

Fields

Modifier and Type	Field and Description
static int	UNKNOWN_CHANNEL_CID Channel CID sent with an error message if the error is not associated with a specific channel.

Fields inherited from class com.aquenos.epics.jackie.common.protocol.ChannelAccessMessage

command, originalMessageHeader

Constructor Summary

Constructors

Constructor and Description
ChannelAccessErrorMessage(int channelCID, ChannelAccessStatus status, ChannelAccessMessage originalMessage, java.lang.String messageString) Constructor for creating a CA_PROTO_ERROR message.

Method Summary

Modifier and Type	Method and Description
protected static ChannelAccessErrorMessage	deserialize(ChannelAccessMessageHeader messageHeader, ByteSource byteSource, java.nio.charset.Charset charset, ChannelAccessVersion version, boolean isTCP) Constructs a message from a header and a byte source.
boolean	equals(java.lang.Object obj) Tells whether the specified object represents the same message.
int	getChannelCID() Returns the channel CID used by the client.
java.lang.String	getMessageString() Returns the string describing details about this error.
ChannelAccessMessage	getOriginalMessage() Returns the original message that is attached to this error message.
ChannelAccessStatus	getStatus() Returns the status associated with this error.
int	hashCode() Returns a hash code value for this message.
protected void	serialize(ByteSink byteSink, ChannelAccessVersion version, int maxPayloadSize, java.nio.charset.Charset charset) Serializes this message to a byte sink.
java.lang.String	toString() Returns a string representation of this message.
protected void	verify(ChannelAccessVersion version, int maxPayloadSize, java.nio.charset.Charset charset) Verifies that this message can be serialized.

Methods inherited from class com.aquenos.epics.jackie.common.protocol.ChannelAccessMessage

addByteArrayToStringBuilder, calculatePaddingSize, getCommand, getOriginalMessageHeader, hasOriginalMessageHeader, serializeHeader, verifyHeader

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN_CHANNEL_CID

public static final int UNKNOWN_CHANNEL_CID

Channel CID sent with an error message if the error is not associated with a specific channel.

See Also:

Constant Field Values

Constructor Detail

ChannelAccessErrorMessage

public ChannelAccessErrorMessage(int channelCID,
                                 ChannelAccessStatus status,
                                 ChannelAccessMessage originalMessage,
                                 java.lang.String messageString)

Constructor for creating a CA_PROTO_ERROR message.

Parameters:

channelCID - client-side channel identifier related to the error message. If the error is not related to a specific channel or the channel CID is unknown, the value should be set to -1.

status - Channel Access status code indicating the kind of error.

originalMessage - message that caused this error. This parameter may be null if no such message is available. However, if it is null the messageString must also be null.

messageString - textual error message. This parameter may be null if no such message is available. It must be null if originalMessage is null.

Throws:

java.lang.IllegalArgumentException - if originalMessage is null and messageString is not null and if originalMessage does not have original headers (has not been decoded but created through its public constructor).

Method Detail

getChannelCID

public int getChannelCID()

Returns the channel CID used by the client. This is the identifier that the client uses to identify the channel. This number might be negative or zero. If this error does not affect a specific channel or if the channel CID is not known by the server, the special value UNKNOWN_CHANNEL_CID is returned.

Returns:

channel CID assigned to the affected channel by the client or UNKNOWN_CHANNEL_CID if the channel CID is unknown.

getStatus

public ChannelAccessStatus getStatus()

Returns the status associated with this error. The status gives more information about the origin of the error. For an error message, the status should never be ECA_NORMAL.

Returns:

status code associated with this error (never null).

getOriginalMessage

public ChannelAccessMessage getOriginalMessage()

Returns the original message that is attached to this error message. This typically is the message sent by the client that caused the error. If no original message was attached to this error message, this method returns null.

Please note: The message returned is incomplete because the offending message's payload is never included in an error message. Therefore, some of the messages original information might not be available and calling methods that need this information might have unexpected results. In particular, the original message cannot be serialized again.

Returns:

original message that caused the error (reconstructed from the message's header) or null if no original message header has been attached to this error message.

getMessageString

public java.lang.String getMessageString()

Returns the string describing details about this error. If no such string has been attached to this message, null is returned.

Returns:

string describing this error or null.

serialize

protected void serialize(ByteSink byteSink,
                         ChannelAccessVersion version,
                         int maxPayloadSize,
                         java.nio.charset.Charset charset)

Description copied from class: ChannelAccessMessage

Serializes this message to a byte sink. This method is only intended to be used by ChannelAccessMessageCodec.

Specified by:

serialize in class ChannelAccessMessage

Parameters:

byteSink - byte sink that is used for writing the serialized data.

version - protocol version to stay compatible with. This is the protocol version of the peer the message is sent to.

maxPayloadSize - maximum size of the payload.

charset - encoding to use for serializing the string data (e.g. channel names, error strings, string data-values).

verify

protected void verify(ChannelAccessVersion version,
                      int maxPayloadSize,
                      java.nio.charset.Charset charset)

Description copied from class: ChannelAccessMessage

Verifies that this message can be serialized. This method is only intended to be used by ChannelAccessMessageCodec.

Overrides:

verify in class ChannelAccessMessage

Parameters:

version - protocol version to stay compatible with. This is the protocol version of the peer the message is sent to.

maxPayloadSize - maximum size of the payload.

charset - encoding to use for serializing the string data (e.g. channel names, error strings, string data-values).

equals

public boolean equals(java.lang.Object obj)

Description copied from class: ChannelAccessMessage

Tells whether the specified object represents the same message.

Two messages are considered equal if they are of the same type and have the same headers and payload. For comparing the types, the actual Java type and not just the Channel Access command is compared.

Overrides:

equals in class ChannelAccessMessage

Parameters:

obj - reference object with which this object is compared.

Returns:

true if obj is a message that is of the same type and has the same headers and payload as this message. false if obj is null or of a different type than this message or differs in the headers or payload.

hashCode

public int hashCode()

Description copied from class: ChannelAccessMessage

Returns a hash code value for this message. This method is supported for the benefit of hash tables. The hash code is calculated as a combination of the hash codes of this messages headers (including the Channel Access command) and its payload (if present).

If two messages are equal (as indicated by the return value of ChannelAccessMessage.equals(Object)), they also have the same hash code. However, the fact that two messages have the same hash code does not imply that they are equal.

Overrides:

hashCode in class ChannelAccessMessage

Returns:

hash code suitable for use by a hash table.

toString

public java.lang.String toString()

Description copied from class: ChannelAccessMessage

Returns a string representation of this message. The string representation contains the messages command, its header fields (if relevant for the command type) and its payload if present.

Overrides:

toString in class ChannelAccessMessage

Returns:

string representation of this message.

deserialize

protected static ChannelAccessErrorMessage deserialize(ChannelAccessMessageHeader messageHeader,
                                                       ByteSource byteSource,
                                                       java.nio.charset.Charset charset,
                                                       ChannelAccessVersion version,
                                                       boolean isTCP)

Constructs a message from a header and a byte source. This method is only intended for use by ChannelAccessMessageCodec.

Parameters:

messageHeader - CA message header.

byteSource - byte source for reading the message's payload (if any).

charset - encoding to use for deserializing the error message (if present).

version - protocol version in use. This can determine the meaning of some header fields.

isTCP - true if the message to be deserialized has been received over TCP, false if it has been received via UDP.

Returns:

message constructed from the data in the header and the payload read from the byte source.

Throws:

java.nio.BufferUnderflowException - if there is not enough data in the byte source to read the complete payload.