public interface

TrapMessage

com.ericsson.research.trap.spi.TrapMessage
Known Indirect Subclasses

Class Overview

TrapMessage is a message that can be transported via Trap. This class defines the functionality of TrapMessages. A TrapMessage encapsulates the data to be sent in a structured format, and allows for easy serialization.

The messages have two representation formats: 8-bit and 7-bit. The 8-bit is the recommended format, while 7-bit is reserved for legacy use cases. The diagram below represents the 8-bit message format. 

       0               1               2               3
       0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
      +-+-+-----------+---------------+-------------------------------+
      |1|0| MESSAGEOP |C|  Reserved1  |             AUTHLEN           | ; R = Reserved, C = Compressed Flag, CHANID = Channel ID
 32   +-+-+-----------+---------------+-------------------------------+
      |                          Message ID                           |
 64   +---------------+---------------+-------------------------------+
      |   Reserved2   |   ChannelID   |           Reserved3           |
 96   +---------------+---------------+-------------------------------+
      |                        Content Length                         | ; Length of the payload that begins *after* AUTHLEN
 128  +---------------------------------------------------------------+
      |        ... Authentication Data (0...65535 bytes) ...          | ; MUST be US-ASCII (0x20 - 0x7F)
      +---------------------------------------------------------------+
      |                         Payload Data                          | ; Optional content, specified by Content Length
      + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + ; Payload begins at offset (in bytes) 12+AUTHLEN
      |                     Payload Data continued ...                |
      +---------------------------------------------------------------+

Summary

Nested Classes
class TrapMessage.Format The Format class specifies the available Trap message formats. 
class TrapMessage.Operation This subclass defines the possible message operations of a TrapMessage. 
Public Methods
abstract int deserialize(byte[] rawData, int offset, int length)
Attempts to deserialize a TrapMessage.
abstract String getAuthData()
Accessor for the authentication payload.
abstract int getChannel()
Retrieves the channel this message was sent/received on.
abstract byte[] getCompressedData()
Retrieves the compressed data, if compression is enabled.
abstract byte[] getData()
Gets the message's data payload, as set by the user.
abstract TrapMessage.Format getFormat()
Accessor for the message format.
abstract int getMessageId()
Fetches the message ID.
abstract TrapMessage.Operation getOp()
Fetches the message operation.
abstract boolean isCompressed()
Checks whether this message will be or was transmitted compressed.
abstract long length()
The length in bytes of this message, as it would appear when serialized using the current settings.
abstract byte[] serialize()
Serializes this TrapMessage into a byte array.
abstract TrapMessage setAuthData(String authData)
Sets the message's authentication string/header
abstract TrapMessage setChannel(int channelID)
Sets the channel this message should be transmitted on.
abstract TrapMessage setCompressed(boolean isCompressed)
Sets the compressed flag of this message.
abstract TrapMessage setData(byte[] data)
Sets the message's data (payload)
abstract TrapMessage setFormat(TrapMessage.Format format)
Sets a new message format.
abstract TrapMessage setMessageId(int newMessageId)
Sets the message id.
abstract TrapMessage setOp(TrapMessage.Operation op)
Sets the message operation.
abstract String toString()
Generates a human-readable string describing this message.

Public Methods

public abstract int deserialize (byte[] rawData, int offset, int length)

Attempts to deserialize a TrapMessage.

Parameters
rawData The data to read from
offset The start of the buffer, where to read from.
length The maximum number of bytes that can be read
Returns
  • -1 if it could not parse a message from the data, the number of bytes consumed otherwise.
Throws
UnsupportedEncodingException if the message encoding is not supported

public abstract String getAuthData ()

Accessor for the authentication payload.

Returns
  • The authentication payload, as a UTF string.

public abstract int getChannel ()

Retrieves the channel this message was sent/received on.

Returns
  • The channel ID, in the range [0,63].

public abstract byte[] getCompressedData ()

Retrieves the compressed data, if compression is enabled. Else returns the message data.

Returns
  • The message data, compressed if enabled.

public abstract byte[] getData ()

Gets the message's data payload, as set by the user. If data is not serialized at this point, will serialize it. If serialized, the resulting data is cached, so serialization occurs at most once.

Returns
  • The serialized payload.

public abstract TrapMessage.Format getFormat ()

Accessor for the message format.

Returns
  • The current message format.

public abstract int getMessageId ()

Fetches the message ID.

Returns
  • The current message id.

public abstract TrapMessage.Operation getOp ()

Fetches the message operation.

Returns
  • The current message operation.

public abstract boolean isCompressed ()

Checks whether this message will be or was transmitted compressed.

Returns
  • true if compression was enabled for this message, false otherwise.

public abstract long length ()

The length in bytes of this message, as it would appear when serialized using the current settings. There is no guarantee this will be the number of bytes sent on the wire, but it is an estimate (if nothing else changes).

This method performs an estimate computation, so may be off in case of compressible encodings.

Returns
  • The serialized length, in bytes

public abstract byte[] serialize ()

Serializes this TrapMessage into a byte array. This includes the headers and data. The format used is the one specified in the message settings. This operation is not cached.

Returns
  • A serialized representation of the message.
Throws
IOException If serialization fails.

public abstract TrapMessage setAuthData (String authData)

Sets the message's authentication string/header

Parameters
authData The string to set
Returns
  • The TrapMessage object. Useful for chaining multiple .setX calls.

public abstract TrapMessage setChannel (int channelID)

Sets the channel this message should be transmitted on. Trap supports channels with IDs 0-63, where 0 is the default channel. Each channel has a separate transmission queue, enabling multiplexing onto a single Trap logical connection.

Note that ID 0 is the control channel on which trap signalling goes. While it is possible to send a message on this channel, it is strongly discouraged. Sending application messages on channel ID 0 will be deprecated in the future.

Parameters
channelID The Channel ID to set. Allowed values are [0,63]. This setting should not be changed after the message is enqueued.
Returns
  • This TrapMessage instance, for chaining.
Throws
IllegalArgumentException If channelId is outside the permitted range of [0,63].

public abstract TrapMessage setCompressed (boolean isCompressed)

Sets the compressed flag of this message. If true, Trap will attempt to automatically compress (and decompress on the remote side)

Parameters
isCompressed true if Trap should compress this message, false otherwise.
Returns
  • An instance of this message, for chaining.

public abstract TrapMessage setData (byte[] data)

Sets the message's data (payload)

Parameters
data The data to set
Returns
  • The TrapMessage object. Useful for chaining multiple .setX calls.

public abstract TrapMessage setFormat (TrapMessage.Format format)

Sets a new message format.

Parameters
format The new format to use for serialzation.
Returns
  • The TrapMessage object. Useful for chaining multiple .setX calls.

public abstract TrapMessage setMessageId (int newMessageId)

Sets the message id. Messages must have a unique ID (except for certain transport messages). This method should only be called by Trap.

Parameters
newMessageId The new message ID.
Returns
  • keepaliveReceived

public abstract TrapMessage setOp (TrapMessage.Operation op)

Sets the message operation.

Parameters
op The new operation.
Returns
  • The TrapMessage object. Useful for chaining multiple .setX calls.

public abstract String toString ()

Generates a human-readable string describing this message. The string representation will contain the message operation, channel, id, and the data length (if present). For example: 

 OK/C0/0 - Plain OK message with no body, on the control channel.
 MESSAGE/C5/42/6 - Message with op MESSAGE, on channel 5, with ID 42, and 6 bytes payload.
It is not possible to use toString() to serialize the message. The serialize() method exists for that (but is not human readable).

Returns
  • A string with concise information about the message.