Menu Search

Chapter 8. Binding URL

The Binding URL syntax is the only addressing syntax supported by the Qpid JMS client for AMQP 0-8, 0-9 and 0-9-1. It allows to specify the bindings that define the relationship between a queue and an exchange, queue and exchange creation arguments and client behaviour.

The format for a Binding URL is provided below

<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']]
    

where

  • Exchange Class, specifies the type of the exchange, for example, direct,topic,fanout, etc.

  • Exchange Name, specifies the name of the exchange, for example, amq.direct,amq.topic, etc.

  • Destination, is an optional part of Binding URL. It can be used to specify a routing key with the non direct exchanges if an option routingkey is not specified. If both Destination and option routingkey are specified, then option routingkey has precedence.

  • Queue, is an optional part of Binding URL to specify a queue name for JMS queue destination. It is ignored in JMS topic destinations. Queue names may consist of any mixture of digits, letters, and underscores

  • Options, key-value pairs separated by '=' character specifying queue and exchange creation arguments, routing key, client behaviour, etc.

Binding URL option quoting

Take care with the quoting surrounding option values. Each option value must be surrounded with single quotes (').

The following Binding URL options are currently defined:

Table 8.1. Binding URL options

OptionTypeDescription

durable

boolean

Queue durability flag. If it is set to true, a durable queue is requested to create. The durable queue should be stored on the Broker and remained there after Broker restarts until it is explicitly deleted. This option has no meaning for JMS topic destinations, as by nature a topic destination only exists when a subscriber is connected. If durability is required for topic destinations, the durable subscription should be created.

exclusive

boolean

Queue exclusivity flag. The client cannot use a queue that was declared as exclusive by another still-open connection.

autodelete

boolean

Queue auto-deletion flag. If it is set to true on queue creation, the queue is deleted if there are no remaining subscribers.

exchangeautodelete

boolean

Exchange auto-deletion flag.

exchangedurable

boolean

Exchange durability flag. If it is set to true when creating a new exchange, the exchange will be marked as durable. Durable exchanges should remain active after Broker restarts. Non-durable exchanges are deleted on following Broker restart.

routingkey

string

Defines the value of the binding key to bind a queue to the exchange. It is always required to specify for JMS topic destinations. If routing key option is not set in Binding URL and direct exchange class is specified, the queue name is used as a routing key. MessagePublisher uses routing key to publish messages onto exchange.

browse

boolean

If set to true on a destination for a message consumer, such consumer can only read messages on the queue but cannot consume them. The consumer behaves like a queue browser in this case.

rejectbehaviour

string

Defines the reject behaviour for the re-delivered messages. If set to 'SERVER' the client delegates the requeue/DLQ decision to the server. If this option is not specified, the messages won't be moved to the DLQ (or dropped) when delivery count exceeds the maximum.


8.1. Binding URL Examples

8.1.1. Binding URLs for declaring of JMS Queues

The Qpid client Binding URLs for JMS queue destinations can be declared using direct exchange (Mostly it is a pre-defined exchange with a name "amq.direct". Also, custom direct exchanges can be used.):

direct://amq.direct//<Queue Name>
         

The Binding URLs for destinations created with calls to Session.createQueue(String) can be expressed as

direct://amq.direct//<Queue Name>?durable='true'
         

The durability flag is set to true in such destinations.

Example 8.1. Binding URL examples for JMS queues

direct://amq.direct//myNonDurableQueue
direct://amq.direct//myDurableQueue?durable='true'
direct://amq.direct//myAnotherQueue?durable='true'&routingkey='myqueue'
direct://amq.direct//myQueue?durable='true'&routingkey='myqueue'&rejectbehaviour='server'
direct://custom.direct//yetAnotherQueue
        

8.1.2. Binding URLs for declaring of JMS Topics

The Binding URLs for JMS queue destinations can be declared using topic exchange (A pre-defined exchange having name "amq.topic" is used mainly. However, custom topic exchanges can be used as well):

topic://amq.topic//<Queue name>?routingkey='<Topic Name>'&exclusive='true'&autodelete='true'
         

The Binding URLs for a topic destination created with calls to Session.createTopic("hello") is provided below:

Example 8.2. Binding URL examples for JMS topics

topic://amq.topic/hello/tmp_127_0_0_1_36973_1?routingkey='hello'&exclusive='true'&autodelete='true'
        


8.1.3. Wildcard characters in routing keys for topic destinations

AMQP exchanges of class topic can route messages to the queues using special matches containing wildcard characters (a "#" matches one or more words, a "*" matches a single word). The routing keys words are separated with a "." delimiter to distinguish words for matching. Thus, if a consumer application specifies a routing key in the destination like "usa.#", it should receive all the messages matching to that routing key. For example, "usa.boston", "usa.new-york", etc.

The examples of the Binding URLs having routing keys with wildcards characters are provided below:

topic://amq.topic?routingkey='stocks.#'
topic://amq.topic?routingkey='stocks.*.ibm'
topic://amq.topic?routingkey='stocks.nyse.ibm'
        

8.1.4. More Examples

Table 8.2. Binding URL examples

Binding URLDescription

fanout://amq.fanout//myQueue

Binding URL binding queue "myQueue" to predefined "amq.fanout" exchange of class "fanout"

topic://custom.topic//anotherQueue?routingkey='aq'

Binding URL binding queue "anotherQueue" to the exchange with name "custom.topic" of class "topic" using binding key "aq".