com.microsoft.azure.servicebus.IMessage Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of azure-servicebus Show documentation
Show all versions of azure-servicebus Show documentation
Java library for Azure Service Bus. Please note, a newer package com.azure:azure-messaging-servicebus for Azure Service Bus is available as of December 2020. While this package will continue to receive critical bug fixes, we strongly encourage you to upgrade. Read the migration guide at https://aka.ms/azsdk/java/migrate/sb for more details.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.microsoft.azure.servicebus;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
/**
* Represents the message that is exchanged between Azure Service Bus and its clients.
*
* @since 1.0
* @see Messages, Payloads, and Serialization
*/
public interface IMessage {
/**
* 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.
*
* @return delivery count of this message.
* @see Message transfers, locks, and settlement.
*/
long getDeliveryCount();
/**
* 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.
*
* @return Id of this message
*/
String getMessageId();
/**
* Sets the Id of this message.
* @param messageId Id of this message
* @see #getMessageId()
*/
void setMessageId(String messageId);
/**
* 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
* {@link #getEnqueuedTimeUtc() 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.
*
* @return Time to Live duration of this message
* @see Message Expiration
*/
Duration getTimeToLive();
/**
* Sets the duration of time before this message expires.
*
* @param timeToLive Time to Live duration of this message
* @see #getTimeToLive()
*/
void setTimeToLive(Duration timeToLive);
/**
* 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.
*
* @return content type of this message
*/
String getContentType();
/**
* Sets the content type of this message.
*
* @param contentType content type of this message
* @see #getContentType()
*/
void setContentType(String contentType);
/**
* 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 {@link #getTimeToLive() TimeToLive} property.
* This property is computed from {@link #getEnqueuedTimeUtc() EnqueuedTimeUtc}+{@link #getTimeToLive() TimeToLive}.
*
* @return instant at which this message expires
* @see Message Expiration
*/
Instant getExpiresAtUtc();
/**
* 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 {@link #getDeliveryCount() DeliveryCount}
* is incremented and the message is again available for retrieval. This property is read-only.
* @return the instant at which the lock of this message expires if the message is received using PEEKLOCK mode. Otherwise it returns null.
* @see Message transfers, locks, and settlement
*/
Instant getLockedUntilUtc();
/**
* 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.
*
* @return the instant at which the message was enqueued in Azure Service Bus
* @see Message Sequencing and Timestamps
*/
Instant getEnqueuedTimeUtc();
/**
* 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.
*
* @return the instant at which the message will be enqueued in Azure Service Bus
* @see Message Sequencing and Timestamps
* @deprecated Replaced by {@link #getScheduledEnqueueTimeUtc()}
*/
@Deprecated
Instant getScheduledEnqueuedTimeUtc();
/**
* Sets the scheduled enqueue time of this message.
*
* @param scheduledEnqueueTimeUtc the instant at which this message should be enqueued in Azure Service Bus
* @see #getScheduledEnqueueTimeUtc()
* @deprecated Replaced by {@link #setScheduledEnqueueTimeUtc(Instant)}
*/
@Deprecated
void setScheduledEnqueuedTimeUtc(Instant scheduledEnqueueTimeUtc);
/**
* 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.
*
* @return the instant at which the message will be enqueued in Azure Service Bus
* @see Message Sequencing and Timestamps
*/
Instant getScheduledEnqueueTimeUtc();
/**
* Sets the scheduled enqueue time of this message.
*
* @param scheduledEnqueueTimeUtc the instant at which this message should be enqueued in Azure Service Bus
* @see #getScheduledEnqueueTimeUtc()
*/
void setScheduledEnqueueTimeUtc(Instant scheduledEnqueueTimeUtc);
/**
* 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.
*
* @return sequence number of this message
* @see Message Sequencing and Timestamps
*/
long getSequenceNumber();
/**
* 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.
*
* @return session id of this message
* @see Message Sessions
*/
String getSessionId();
/**
* Sets the session identifier for a session-aware entity.
*
* @param sessionId session id of this message
* @see #getSessionId()
*/
void setSessionId(String sessionId);
/**
* Gets the body of this message as a byte array. It is up to client applications
* to decode the bytes.
*
* @return body of this message
* @see Messages, payloads, and serialization
* @deprecated Message body need not just a byte array. Replaced by {@link #getMessageBody()}
*/
@Deprecated
byte[] getBody();
/**
* Sets the body of this message as a byte array.
*
* @param body body of this message
* @see #getBody()
* @deprecated Message body need not just a byte array. Replaced by {@link #setMessageBody(MessageBody)}
*/
@Deprecated
void setBody(byte[] body);
/**
* Gets the body of this message. Client applications should extract message content based on body type.
*
* @return body of this message
* @see Messages, payloads, and serialization
*/
MessageBody getMessageBody();
/**
* Sets the body of this message.
*
* @param body body of this message
* @see #getMessageBody()
*/
void setMessageBody(MessageBody body);
/**
* Gets the map of user application properties of this message. Client
* applications can set user properties (headers) on the message using this map.
*
* @return the map of user application properties of this message
* @see Messages, payloads, and serialization
*/
Map getProperties();
/**
* Sets the map of user application properties of this message. Client applications
* can set user properties on the message using this map.
*
* @param properties the map of user application properties of this message
* @see #getProperties()
*/
void setProperties(Map properties);
/**
* 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.
*
* @return correlation Id of this message
* @see Message Routing and Correlation
*/
String getCorrelationId();
/**
* Sets a correlation identifier.
*
* @param correlationId correlation Id of this message
* @see #getCorrelationId()
*/
void setCorrelationId(String correlationId);
/**
* Gets the "to" address.
*
* @return To property value of this message
*/
String getTo();
/**
* 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.
*
* @param to To property value of this message
*/
void setTo(String to);
/**
* 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.
*
* @return ReplyTo property value of this message
* @see Message Routing and Correlation
*/
String getReplyTo();
/**
* Sets the address of an entity to send replies to.
*
* @param replyTo ReplyTo property value of this message
* @see #getReplyTo()
*/
void setReplyTo(String replyTo);
/**
* 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".
*
* @return Label property value of this message
*/
String getLabel();
/**
* Sets an application specific message label.
*
* @param label Label property value of this message
* @see #getLabel()
*/
void setLabel(String label);
/**
* Gets or sets a session identifier augmenting the {@link #getReplyTo() ReplyTo} address.
*
* This value augments the ReplyTo information and specifies which SessionId should be set
* for the reply when sent to the reply entity.
*
* @return ReplyToSessionId property value of this message
* @see Message Routing and Correlation
*/
String getReplyToSessionId();
/**
* Gets or sets a session identifier augmenting the {@link #getReplyTo() ReplyTo} address.
*
* @param replyToSessionId ReplyToSessionId property value of this message
*/
void setReplyToSessionId(String replyToSessionId);
/**
* 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 {@link #getSessionId() SessionId } property overrides this value.
*
* @return partition key of this message
* @see Partitioned entities
*/
String getPartitionKey();
/**
* Sets a partition key for sending a message to a partitioned entity
*
* @param partitionKey partition key of this message
* @see #getPartitionKey()
*/
void setPartitionKey(String partitionKey);
/**
* 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 {@link #getPartitionKey()} and ensures that
* messages are kept together and in order as they are transferred.
*
* @return partition key on the via queue.
* @see Transfers and Send Via
*/
String getViaPartitionKey();
/**
* Sets a via-partition key for sending a message to a destination entity via another partitioned entity
*
* @param viaPartitionKey via-partition key of this message
* @see #getViaPartitionKey()
*/
void setViaPartitionKey(String viaPartitionKey);
/**
* 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.
*
* @return dead letter source of this message
* @see Dead-letter queues
*/
String getDeadLetterSource();
/**
* 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.
*
* @return lock token of this message.
* @see Message transfers, locks, and settlement
*/
UUID getLockToken();
/**
* Creates a shallow copy of this message.
* @return copy of this message
*/
IMessage createCopy();
}