Package com.softwareag.connectivity

Class Message

  • All Implemented Interfaces:
    java.lang.Cloneable
    public final class Message
extends java.lang.Object
implements java.lang.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 Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CHANNEL
      The metadata key for the channel name.
      static java.lang.String CONTROL_TYPE
      The metadata key indicating that a message is a control message, and what its type is.
      static java.lang.String CONTROL_TYPE_ACK_REQUIRED
      Name of the AckRequired control message, a towards-host control message.
      static java.lang.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.
      static java.lang.String CONTROL_TYPE_FLUSH
      Name of the Flush control message, a towards-transport control message.
      static java.lang.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.
      static java.lang.String HOST_MESSAGE_TYPE
      The metadata key for the type of message; its meaning is host-specific.
      static java.lang.String MESSAGE_ID
      The metadata key used for unique identification of towards-host messages.
      static java.lang.String REQUEST_ID
      The metadata key used for unique identification of towards-transport control messages, with a value of type Long.

    • Constructor Summary

      Constructors 
      Constructor Description
      Message​(java.lang.Object payload)
      Create a message with the given payload.
      Message​(java.lang.Object payload, java.util.Map<java.lang.String,​?> metadata)
      Create a message with the given payload and metadata

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.Object clone()
      Create a copy of this Message.
      Message copy()
      Create a copy of this Message.
      java.util.Map<java.lang.String,​java.lang.String> getMetadata()
      Deprecated.
      Use getMetadataMap() instead
      java.util.Map<java.lang.String,​java.lang.Object> getMetadataMap()
      Get the metadata for this message as a map.
      java.lang.Object getPayload()
      Get the payload object.
      Message putMetadataValue​(java.lang.String key, java.lang.Object value)
      Put the specified key,value pair into the metadata for this message.
      Message setPayload​(java.lang.Object e)
      Set the payload object.
      java.lang.String toString()
      Return a string representation of the message metadata and payload.
      java.lang.String toString​(boolean noTruncate)
      Return a string representation of the message metadata and payload.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • CHANNEL

        public static final java.lang.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:
        Constant Field Values

      • HOST_MESSAGE_TYPE

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

      • MESSAGE_ID

        public static final java.lang.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:
        CONTROL_TYPE_ACK_REQUIRED, CONTROL_TYPE_ACK_UPTO, CONTROL_TYPE, Constant Field Values

      • CONTROL_TYPE_FLUSH

        public static final java.lang.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, REQUEST_ID, CONTROL_TYPE, Constant Field Values

      • CONTROL_TYPE_FLUSH_ACK

        public static final java.lang.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_FLUSH, REQUEST_ID, CONTROL_TYPE, Constant Field Values

      • CONTROL_TYPE_ACK_REQUIRED

        public static final java.lang.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, MESSAGE_ID, CONTROL_TYPE, Constant Field Values

      • CONTROL_TYPE_ACK_UPTO

        public static final java.lang.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:
        CONTROL_TYPE_ACK_REQUIRED, MESSAGE_ID, CONTROL_TYPE, Constant Field Values

    • Constructor Detail

      • Message

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

      • Message

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

    • Method Detail

      • getPayload

        public java.lang.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(java.lang.Object), MapExtractor

      • setPayload

        public Message setPayload​(java.lang.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:
        getPayload()

      • getMetadata

        @Deprecated
public java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.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​(java.lang.String key,
                                java.lang.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 java.lang.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:
        java.lang.CloneNotSupportedException

      • clone

        public java.lang.Object clone()
                       throws java.lang.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:
        java.lang.CloneNotSupportedException

      • toString

        public java.lang.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 java.lang.String toString()
        Return a string representation of the message metadata and payload. Long payloads will be truncated with "...".
        Overrides:
        toString in class java.lang.Object