Package org.apache.qpid.protonj2.client

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 Details

    • create

      static <E> Message<E> create()
      Create and return an Message that will carry no body Section unless one is assigned by the caller.
      Type Parameters:
      E - The type that the message body should be treated as.
      Returns:
      a new Message instance with an empty body Section.

    • create

      static <E> Message<E> create(E body)
      Create and return an Message that will wrap the given Object in an AmqpValue section.
      Type Parameters:
      E - The type that the message body should be treated as.
      Parameters:
      body - An object that will be wrapped in an AmqpValue body section.
      Returns:
      a new Message instance with a body containing the given value.

    • create

      static Message<byte[]> create(byte[] body)
      Create and return an Message that will wrap the given byte array in an Data section.
      Parameters:
      body - An byte array that will be wrapped in an Data body section.
      Returns:
      a new Message instance with a body containing the given byte array.

    • create

      static <E> Message<List<E>> create(List<E> body)
      Create and return an Message that will wrap the given List in an AmqpSequence section.
      Type Parameters:
      E - The type that the List elements should be treated as.
      Parameters:
      body - An List that will be wrapped in an AmqpSequence body section.
      Returns:
      a new Message instance with a body containing the given List.

    • create

      static <K, V> Message<Map<K,V>> create(Map<K,V> body)
      Create and return an Message that will wrap the given Map in an AmqpValue section.
      Type Parameters:
      K - the type that the Map keys should be treated as.
      V - the type that the Map values should be treated as.
      Parameters:
      body - An Map that will be wrapped in an AmqpValue body section.
      Returns:
      a new Message instance with a body containing the given Map.

    • toAdvancedMessage

      default AdvancedMessage<E> toAdvancedMessage() throws ClientException
      Safely convert this Message instance into an AdvancedMessage 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 the Message implementation cannot be converted
      ClientException - if an error occurs while converting the message to an AdvancedMessage/

    • 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 this Message.

      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 this Message.

      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 this Message.

      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 this Message 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 this Message.

      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 this Message 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 this Message.

      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 this Message 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 this Message.

      A common field for summary information about the message content and purpose.

      Parameters:
      subject - The subject node value to assign to this Message 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 this Message.

      The address of the node to send replies to.

      Parameters:
      replyTo - The replyTo node value to assign to this Message 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 this Message.

      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 this Message 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 this Message.

      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 this Message 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 this Message.

      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 this Message 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 this Message.

      An absolute time when this message is considered to be expired.

      Parameters:
      expiryTime - The absolute expiration time value to assign to this Message 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 this Message.

      An absolute time when this message was created.

      Parameters:
      createTime - The creation time value to assign to this Message 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 this Message.

      Identifies the group the message belongs to.

      Parameters:
      groupId - The groupId value to assign to this Message 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 this Message.

      The relative position of this message within its group.

      Parameters:
      groupSequence - The group sequence to assign to this Message 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 this Message.

      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 this Message 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 this Message 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 this Message.

    • hasAnnotation

      boolean hasAnnotation(String key) throws ClientException
      Query the Message 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 this Message.

    • hasAnnotations

      boolean hasAnnotations() throws ClientException
      Query the Message 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 this Message.

    • 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 returns null.
      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 this Message.

    • forEachAnnotation

      Message<E> forEachAnnotation(BiConsumer<String,Object> action) throws ClientException
      Invokes the given BiConsumer on each message annotation entry carried in this Message.
      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 this Message.

    • 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 this Message.
      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 this Message.

    • property

      Object property(String key) throws ClientException
      Returns the requested application property value from this Message 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 this Message.

    • 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 this Message.
      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 this Message.

    • hasProperty

      boolean hasProperty(String key) throws ClientException
      Query the Message 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 this Message.

    • hasProperties

      boolean hasProperties() throws ClientException
      Query the Message 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 this Message.

    • 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 returns null.
      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 this Message.

    • forEachProperty

      Message<E> forEachProperty(BiConsumer<String,Object> action) throws ClientException
      Invokes the given BiConsumer on each application property entry carried in this Message.
      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 this Message.

    • footer

      Object footer(String key) throws ClientException
      Returns the requested footer value from this Message if it exists or returns null 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 this Message.

    • hasFooter

      boolean hasFooter(String key) throws ClientException
      Query the Message 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 this Message.

    • hasFooters

      boolean hasFooters() throws ClientException
      Query the Message 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 this Message.

    • 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 returns null.
      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 this Message.

    • forEachFooter

      Message<E> forEachFooter(BiConsumer<String,Object> action) throws ClientException
      Invokes the given BiConsumer on each footer entry carried in this Message.
      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 this Message.

    • 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 this Message.
      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 this Message.

    • 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 AMQP Section to use to wrap the given value.

      Parameters:
      value - The value to assign to the given message body Section.
      Returns:
      this Message instance.
      Throws:
      ClientException - if the implementation cannot write to the body section for some reason..