Interface Message<E>
-
- Type Parameters:
E
- The type of the message body that this message carries
- All Known Subinterfaces:
AdvancedMessage<E>
,StreamReceiverMessage
,StreamSenderMessage
- All Known Implementing Classes:
ClientMessage
,ClientStreamReceiverMessage
public interface Message<E>
Message object that provides a high level abstraction to raw AMQP types
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description long
absoluteExpiryTime()
Message<E>
absoluteExpiryTime(long expiryTime)
Sets the absolute expiration time value to assign to thisMessage
.Object
annotation(String key)
Returns the requested message annotation value from thisMessage
if it exists or returns null otherwise.Message<E>
annotation(String key, Object value)
Sets the given message annotation value at the given key, replacing any previous value that was assigned to thisMessage
.E
body()
Returns the body value that is conveyed in this message or null if no body was set locally or sent from the remote if this is an incoming message.Message<E>
body(E value)
Sets the body value that is to be conveyed to the remote when this message is sent.String
contentEncoding()
Message<?>
contentEncoding(String contentEncoding)
Sets the contentEncoding value to assign to thisMessage
.String
contentType()
Message<E>
contentType(String contentType)
Sets the contentType value to assign to thisMessage
.Object
correlationId()
Message<E>
correlationId(Object correlationId)
Sets the correlationId value to assign to thisMessage
.static <E> Message<E>
create()
static Message<byte[]>
create(byte[] body)
static <E> Message<E>
create(E body)
static <E> Message<List<E>>
create(List<E> body)
static <K,V>
Message<Map<K,V>>create(Map<K,V> body)
long
creationTime()
Message<E>
creationTime(long createTime)
Sets the creation time value to assign to thisMessage
.long
deliveryCount()
Message<E>
deliveryCount(long deliveryCount)
Sets the value to assign to the delivery count field of thisMessage
.boolean
durable()
For an message being sent this method returns the current state of the durable flag on the message.Message<E>
durable(boolean durable)
Controls if the message is marked as durable when sent.boolean
firstAcquirer()
Message<E>
firstAcquirer(boolean firstAcquirer)
Sets the value to assign to the first acquirer field of thisMessage
.Object
footer(String key)
Returns the requested footer value from thisMessage
if it exists or returnsnull
otherwise.Message<E>
footer(String key, Object value)
Sets the given footer value at the given key, replacing any previous value that was assigned to thisMessage
.Message<E>
forEachAnnotation(BiConsumer<String,Object> action)
Invokes the givenBiConsumer
on each message annotation entry carried in thisMessage
.Message<E>
forEachFooter(BiConsumer<String,Object> action)
Invokes the givenBiConsumer
on each footer entry carried in thisMessage
.Message<E>
forEachProperty(BiConsumer<String,Object> action)
Invokes the givenBiConsumer
on each application property entry carried in thisMessage
.String
groupId()
Message<E>
groupId(String groupId)
Sets the groupId value to assign to thisMessage
.int
groupSequence()
Message<E>
groupSequence(int groupSequence)
Sets the group sequence value to assign to thisMessage
.boolean
hasAnnotation(String key)
Query theMessage
to determine if it carries the given message annotation key.boolean
hasAnnotations()
Query theMessage
to determine if it carries any message annotations.boolean
hasFooter(String key)
Query theMessage
to determine if it carries the given footer key.boolean
hasFooters()
Query theMessage
to determine if it carries any footers.boolean
hasProperties()
Query theMessage
to determine if it carries any application properties.boolean
hasProperty(String key)
Query theMessage
to determine if it carries the given application property key.Object
messageId()
Message<E>
messageId(Object messageId)
Sets the message Id value to assign to thisMessage
.byte
priority()
Message<E>
priority(byte priority)
Sets the relative message priority.Object
property(String key)
Returns the requested application property value from thisMessage
if it exists or returns null otherwise.Message<E>
property(String key, Object value)
Sets the given application property value at the given key, replacing any previous value that was assigned to thisMessage
.Object
removeAnnotation(String key)
Removes the given message annotation from the values carried in the message currently, if none was present than this method returnsnull
.Object
removeFooter(String key)
Removes the given footer from the values carried in the message currently, if none was present than this method returnsnull
.Object
removeProperty(String key)
Removes the given application property from the values carried in the message currently, if none was present than this method returnsnull
.String
replyTo()
Message<E>
replyTo(String replyTo)
Sets the replyTo value to assign to thisMessage
.String
replyToGroupId()
Message<E>
replyToGroupId(String replyToGroupId)
Sets the replyTo group Id value to assign to thisMessage
.String
subject()
Message<E>
subject(String subject)
Sets the subject value to assign to thisMessage
.long
timeToLive()
Message<E>
timeToLive(long timeToLive)
Sets the message time to live value.String
to()
Message<E>
to(String to)
Sets the 'to' value to assign to thisMessage
.default AdvancedMessage<E>
toAdvancedMessage()
Safely convert thisMessage
instance into anAdvancedMessage
reference which can offer more low level APIs to an experienced client user.byte[]
userId()
Message<E>
userId(byte[] userId)
Sets the user Id value to assign to thisMessage
.
-
-
-
Method Detail
-
create
static <E> Message<E> create()
-
create
static <E> Message<E> create(E body)
-
create
static Message<byte[]> create(byte[] body)
-
create
static <E> Message<List<E>> create(List<E> body)
- Type Parameters:
E
- The type that the List elements should be treated as.- Parameters:
body
- An List that will be wrapped in anAmqpSequence
body section.- Returns:
- a new
Message
instance with a body containing the given List.
-
toAdvancedMessage
default AdvancedMessage<E> toAdvancedMessage() throws ClientException
Safely convert thisMessage
instance into anAdvancedMessage
reference which can offer more low level APIs to an experienced client user.The default implementation first checks if the current instance is already of the correct type before performing a brute force conversion of the current message to the client's own internal
AdvancedMessage
implementation. Users should override this method if the internal conversion implementation is insufficient to obtain the proper message structure to encode a meaningful 'on the wire' encoding of their custom implementation.- Returns:
- a
AdvancedMessage
that contains this message's current state. - Throws:
UnsupportedOperationException
- if theMessage
implementation cannot be convertedClientException
- if an error occurs while converting the message to anAdvancedMessage
/
-
durable
boolean durable() throws ClientException
For an message being sent this method returns the current state of the durable flag on the message. For a received message this method returns the durable flag value at the time of sending (or false if not set) unless the value is updated after being received by the receiver.- Returns:
- true if the Message is marked as being durable
- Throws:
ClientException
- if an error occurs while reading the given value.
-
durable
Message<E> durable(boolean durable) throws ClientException
Controls if the message is marked as durable when sent.- Parameters:
durable
- value assigned to the durable flag for this message.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
priority
byte priority() throws ClientException
- Returns:
- the currently configured priority or the default if none set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
priority
Message<E> priority(byte priority) throws ClientException
Sets the relative message priority. Higher numbers indicate higher priority messages. Messages with higher priorities MAY be delivered before those with lower priorities. For a received message this overwrites any value that was set by the remote sender.- Parameters:
priority
- The priority value to assign this message.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
timeToLive
long timeToLive() throws ClientException
- Returns:
- the currently set Time To Live duration (milliseconds).
- Throws:
ClientException
- if an error occurs while reading the given value.
-
timeToLive
Message<E> timeToLive(long timeToLive) throws ClientException
Sets the message time to live value.The time to live duration in milliseconds for which the message is to be considered "live". If this is set then a message expiration time will be computed based on the time of arrival at an intermediary. Messages that live longer than their expiration time will be discarded (or dead lettered). When a message is transmitted by an intermediary that was received with a time to live, the transmitted message's header SHOULD contain a time to live that is computed as the difference between the current time and the formerly computed message expiration time, i.e., the reduced time to live, so that messages will eventually die if they end up in a delivery loop.
- Parameters:
timeToLive
- The time span in milliseconds that this message should remain live before being discarded.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
firstAcquirer
boolean firstAcquirer() throws ClientException
- Returns:
- if this message has been acquired by another link previously
- Throws:
ClientException
- if an error occurs while reading the given value.
-
firstAcquirer
Message<E> firstAcquirer(boolean firstAcquirer) throws ClientException
Sets the value to assign to the first acquirer field of thisMessage
.If this value is true, then this message has not been acquired by any other link. If this value is false, then this message MAY have previously been acquired by another link or links.
- Parameters:
firstAcquirer
- The boolean value to assign to the first acquirer field of the message.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
deliveryCount
long deliveryCount() throws ClientException
- Returns:
- the number of failed delivery attempts that this message has been part of.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
deliveryCount
Message<E> deliveryCount(long deliveryCount) throws ClientException
Sets the value to assign to the delivery count field of thisMessage
.Delivery count is the number of unsuccessful previous attempts to deliver this message. If this value is non-zero it can be taken as an indication that the delivery might be a duplicate. On first delivery, the value is zero. It is incremented upon an outcome being settled at the sender, according to rules defined for each outcome.
- Parameters:
deliveryCount
- The new delivery count value to assign to this message.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
messageId
Object messageId() throws ClientException
- Returns:
- the currently set Message ID or null if none set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
messageId
Message<E> messageId(Object messageId) throws ClientException
Sets the message Id value to assign to thisMessage
.The message Id, if set, uniquely identifies a message within the message system. The message producer is usually responsible for setting the message-id in such a way that it is assured to be globally unique. A remote peer MAY discard a message as a duplicate if the value of the message-id matches that of a previously received message sent to the same node.
- Parameters:
messageId
- The message Id value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
userId
byte[] userId() throws ClientException
- Returns:
- the currently set User ID or null if none set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
userId
Message<E> userId(byte[] userId) throws ClientException
Sets the user Id value to assign to thisMessage
.The identity of the user responsible for producing the message. The client sets this value, and it MAY be authenticated by intermediaries.
- Parameters:
userId
- The user Id value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
to
String to() throws ClientException
- Returns:
- the currently set 'To' address which indicates the intended destination of the message.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
to
Message<E> to(String to) throws ClientException
Sets the 'to' value to assign to thisMessage
.The to field identifies the node that is the intended destination of the message. On any given transfer this might not be the node at the receiving end of the link.
- Parameters:
to
- The 'to' node value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
subject
String subject() throws ClientException
- Returns:
- the currently set subject metadata for this message or null if none set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
subject
Message<E> subject(String subject) throws ClientException
Sets the subject value to assign to thisMessage
.A common field for summary information about the message content and purpose.
- Parameters:
subject
- The subject node value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
replyTo
String replyTo() throws ClientException
- Returns:
- the configured address of the node where replies to this message should be sent, or null if not set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
replyTo
Message<E> replyTo(String replyTo) throws ClientException
Sets the replyTo value to assign to thisMessage
.The address of the node to send replies to.
- Parameters:
replyTo
- The replyTo node value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
correlationId
Object correlationId() throws ClientException
- Returns:
- the currently assigned correlation ID or null if none set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
correlationId
Message<E> correlationId(Object correlationId) throws ClientException
Sets the correlationId value to assign to thisMessage
.This is a client-specific id that can be used to mark or identify messages between clients.
- Parameters:
correlationId
- The correlationId value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
contentType
String contentType() throws ClientException
- Returns:
- the assigned content type value for the message body section or null if not set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
contentType
Message<E> contentType(String contentType) throws ClientException
Sets the contentType value to assign to thisMessage
.The RFC-2046 MIME type for the message's application-data section (body). As per RFC-2046 this can contain a charset parameter defining the character encoding used: e.g., 'text/plain; charset="utf-8"'.
For clarity, as per section 7.2.1 of RFC-2616, where the content type is unknown the content-type SHOULD NOT be set. This allows the recipient the opportunity to determine the actual type. Where the section is known to be truly opaque binary data, the content-type SHOULD be set to application/octet-stream.
When using an application-data section with a section code other than data, content-type SHOULD NOT be set.
- Parameters:
contentType
- The contentType value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
contentEncoding
String contentEncoding() throws ClientException
- Returns:
- the assigned content encoding value for the message body section or null if not set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
contentEncoding
Message<?> contentEncoding(String contentEncoding) throws ClientException
Sets the contentEncoding value to assign to thisMessage
.The content-encoding property is used as a modifier to the content-type. When present, its value indicates what additional content encodings have been applied to the application-data, and thus what decoding mechanisms need to be applied in order to obtain the media-type referenced by the content-type header field.
Content-encoding is primarily used to allow a document to be compressed without losing the identity of its underlying content type.
Content-encodings are to be interpreted as per section 3.5 of RFC 2616 [RFC2616]. Valid content-encodings are registered at IANA [IANAHTTPPARAMS].
The content-encoding MUST NOT be set when the application-data section is other than data. The binary representation of all other application-data section types is defined completely in terms of the AMQP type system.
Implementations MUST NOT use the identity encoding. Instead, implementations SHOULD NOT set this property. Implementations SHOULD NOT use the compress encoding, except as to remain compatible with messages originally sent with other protocols, e.g. HTTP or SMTP.
Implementations SHOULD NOT specify multiple content-encoding values except as to be compatible with messages originally sent with other protocols, e.g. HTTP or SMTP.
- Parameters:
contentEncoding
- The contentEncoding value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
absoluteExpiryTime
long absoluteExpiryTime() throws ClientException
- Returns:
- the configured absolute time of expiration for this message.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
absoluteExpiryTime
Message<E> absoluteExpiryTime(long expiryTime) throws ClientException
Sets the absolute expiration time value to assign to thisMessage
.An absolute time when this message is considered to be expired.
- Parameters:
expiryTime
- The absolute expiration time value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
creationTime
long creationTime() throws ClientException
- Returns:
- the absolute time of creation for this message.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
creationTime
Message<E> creationTime(long createTime) throws ClientException
Sets the creation time value to assign to thisMessage
.An absolute time when this message was created.
- Parameters:
createTime
- The creation time value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
groupId
String groupId() throws ClientException
- Returns:
- the assigned group ID for this message or null if not set.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
groupId
Message<E> groupId(String groupId) throws ClientException
Sets the groupId value to assign to thisMessage
.Identifies the group the message belongs to.
- Parameters:
groupId
- The groupId value to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
groupSequence
int groupSequence() throws ClientException
- Returns:
- the assigned group sequence for this message.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
groupSequence
Message<E> groupSequence(int groupSequence) throws ClientException
Sets the group sequence value to assign to thisMessage
.The relative position of this message within its group.
- Parameters:
groupSequence
- The group sequence to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
replyToGroupId
String replyToGroupId() throws ClientException
- Returns:
- the client-specific id used so that client can send replies to this message to a specific group.
- Throws:
ClientException
- if an error occurs while reading the given value.
-
replyToGroupId
Message<E> replyToGroupId(String replyToGroupId) throws ClientException
Sets the replyTo group Id value to assign to thisMessage
.This is a client-specific id that is used so that client can send replies to this message to a specific group.
- Parameters:
replyToGroupId
- The replyTo group Id to assign to thisMessage
instance.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs while writing the given value.
-
annotation
Object annotation(String key) throws ClientException
Returns the requested message annotation value from thisMessage
if it exists or returns null otherwise.- Parameters:
key
- The key of the message annotation to query for.- Returns:
- the corresponding message annotation value of null if none was carried in this
Message
. - Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
hasAnnotation
boolean hasAnnotation(String key) throws ClientException
Query theMessage
to determine if it carries the given message annotation key.- Parameters:
key
- The key of the message annotation to query for.- Returns:
true
if the Message carries the given message annotation.- Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
hasAnnotations
boolean hasAnnotations() throws ClientException
Query theMessage
to determine if it carries any message annotations.- Returns:
true
if the Message carries any message annotations.- Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
removeAnnotation
Object removeAnnotation(String key) throws ClientException
Removes the given message annotation from the values carried in the message currently, if none was present than this method returnsnull
.- Parameters:
key
- The key of the message annotation to query for removal.- Returns:
- the message annotation value that was previously assigned to that key.
- Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
forEachAnnotation
Message<E> forEachAnnotation(BiConsumer<String,Object> action) throws ClientException
Invokes the givenBiConsumer
on each message annotation entry carried in thisMessage
.- Parameters:
action
- The action that will be invoked on each message annotation entry.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
annotation
Message<E> annotation(String key, Object value) throws ClientException
Sets the given message annotation value at the given key, replacing any previous value that was assigned to thisMessage
.- Parameters:
key
- The message annotation key where the value is to be assigned.value
- The value to assign to the given message annotation key.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the message annotations in thisMessage
.
-
property
Object property(String key) throws ClientException
Returns the requested application property value from thisMessage
if it exists or returns null otherwise.- Parameters:
key
- The key of the application property to query for.- Returns:
- the corresponding application property value of null if none was carried in this
Message
. - Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
property
Message<E> property(String key, Object value) throws ClientException
Sets the given application property value at the given key, replacing any previous value that was assigned to thisMessage
.- Parameters:
key
- The application property key where the value is to be assigned.value
- The value to assign to the given application property key.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
hasProperty
boolean hasProperty(String key) throws ClientException
Query theMessage
to determine if it carries the given application property key.- Parameters:
key
- The key of the application property to query for.- Returns:
true
if the Message carries the given application property.- Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
hasProperties
boolean hasProperties() throws ClientException
Query theMessage
to determine if it carries any application properties.- Returns:
true
if the Message carries any application properties.- Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
removeProperty
Object removeProperty(String key) throws ClientException
Removes the given application property from the values carried in the message currently, if none was present than this method returnsnull
.- Parameters:
key
- The key of the application property to query for removal.- Returns:
- the application property value that was previously assigned to that key.
- Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
forEachProperty
Message<E> forEachProperty(BiConsumer<String,Object> action) throws ClientException
Invokes the givenBiConsumer
on each application property entry carried in thisMessage
.- Parameters:
action
- The action that will be invoked on each application property entry.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the application properties in thisMessage
.
-
footer
Object footer(String key) throws ClientException
Returns the requested footer value from thisMessage
if it exists or returnsnull
otherwise.- Parameters:
key
- The key of the footer to query for.- Returns:
- the corresponding footer value of null if none was carried in this
Message
. - Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
hasFooter
boolean hasFooter(String key) throws ClientException
Query theMessage
to determine if it carries the given footer key.- Parameters:
key
- The key of the footer to query for.- Returns:
true
if the Message carries the given footer.- Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
hasFooters
boolean hasFooters() throws ClientException
Query theMessage
to determine if it carries any footers.- Returns:
true
if the Message carries any footers.- Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
removeFooter
Object removeFooter(String key) throws ClientException
Removes the given footer from the values carried in the message currently, if none was present than this method returnsnull
.- Parameters:
key
- The key of the footer to query for removal.- Returns:
- the footer value that was previously assigned to that key.
- Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
forEachFooter
Message<E> forEachFooter(BiConsumer<String,Object> action) throws ClientException
Invokes the givenBiConsumer
on each footer entry carried in thisMessage
.- Parameters:
action
- The action that will be invoked on each footer entry.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
footer
Message<E> footer(String key, Object value) throws ClientException
Sets the given footer value at the given key, replacing any previous value that was assigned to thisMessage
.- Parameters:
key
- The footer key where the value is to be assigned.value
- The value to assign to the given footer key.- Returns:
- this
Message
instance. - Throws:
ClientException
- if an error occurs accessing the footers in thisMessage
.
-
body
E body() throws ClientException
Returns the body value that is conveyed in this message or null if no body was set locally or sent from the remote if this is an incoming message.- Returns:
- the message body value or null if none present.
- Throws:
ClientException
- if the implementation can't provide a body for some reason.
-
body
Message<E> body(E value) throws ClientException
Sets the body value that is to be conveyed to the remote when this message is sent.The
Message
implementation will choose the AMQPSection
to use to wrap the given value.- Parameters:
value
- The value to assign to the given message bodySection
.- Returns:
- this
Message
instance. - Throws:
ClientException
- if the implementation cannot write to the body section for some reason..
-
-