public final class Message
extends java.lang.Object
implements java.lang.Cloneable
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.
Modifier and Type | Field and 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 and 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
|
Modifier and Type | Method and 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.
|
public static final java.lang.String CHANNEL
public static final java.lang.String HOST_MESSAGE_TYPE
public static final java.lang.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.
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.
public static final java.lang.String REQUEST_ID
public static final java.lang.String CONTROL_TYPE_FLUSH
public static final java.lang.String CONTROL_TYPE_FLUSH_ACK
CONTROL_TYPE_FLUSH
,
REQUEST_ID
,
CONTROL_TYPE
,
Constant Field Valuespublic static final java.lang.String CONTROL_TYPE_ACK_REQUIRED
CONTROL_TYPE_ACK_UPTO
,
MESSAGE_ID
,
CONTROL_TYPE
,
Constant Field Valuespublic static final java.lang.String CONTROL_TYPE_ACK_UPTO
public Message(java.lang.Object payload, java.util.Map<java.lang.String,?> metadata)
public Message(java.lang.Object payload)
public java.lang.Object getPayload()
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.
setPayload(java.lang.Object)
,
MapExtractor
public Message setPayload(java.lang.Object e)
e
- May be null.getPayload()
@Deprecated public java.util.Map<java.lang.String,java.lang.String> getMetadata()
getMetadataMap()
insteadpublic java.util.Map<java.lang.String,java.lang.Object> getMetadataMap()
MapExtractor
to extract from the metadata.public Message putMetadataValue(java.lang.String key, java.lang.Object value)
public Message copy() throws java.lang.CloneNotSupportedException
Requires that the payload be and contain only objects of String, Map, List, Boolean, Double, Long or byte[].
java.lang.CloneNotSupportedException
public java.lang.Object clone() throws java.lang.CloneNotSupportedException
clone
in class java.lang.Object
java.lang.CloneNotSupportedException
public java.lang.String toString(boolean noTruncate)
noTruncate
- Set to true to disable truncation of long payload strings.public java.lang.String toString()
toString
in class java.lang.Object
Submit a bug or feature
Copyright (c) 2013-2021 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG.