Package com.softwareag.connectivity

Class Message

java.lang.Object
com.softwareag.connectivity.Message
All Implemented Interfaces:
Cloneable
public final class Message extends Object implements Cloneable
A container for a payload and metadata.

A message may have a null payload; many plug-ins will silently pass through messages with null payloads, but plug-ins may treat them as special messages depending on the metadata.

Metadata is information that would not be thought of as part of the message payload, but data about the message. This may correspond to headers for a transport, or information deciding how to route the message. If required, the host's type will be specified in the metadata.

Messages passed between codec and transport plug-ins are not copied and Messages are mutable: plug-ins should send copies of Messages if they need to keep pristine copies of messages for future use, as other plug-ins may modify a Message.

This class is not thread-safe, so users are required to ensure that each instance of Message is only accessed by the codec or transport plug-in that currently owns it, and that only one thread from each plug-in is accessing it at any one time.

  • Field Details

    • CHANNEL

      public static final String CHANNEL
      The metadata key for the channel name. The channel is the primary value used to route the message; its meaning is host-dependent.
      See Also:

    • HOST_MESSAGE_TYPE

      public static final String HOST_MESSAGE_TYPE
      The metadata key for the type of message; its meaning is host-specific.
      See Also:

    • CONTROL_TYPE

      public static final String CONTROL_TYPE

      The metadata key indicating that a message is a control message, and what its type is. The metadata value names the control message, with different types of control message defined in the CONTROL_TYPE_* constants.

      Control messages must have a null payload.

      See Also:

    • MESSAGE_ID

      public static final String MESSAGE_ID

      The metadata key used for unique identification of towards-host messages. This is not mandatory, and only has to be populated for messages that you would like to see reliably acknowledged.

      The identifier can be an arbitrary value of String type, and must uniquely identify a message within the scope of the chain and the lifetime of the system. That is, possibly across host reboots and reconnections. Where applicable you should use an id provided by the external messaging system. This will help traceability of messages.

      See Also:

    • REQUEST_ID

      public static final String REQUEST_ID
      The metadata key used for unique identification of towards-transport control messages, with a value of type Long. Used to correlate Flush and FlushAck control messages.
      See Also:

    • CONTROL_TYPE_FLUSH

      public static final String CONTROL_TYPE_FLUSH
      Name of the Flush control message, a towards-transport control message. It is a request for the transport to acknowledge that all previous towards-transport non-control messages have been fully and reliably processed. Metadata of this control message will also contain a unique REQUEST_ID.
      See Also:

    • CONTROL_TYPE_FLUSH_ACK

      public static final String CONTROL_TYPE_FLUSH_ACK
      Name of the FlushAck control message, a towards-host control message in response to Flush, containing the corresponding REQUEST_ID. FlushAck messages implicitly cover all preceding Flush messages. That is, it is safe to miss a Flush if you have a later Flush in hand that succeeds it.
      See Also:

    • CONTROL_TYPE_ACK_REQUIRED

      public static final String CONTROL_TYPE_ACK_REQUIRED
      Name of the AckRequired control message, a towards-host control message. It is a request for the host to acknowledge that all previous towards-host non-control messages have been fully and reliably processed. Metadata of this control message should also contain the MESSAGE_ID of the immediately preceding non-control message.
      See Also:

    • CONTROL_TYPE_ACK_UPTO

      public static final String CONTROL_TYPE_ACK_UPTO
      Name of the AckUpTo control message, a towards-transport control message in response to AckRequired, containing the corresponding MESSAGE_ID. AckUpTo messages will be seen in the exact order that their corresponding AckRequired messages were sent, with none missing or duplicated.
      See Also:

  • Constructor Details

    • Message

      public Message(Object payload, Map<String,?> metadata)
      Create a message with the given payload and metadata

    • Message

      public Message(Object payload)
      Create a message with the given payload. The metadata will be an empty dictionary

  • Method Details

    • getPayload

      public Object getPayload()
      Get the payload object. The payload object represents the payload of the message. The type may be one of:
      • String
      • Boolean
      • Long
      • Short
      • Integer
      • Float
      • Double
      • BigDecimal
      • byte[]
      • Map<Object,Object> (where keys and values are typically one of these types
      • List< Object> (where the values are typically one of these types)
      • can be a user-defined type if plug-ins agree upon it.

      The contents of the payload may be mutated (for example if it is a map) by subsequent codecs - if a sender requires a pristine copy, it will need to take a copy before sending the message.

      The contents of the payload should not contain cycles - that is, a Map cannot contain a value that can reach the map.

      MapExtractor can be used to extract the content of payload.

      May be null.

      See Also:

    • setPayload

      public Message setPayload(Object e)
      Set the payload object.
      Parameters:
      e - May be null.
      Returns:
      The same Message instance the method was called on, for fluent-style building up of the message.
      See Also:

    • getMetadata

      @Deprecated public Map<String,String> getMetadata()
      Deprecated.
      Use getMetadataMap() instead
      Get the metadata for this message as a map, treating all values as strings.
      Returns:
      The metadata. Never null.

    • getMetadataMap

      public Map<String,Object> getMetadataMap()
      Get the metadata for this message as a map. Consider using MapExtractor to extract from the metadata.
      Returns:
      The metadata. Never null.

    • putMetadataValue

      public Message putMetadataValue(String key, Object value)
      Put the specified key,value pair into the metadata for this message. Keys starting with "sag." are reserved for internal use.
      Returns:
      The same Message instance the method was called on, for fluent-style building up of metadata on a message.

    • copy

      public Message copy() throws CloneNotSupportedException
      Create a copy of this Message. Returns a copy of the message. (More convenient equivalent to clone())

      Requires that the payload be and contain only objects of String, Map, List, Boolean, Double, Long or byte[].

      Throws:
      CloneNotSupportedException

    • clone

      public Object clone() throws CloneNotSupportedException
      Create a copy of this Message. Returns a copy of the message - with an Object return type to meet the Object.clone() method signature.
      Throws:
      CloneNotSupportedException

    • toString

      public String toString(boolean noTruncate)
      Return a string representation of the message metadata and payload. Long payloads may optionally be truncated with "...".
      Parameters:
      noTruncate - Set to true to disable truncation of long payload strings.

    • toString

      public String toString()
      Return a string representation of the message metadata and payload. Long payloads will be truncated with "...".
      Overrides:
      toString in class Object