Package org.apache.qpid.protonj2.client

Interface AdvancedMessage<E>

Type Parameters:

E - The type of the message body that this message carries

All Superinterfaces:

Message<E>

All Known Subinterfaces:

StreamReceiverMessage, StreamSenderMessage

All Known Implementing Classes:

ClientMessage, ClientStreamReceiverMessage

public interface AdvancedMessage<E>
extends Message<E>

Advanced AMQP Message object that provides a thin abstraction to raw AMQP types

Method Summary

Modifier and Type	Method	Description
AdvancedMessage<E>	addBodySection(Section<?> bodySection)	Adds the given Section to the internal collection of sections that will be sent to the remote peer when this message is encoded.
MessageAnnotations	annotations()	Return the current MessageAnnotations assigned to this message, if none was assigned yet then this method returns null.
AdvancedMessage<E>	annotations(MessageAnnotations messageAnnotations)	Assign or replace the MessageAnnotations instance associated with this message.
ApplicationProperties	applicationProperties()	Return the current ApplicationProperties assigned to this message, if none was assigned yet then this method returns null.
AdvancedMessage<E>	applicationProperties(ApplicationProperties applicationProperties)	Assign or replace the ApplicationProperties instance associated with this message.
Collection<Section<?>>	bodySections()	Create and return an unmodifiable Collection that contains the Section instances currently assigned to this message.
AdvancedMessage<E>	bodySections(Collection<Section<?>> sections)	Sets the body Section instances to use when encoding this message.
AdvancedMessage<E>	clearBodySections()	Clears all current body Section elements from the AdvancedMessage.
static <V> AdvancedMessage<V>	create()	Creates a new AdvancedMessage instance using the library default implementation.
default ProtonBuffer	encode(Map<String,Object> deliveryAnnotations)	Encodes the AdvancedMessage for transmission by the client.
ProtonBuffer	encode(Map<String,Object> deliveryAnnotations, ProtonBufferAllocator allocator)	Encodes the AdvancedMessage for transmission by the client.
Footer	footer()	Return the current Footer assigned to this message, if none was assigned yet then this method returns null.
AdvancedMessage<E>	footer(Footer footer)	Assign or replace the Footer instance associated with this message.
AdvancedMessage<E>	forEachBodySection(Consumer<Section<?>> consumer)	Performs the given action for each body Section of the AdvancedMessage until all sections have been presented to the given Consumer or the consumer throws an exception.
Header	header()	Return the current Header assigned to this message, if none was assigned yet then this method returns null.
AdvancedMessage<E>	header(Header header)	Assign or replace the Header instance associated with this message.
int	messageFormat()
AdvancedMessage<E>	messageFormat(int messageFormat)	Sets the message format to use when the message is sent.
Properties	properties()	Return the current Properties assigned to this message, if none was assigned yet then this method returns null.
AdvancedMessage<E>	properties(Properties properties)	Assign or replace the Properties instance associated with this message.

Methods inherited from interface org.apache.qpid.protonj2.client.Message

absoluteExpiryTime, absoluteExpiryTime, annotation, annotation, body, body, contentEncoding, contentEncoding, contentType, contentType, correlationId, correlationId, creationTime, creationTime, deliveryCount, deliveryCount, durable, durable, firstAcquirer, firstAcquirer, footer, footer, forEachAnnotation, forEachFooter, forEachProperty, groupId, groupId, groupSequence, groupSequence, hasAnnotation, hasAnnotations, hasFooter, hasFooters, hasProperties, hasProperty, messageId, messageId, priority, priority, property, property, removeAnnotation, removeFooter, removeProperty, replyTo, replyTo, replyToGroupId, replyToGroupId, subject, subject, timeToLive, timeToLive, to, to, toAdvancedMessage, userId, userId

Method Details

create

static <V> AdvancedMessage<V> create()

Creates a new AdvancedMessage instance using the library default implementation.

Type Parameters:

V - The type to use when specifying the body section value type.

Returns:

a new AdvancedMessage instance.

header

Header header()
       throws ClientException

Return the current Header assigned to this message, if none was assigned yet then this method returns null.

Returns:

the currently assigned Header for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

header

AdvancedMessage<E> header(Header header)
                   throws ClientException

Assign or replace the Header instance associated with this message.

Parameters:

header - The Header value to assign to this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing the message Header value.

annotations

MessageAnnotations annotations()
                        throws ClientException

Return the current MessageAnnotations assigned to this message, if none was assigned yet then this method returns null.

Returns:

the currently assigned MessageAnnotations for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

annotations

AdvancedMessage<E> annotations(MessageAnnotations messageAnnotations)
                        throws ClientException

Assign or replace the MessageAnnotations instance associated with this message.

Parameters:

messageAnnotations - The MessageAnnotations value to assign to this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing the message MessageAnnotations value.

properties

Properties properties()
               throws ClientException

Return the current Properties assigned to this message, if none was assigned yet then this method returns null.

Returns:

the currently assigned Properties for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

properties

AdvancedMessage<E> properties(Properties properties)
                       throws ClientException

Assign or replace the Properties instance associated with this message.

Parameters:

properties - The Properties value to assign to this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing the message Properties value.

applicationProperties

ApplicationProperties applicationProperties()
                                     throws ClientException

Return the current ApplicationProperties assigned to this message, if none was assigned yet then this method returns null.

Returns:

the currently assigned ApplicationProperties for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

applicationProperties

AdvancedMessage<E> applicationProperties(ApplicationProperties applicationProperties)
                                  throws ClientException

Assign or replace the ApplicationProperties instance associated with this message.

Parameters:

applicationProperties - The ApplicationProperties value to assign to this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing the message ApplicationProperties value.

footer

Footer footer()
       throws ClientException

Return the current Footer assigned to this message, if none was assigned yet then this method returns null.

Returns:

the currently assigned Footer for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

footer

AdvancedMessage<E> footer(Footer footer)
                   throws ClientException

Assign or replace the Footer instance associated with this message.

Parameters:

footer - The Footer value to assign to this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing the message Footer value.

messageFormat

int messageFormat()
           throws ClientException

Returns:

the currently assigned message format for this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

messageFormat

AdvancedMessage<E> messageFormat(int messageFormat)
                          throws ClientException

Sets the message format to use when the message is sent. The exact structure of a message, together with its encoding, is defined by the message format (default is the AMQP defined message format zero.

This field MUST be specified for the first transfer of a multi-transfer message, if it is not set at the time of send of the first transfer the sender uses the AMQP default value of zero for this field.

The upper three octets of a message format code identify a particular message format. The lowest octet indicates the version of said message format. Any given version of a format is forwards compatible with all higher versions.

       3 octets      1 octet
    +----------------+---------+
    | message format | version |
    +----------------+---------+
    |                          |
   msb                        lsb

 

Parameters:

messageFormat - The message format to encode into the transfer frame that carries the message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while configuring the message format.

addBodySection

AdvancedMessage<E> addBodySection(Section<?> bodySection)
                           throws ClientException

Adds the given Section to the internal collection of sections that will be sent to the remote peer when this message is encoded. If a previous section was added by a call to the Message.body(Object) method it should be retained as the first element of the running list of body sections contained in this message.

The implementation should make an attempt to validate that sections added are valid for the message format that is assigned when they are added.

Parameters:

bodySection - The Section instance to append to the internal collection.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing to the message body sections.

bodySections

AdvancedMessage<E> bodySections(Collection<Section<?>> sections)
                         throws ClientException

Sets the body Section instances to use when encoding this message. The value given replaces any existing sections assigned to this message through the Message.body(Object) or addBodySection(Section) methods. Calling this method with a null or empty collection is equivalent to calling the clearBodySections() method.

Parameters:

sections - The Collection of Section instance to assign this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while writing to the message body sections.

bodySections

Collection<Section<?>> bodySections()
                             throws ClientException

Create and return an unmodifiable Collection that contains the Section instances currently assigned to this message. Changes to this message body after calling this will not be reflected in the returned collection.

Returns:

an unmodifiable Collection that is a view of the current sections assigned to this message.

Throws:

ClientException - if an error occurs while retrieving the message data.

forEachBodySection

AdvancedMessage<E> forEachBodySection(Consumer<Section<?>> consumer)
                               throws ClientException

Performs the given action for each body Section of the AdvancedMessage until all sections have been presented to the given Consumer or the consumer throws an exception.

Parameters:

consumer - the Consumer that will operate on each of the body sections in this message.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while iterating over the message data.

clearBodySections

AdvancedMessage<E> clearBodySections()
                              throws ClientException

Clears all current body Section elements from the AdvancedMessage.

Returns:

this AdvancedMessage instance.

Throws:

ClientException - if an error occurs while clearing the message body sections.

encode

default ProtonBuffer encode(Map<String,Object> deliveryAnnotations)
                     throws ClientException

Encodes the AdvancedMessage for transmission by the client. The provided DeliveryAnnotations can be included or augmented by the AdvancedMessage implementation based on the target message format. The implementation is responsible for ensuring that the delivery annotations are treated correctly encoded into the correct location in the message.

Parameters:

deliveryAnnotations - A Map of delivery annotation values that were requested to be included in the transmitted message.

Returns:

the encoded form of this message in a ProtonBuffer instance.

Throws:

ClientException - if an error occurs while encoding the message data.

encode

ProtonBuffer encode(Map<String,Object> deliveryAnnotations,
 ProtonBufferAllocator allocator)
             throws ClientException

Encodes the AdvancedMessage for transmission by the client. The provided DeliveryAnnotations can be included or augmented by the AdvancedMessage implementation based on the target message format. The implementation is responsible for ensuring that the delivery annotations are treated correctly encoded into the correct location in the message.

Parameters:

deliveryAnnotations - A Map of delivery annotation values that were requested to be included in the transmitted message.

allocator - An allocator that should be used to create the buffer the message is encoded into.

Returns:

the encoded form of this message in a ProtonBuffer instance.

Throws:

ClientException - if an error occurs while encoding the message data.