Message Class

  • java.lang.Object
    • Serializable
      • com.microsoft.azure.servicebus.Message

public class Message implements IMessage

Constructor Summary

Constructor Description
Message()

Creates an empty message with an empty byte array as body.

Message(byte[] content)

Creates a message from a byte array. Message body type is set to binary.

Message(byte[] content, String contentType)

Creates a message from a byte array. Message body type is set to binary.

Message(MessageBody body)

Creates a message from message body.

Message(MessageBody body, String contentType)

Creates a message from message body.

Message(String content)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Message(String messageId, byte[] content, String contentType)

Creates a message from a byte array. Message body type is set to binary.

Message(String messageId, MessageBody body, String contentType)

Creates a message from message body.

Message(String content, String contentType)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Message(String messageId, String content, String contentType)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Method Summary

Modifier and Type Method and Description
IMessage createCopy()

Creates a shallow copy of this message.

byte [] getBody()

Gets the body of this message as a byte array. It is up to client applications to decode the bytes.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Message body need not just a byte array. Replaced by <xref uid="com.microsoft.azure.servicebus.Message.getMessageBody()" data-throw-if-not-resolved="false" data-raw-source="getMessageBody()"></xref></p>

</xrefdescription>

String getContentType()

Gets the content type of this message.

Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example "application/json". Note that content type is not same as message body type.

String getCorrelationId()

Gets a correlation identifier.

Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to.

String getDeadLetterSource()

Gets the name of the queue or subscription that this message was enqueued on, before it was deadlettered.

This value is only set in messages that have been dead-lettered and subsequently auto-forwarded from the dead-letter queue to another entity. Indicates the entity in which the message was dead-lettered. This property is read-only.

long getDeliveryCount()

Gets the number of the times this message was delivered to clients.

The count is incremented when a message lock expires, or the message is explicitly abandoned by the receiver. This property is read-only.

Instant getEnqueuedTimeUtc()

Gets the instant at which this message was enqueued in Azure Service Bus.

The UTC instant at which the message has been accepted and stored in the entity. For scheduled messages, this reflects the time when the message was activated. This value can be used as an authoritative and neutral arrival time indicator when the receiver does not want to trust the sender's clock. This property is read-only.

Instant getExpiresAtUtc()

Gets the instant at which this message will expire.

The value is the UTC instant for when the message is scheduled for removal and will no longer available for retrieval from the entity due to expiration. Expiry is controlled by the getTimeToLive() property. This property is computed from getEnqueuedTimeUtc()+getTimeToLive().

String getLabel()

Gets the application specific message label.

This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line. The mapped AMQP property is "subject".

Instant getLockedUntilUtc()

Gets the instant at which the lock of this message expires.

For messages retrieved under a lock (peek-lock receive mode, not pre-settled) this property reflects the UTC instant until which the message is held locked in the queue/subscription. When the lock expires, the getDeliveryCount() is incremented and the message is again available for retrieval. This property is read-only.

UUID getLockToken()

Gets the lock token for the current message.

The lock token is a reference to the lock that is being held by the broker in PEEKLOCK mode. Locks are used to explicitly settle messages as explained in the product documentation in more detail. The token can also be used to pin the lock permanently through the Deferral API and, with that, take the message out of the regular delivery state flow. This property is read-only.

MessageBody getMessageBody()

Gets the body of this message. Client applications should extract message content based on body type.

String getMessageId()

Gets the Id of this message.

The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection feature identifies and removes second and further submissions of messages with the same MessageId.

String getPartitionKey()

Gets the partition key for sending a message to a partitioned entity.

For partitioned entities, setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly. For session-aware entities, the getSessionId() property overrides this value.

Map<String, Object> getProperties()

Gets the map of user application properties of this message. Client applications can set user properties (headers) on the message using this map.

String getReplyTo()

Gets the address of an entity to send replies to.

This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to.

String getReplyToSessionId()

Gets or sets a session identifier augmenting the getReplyTo() address.

This value augments the ReplyTo information and specifies which SessionId should be set for the reply when sent to the reply entity.

Instant getScheduledEnqueuedTimeUtc()

Gets the scheduled enqueue time of this message.

This value is used for delayed message availability. The message is safely added to the queue, but is not considered active and therefore not retrievable until the scheduled enqueue time. Mind that the message may not be activated (enqueued) at the exact given instant; the actual activation time depends on the queue's workload and its state.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Replaced by <xref uid="com.microsoft.azure.servicebus.Message.getScheduledEnqueueTimeUtc()" data-throw-if-not-resolved="false" data-raw-source="getScheduledEnqueueTimeUtc()"></xref></p>

</xrefdescription>

Instant getScheduledEnqueueTimeUtc()

Gets the scheduled enqueue time of this message.

This value is used for delayed message availability. The message is safely added to the queue, but is not considered active and therefore not retrievable until the scheduled enqueue time. Mind that the message may not be activated (enqueued) at the exact given instant; the actual activation time depends on the queue's workload and its state.

long getSequenceNumber()

Gets the unique number assigned to a message by Service Bus.

The sequence number is a unique 64-bit integer assigned to a message as it is accepted and stored by the broker and functions as its true identifier. For partitioned entities, the topmost 16 bits reflect the partition identifier. Sequence numbers monotonically increase and are gapless. They roll over to 0 when the 48-64 bit range is exhausted. This property is read-only.

String getSessionId()

Gets the session identifier for a session-aware entity.

For session-aware entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For session-unaware entities, this value is ignored.

Duration getTimeToLive()

Gets the duration before this message expires.

This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in getEnqueuedTimeUtc(). When not set explicitly, the assumed value is the DefaultTimeToLive set for the respective queue or topic. A message-level TimeToLive value cannot be longer than the entity's DefaultTimeToLive setting and it is silently adjusted if it does.

String getTo()

Gets the "to" address.

String getViaPartitionKey()

Gets the partition key for sending a message to a entity via another partitioned transfer entity.

If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to getPartitionKey() and ensures that messages are kept together and in order as they are transferred.

void setBody(byte[] body)

Sets the body of this message as a byte array.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Message body need not just a byte array. Replaced by <xref uid="com.microsoft.azure.servicebus.Message.setMessageBody(MessageBody)" data-throw-if-not-resolved="false" data-raw-source="setMessageBody(MessageBody)"></xref></p>

</xrefdescription>

void setContentType(String contentType)

Sets the content type of this message.

void setCorrelationId(String correlationId)

Sets a correlation identifier.

void setLabel(String label)

Sets an application specific message label.

void setLockedUntilUtc(Instant lockedUntilUtc)
void setMessageBody(MessageBody body)

Sets the body of this message.

void setMessageId(String messageId)

Sets the Id of this message.

void setPartitionKey(String partitionKey)

Sets a partition key for sending a message to a partitioned entity

void setProperties(Map<String, Object> properties)

Sets the map of user application properties of this message. Client applications can set user properties on the message using this map.

void setReplyTo(String replyTo)

Sets the address of an entity to send replies to.

void setReplyToSessionId(String replyToSessionId)

Gets or sets a session identifier augmenting the getReplyTo() address.

void setScheduledEnqueuedTimeUtc(Instant scheduledEnqueueTimeUtc)

Sets the scheduled enqueue time of this message.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Replaced by <xref uid="com.microsoft.azure.servicebus.Message.setScheduledEnqueueTimeUtc(Instant)" data-throw-if-not-resolved="false" data-raw-source="setScheduledEnqueueTimeUtc(Instant)"></xref></p>

</xrefdescription>

void setScheduledEnqueueTimeUtc(Instant scheduledEnqueueTimeUtc)

Sets the scheduled enqueue time of this message.

void setSessionId(String sessionId)

Sets the session identifier for a session-aware entity.

void setTimeToLive(Duration timeToLive)

Sets the duration of time before this message expires.

void setTo(String to)

Sets the "to" address.

This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.

void setViaPartitionKey(String partitionKey)

Sets a via-partition key for sending a message to a destination entity via another partitioned entity

Constructor Details

Message

public Message()

Creates an empty message with an empty byte array as body.

Message

public Message(byte[] content)

Creates a message from a byte array. Message body type is set to binary.

Parameters:

content - content of the message

Message

public Message(byte[] content, String contentType)

Creates a message from a byte array. Message body type is set to binary.

Parameters:

content - content of the message
contentType - content type of the message

Message

public Message(MessageBody body)

Creates a message from message body.

Parameters:

body - message body

Message

public Message(MessageBody body, String contentType)

Creates a message from message body.

Parameters:

body - message body
contentType - content type of the message

Message

public Message(String content)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Parameters:

content - content of the message.

Message

public Message(String messageId, byte[] content, String contentType)

Creates a message from a byte array. Message body type is set to binary.

Parameters:

messageId - id of the message
content - content of the message
contentType - content type of the message

Message

public Message(String messageId, MessageBody body, String contentType)

Creates a message from message body.

Parameters:

messageId - id of the message
body - message body
contentType - content type of the message

Message

public Message(String content, String contentType)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Parameters:

content - content of the message
contentType - content type of the message

Message

public Message(String messageId, String content, String contentType)

Creates a message from a string. For backward compatibility reasons, the string is converted to a byte array and message body type is set to binary.

Parameters:

messageId - id of the message
content - content of the message
contentType - content type of the message

Method Details

createCopy

public IMessage createCopy()

Creates a shallow copy of this message.

Overrides:

Message.createCopy()

Returns:

copy of this message

getBody

public byte [] getBody()

Gets the body of this message as a byte array. It is up to client applications to decode the bytes.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Message body need not just a byte array. Replaced by <xref uid="com.microsoft.azure.servicebus.Message.getMessageBody()" data-throw-if-not-resolved="false" data-raw-source="getMessageBody()"></xref></p>

</xrefdescription>

Overrides:

Message.getBody()

Returns:

body of this message

getContentType

public String getContentType()

Gets the content type of this message.

Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example "application/json". Note that content type is not same as message body type.

Overrides:

Message.getContentType()

Returns:

content type of this message

getCorrelationId

public String getCorrelationId()

Gets a correlation identifier.

Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to.

Overrides:

Message.getCorrelationId()

Returns:

correlation Id of this message

getDeadLetterSource

public String getDeadLetterSource()

Gets the name of the queue or subscription that this message was enqueued on, before it was deadlettered.

This value is only set in messages that have been dead-lettered and subsequently auto-forwarded from the dead-letter queue to another entity. Indicates the entity in which the message was dead-lettered. This property is read-only.

Overrides:

Message.getDeadLetterSource()

Returns:

dead letter source of this message

getDeliveryCount

public long getDeliveryCount()

Gets the number of the times this message was delivered to clients.

The count is incremented when a message lock expires, or the message is explicitly abandoned by the receiver. This property is read-only.

Overrides:

Message.getDeliveryCount()

Returns:

delivery count of this message.

getEnqueuedTimeUtc

public Instant getEnqueuedTimeUtc()

Gets the instant at which this message was enqueued in Azure Service Bus.

The UTC instant at which the message has been accepted and stored in the entity. For scheduled messages, this reflects the time when the message was activated. This value can be used as an authoritative and neutral arrival time indicator when the receiver does not want to trust the sender's clock. This property is read-only.

Overrides:

Message.getEnqueuedTimeUtc()

Returns:

the instant at which the message was enqueued in Azure Service Bus

getExpiresAtUtc

public Instant getExpiresAtUtc()

Gets the instant at which this message will expire.

The value is the UTC instant for when the message is scheduled for removal and will no longer available for retrieval from the entity due to expiration. Expiry is controlled by the getTimeToLive() property. This property is computed from getEnqueuedTimeUtc()+getTimeToLive().

Overrides:

Message.getExpiresAtUtc()

Returns:

instant at which this message expires

getLabel

public String getLabel()

Gets the application specific message label.

This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line. The mapped AMQP property is "subject".

Overrides:

Message.getLabel()

Returns:

Label property value of this message

getLockedUntilUtc

public Instant getLockedUntilUtc()

Gets the instant at which the lock of this message expires.

For messages retrieved under a lock (peek-lock receive mode, not pre-settled) this property reflects the UTC instant until which the message is held locked in the queue/subscription. When the lock expires, the getDeliveryCount() is incremented and the message is again available for retrieval. This property is read-only.

Overrides:

Message.getLockedUntilUtc()

Returns:

the instant at which the lock of this message expires if the message is received using PEEKLOCK mode. Otherwise it returns null.

getLockToken

public UUID getLockToken()

Gets the lock token for the current message.

The lock token is a reference to the lock that is being held by the broker in PEEKLOCK mode. Locks are used to explicitly settle messages as explained in the product documentation in more detail. The token can also be used to pin the lock permanently through the Deferral API and, with that, take the message out of the regular delivery state flow. This property is read-only.

Overrides:

Message.getLockToken()

Returns:

lock token of this message.

getMessageBody

public MessageBody getMessageBody()

Gets the body of this message. Client applications should extract message content based on body type.

Overrides:

Message.getMessageBody()

Returns:

body of this message

getMessageId

public String getMessageId()

Gets the Id of this message.

The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection feature identifies and removes second and further submissions of messages with the same MessageId.

Overrides:

Message.getMessageId()

Returns:

Id of this message

getPartitionKey

public String getPartitionKey()

Gets the partition key for sending a message to a partitioned entity.

For partitioned entities, setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly. For session-aware entities, the getSessionId() property overrides this value.

Overrides:

Message.getPartitionKey()

Returns:

partition key of this message

getProperties

public Map getProperties()

Gets the map of user application properties of this message. Client applications can set user properties (headers) on the message using this map.

Overrides:

Message.getProperties()

Returns:

the map of user application properties of this message

getReplyTo

public String getReplyTo()

Gets the address of an entity to send replies to.

This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to.

Overrides:

Message.getReplyTo()

Returns:

ReplyTo property value of this message

getReplyToSessionId

public String getReplyToSessionId()

Gets or sets a session identifier augmenting the getReplyTo() address.

This value augments the ReplyTo information and specifies which SessionId should be set for the reply when sent to the reply entity.

Overrides:

Message.getReplyToSessionId()

Returns:

ReplyToSessionId property value of this message

getScheduledEnqueuedTimeUtc

public Instant getScheduledEnqueuedTimeUtc()

Gets the scheduled enqueue time of this message.

This value is used for delayed message availability. The message is safely added to the queue, but is not considered active and therefore not retrievable until the scheduled enqueue time. Mind that the message may not be activated (enqueued) at the exact given instant; the actual activation time depends on the queue's workload and its state.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Replaced by <xref uid="com.microsoft.azure.servicebus.Message.getScheduledEnqueueTimeUtc()" data-throw-if-not-resolved="false" data-raw-source="getScheduledEnqueueTimeUtc()"></xref></p>

</xrefdescription>

Overrides:

Message.getScheduledEnqueuedTimeUtc()

Returns:

the instant at which the message will be enqueued in Azure Service Bus

getScheduledEnqueueTimeUtc

public Instant getScheduledEnqueueTimeUtc()

Gets the scheduled enqueue time of this message.

This value is used for delayed message availability. The message is safely added to the queue, but is not considered active and therefore not retrievable until the scheduled enqueue time. Mind that the message may not be activated (enqueued) at the exact given instant; the actual activation time depends on the queue's workload and its state.

Overrides:

Message.getScheduledEnqueueTimeUtc()

Returns:

the instant at which the message will be enqueued in Azure Service Bus

getSequenceNumber

public long getSequenceNumber()

Gets the unique number assigned to a message by Service Bus.

The sequence number is a unique 64-bit integer assigned to a message as it is accepted and stored by the broker and functions as its true identifier. For partitioned entities, the topmost 16 bits reflect the partition identifier. Sequence numbers monotonically increase and are gapless. They roll over to 0 when the 48-64 bit range is exhausted. This property is read-only.

Overrides:

Message.getSequenceNumber()

Returns:

sequence number of this message

getSessionId

public String getSessionId()

Gets the session identifier for a session-aware entity.

For session-aware entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For session-unaware entities, this value is ignored.

Overrides:

Message.getSessionId()

Returns:

session id of this message

getTimeToLive

public Duration getTimeToLive()

Gets the duration before this message expires.

This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in getEnqueuedTimeUtc(). When not set explicitly, the assumed value is the DefaultTimeToLive set for the respective queue or topic. A message-level TimeToLive value cannot be longer than the entity's DefaultTimeToLive setting and it is silently adjusted if it does.

Overrides:

Message.getTimeToLive()

Returns:

Time to Live duration of this message

getTo

public String getTo()

Gets the "to" address.

Overrides:

Message.getTo()

Returns:

To property value of this message

getViaPartitionKey

public String getViaPartitionKey()

Gets the partition key for sending a message to a entity via another partitioned transfer entity.

If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to getPartitionKey() and ensures that messages are kept together and in order as they are transferred.

Overrides:

Message.getViaPartitionKey()

Returns:

partition key on the via queue.

setBody

public void setBody(byte[] body)

Sets the body of this message as a byte array.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Message body need not just a byte array. Replaced by <xref uid="com.microsoft.azure.servicebus.Message.setMessageBody(MessageBody)" data-throw-if-not-resolved="false" data-raw-source="setMessageBody(MessageBody)"></xref></p>

</xrefdescription>

Overrides:

Message.setBody(byte[] body)

Parameters:

body - body of this message

setContentType

public void setContentType(String contentType)

Sets the content type of this message.

Overrides:

Message.setContentType(String contentType)

Parameters:

contentType - content type of this message

setCorrelationId

public void setCorrelationId(String correlationId)

Sets a correlation identifier.

Overrides:

Message.setCorrelationId(String correlationId)

Parameters:

correlationId - correlation Id of this message

setLabel

public void setLabel(String label)

Sets an application specific message label.

Overrides:

Message.setLabel(String label)

Parameters:

label - Label property value of this message

setLockedUntilUtc

public void setLockedUntilUtc(Instant lockedUntilUtc)

Parameters:

lockedUntilUtc

setMessageBody

public void setMessageBody(MessageBody body)

Sets the body of this message.

Overrides:

Message.setMessageBody(MessageBody body)

Parameters:

body - body of this message

setMessageId

public void setMessageId(String messageId)

Sets the Id of this message.

Overrides:

Message.setMessageId(String messageId)

Parameters:

messageId - Id of this message

setPartitionKey

public void setPartitionKey(String partitionKey)

Sets a partition key for sending a message to a partitioned entity

Overrides:

Message.setPartitionKey(String partitionKey)

Parameters:

partitionKey - partition key of this message

setProperties

public void setProperties(Map properties)

Sets the map of user application properties of this message. Client applications can set user properties on the message using this map.

Overrides:

Message.setProperties(Map<String, Object> properties)

Parameters:

properties - the map of user application properties of this message

setReplyTo

public void setReplyTo(String replyTo)

Sets the address of an entity to send replies to.

Overrides:

Message.setReplyTo(String replyTo)

Parameters:

replyTo - ReplyTo property value of this message

setReplyToSessionId

public void setReplyToSessionId(String replyToSessionId)

Gets or sets a session identifier augmenting the getReplyTo() address.

Overrides:

Message.setReplyToSessionId(String replyToSessionId)

Parameters:

replyToSessionId - ReplyToSessionId property value of this message

setScheduledEnqueuedTimeUtc

public void setScheduledEnqueuedTimeUtc(Instant scheduledEnqueueTimeUtc)

Sets the scheduled enqueue time of this message.

<xreftitle>Deprecated</xreftitle>

<xrefdescription>

  <p>Replaced by <xref uid="com.microsoft.azure.servicebus.Message.setScheduledEnqueueTimeUtc(Instant)" data-throw-if-not-resolved="false" data-raw-source="setScheduledEnqueueTimeUtc(Instant)"></xref></p>

</xrefdescription>

Overrides:

Message.setScheduledEnqueuedTimeUtc(Instant scheduledEnqueueTimeUtc)

Parameters:

scheduledEnqueueTimeUtc - the instant at which this message should be enqueued in Azure Service Bus

setScheduledEnqueueTimeUtc

public void setScheduledEnqueueTimeUtc(Instant scheduledEnqueueTimeUtc)

Sets the scheduled enqueue time of this message.

Overrides:

Message.setScheduledEnqueueTimeUtc(Instant scheduledEnqueueTimeUtc)

Parameters:

scheduledEnqueueTimeUtc - the instant at which this message should be enqueued in Azure Service Bus

setSessionId

public void setSessionId(String sessionId)

Sets the session identifier for a session-aware entity.

Overrides:

Message.setSessionId(String sessionId)

Parameters:

sessionId - session id of this message

setTimeToLive

public void setTimeToLive(Duration timeToLive)

Sets the duration of time before this message expires.

Overrides:

Message.setTimeToLive(Duration timeToLive)

Parameters:

timeToLive - Time to Live duration of this message

setTo

public void setTo(String to)

Sets the "to" address.

This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.

Overrides:

Message.setTo(String to)

Parameters:

to - To property value of this message

setViaPartitionKey

public void setViaPartitionKey(String partitionKey)

Sets a via-partition key for sending a message to a destination entity via another partitioned entity

Overrides:

Message.setViaPartitionKey(String partitionKey)

Parameters:

viaPartitionKey - via-partition key of this message

Applies to