Message Consumption

In this section we'll take a high-level look at the rules for specifying sources for consuming messages through non-JMS APIs in the following sections:

Detailed rules for setting the source in an attach frame can be found in Rules for Source Specification.

Specifying Consumption from Durable Queues

A client can bind to a durable queue by formatting the destination of the message as follows:

queue://queue-name

The link source durability property should be set to Configuration and the expiry policy to NEVER.

If the queue doesn't exist on the event broker, and the client’s client-profile allows them to create guaranteed endpoints, the queue will automatically be created on the event broker as an exclusive queue. If non-exclusive queues are required, copy-from templates on the event broker can be used to override this default behavior.

The queue:// prefix is optional and isn't case sensitive. If a prefix is not found on the link address, and the address doesn't start with #, the event broker will assume the client is attempting to bind to a durable queue, as long as no other setting has been used to specify the destination type.

Specifying Consumption from Non-Durable Queues

Depending upon the API used, a client can consume from a non-durable queue by formatting the AMQP link address as follows:

AMQP_NULL

or 

empty_string

with the source dynamic flag set to true. The attach response will contain a temporary queue, #P2P/QTMP/queue-name, in the attach response source address.

Specifying Consumption from Durable Topic Endpoints

A client can bind to a durable topic endpoint (DTE) by formatting the target address of the message as follows:

dsub://topic-string

or

topic://topic-string

The link source durability property must be set to Configuration and the expiry policy to NEVER.

The DTE name is specified in the link name in the attach frame and the topic subscription on the DTE is specified in the source addressed after the dsub:// or topic:// prefix.

Not all non-JMS APIs allow an application to set the link name required to identify the DTE. It's not recommended to use DTEs when the link name cannot be specified by the application since this can lead to DTEs that can't be identified by the application being created and leaked on the event broker.

JMS semantics around changing the topic assigned to a DTE apply. For example, if a client binds to the DTE with a different subscription than the one already associated with the DTE, the DTE’s existing queued messages are deleted, the existing subscription is removed from the endpoint, and the new subscription is applied to the endpoint.

If the DTE does not exist on the event broker, and the client’s client-profile allows them to create guaranteed endpoints, the DTE will automatically be created on the event broker as an exclusive DTE. If non-exclusive DTEs are required, copy-from templates on the event broker can be used to override this default behavior.

Specifying Consumption from Non-Durable Topics

A client can consume from a non-durable topic by formatting the AMQP link address as follows:

topic://topic-string

Client Deletion of Durable Topic Endpoints

AMQP clients can delete client created durable topic endpoints (DTEs) by attaching an AMQP receiver link, where the link name is the dte_name and the source of the attach frame is null, and closing the link. The attach response from the event broker will have an empty source indicating that the DTE exists and is going to be deleted, or will have a null source indicating the DTE with the provided link name does not exist on the event broker.