Interface Message<E>

    • Method Detail

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