Queue Routes route all messages from a source queue to a destination exchange. If message acknowledgement is enabled, messages are removed from the queue when they have been received by the destination exchange; if message acknowledgement is off, messages are removed from the queue when sent.

Exchange routes route messages from a source exchange to a destination exchange, using a binding key (which is optional for a fanout exchange).

Internally, creating an exchange route creates a private queue (auto-delete, exclusive) on the source broker to hold messages that are to be routed to the destination broker, binds this private queue to the source broker exchange, and subscribes the destination broker to the queue.

Dynamic exchange routes allow a client to create bindings to an exchange on one broker, and receive messages that satisfy the conditions of these bindings not only from the exchange to which the client created the binding, but also from other exchanges that are connected to it using dynamic exchange routes. If the client modifies the bindings for a given exchange, they are also modified for dynamic exchange routes associated with that exchange.

Dynamic exchange routes apply all the bindings of a destination exchange to a source exchange, so that any message that would match one of these bindings is routed to the destination exchange. If bindings are added or removed from the destination exchange, these changes are reflected in the dynamic exchange route -- when the destination broker creates a binding with a given binding key, this is reflected in the route, and when the destination broker drops a binding with a binding key, the route no longer incurs the overhead of transferring messages that match the binding key among brokers. If two exchanges have dynamic exchange routes to each other, then all bindings in each exchange are reflected in the dynamic exchange route of the other. In a dynamic exchange route, the source and destination exchanges must have the same exchange type, and they must have the same name; for instance, if the source exchange is a direct exchange, the destination exchange must also be a direct exchange, and the names must match.

Internally, dynamic exchange routes are implemented in the same way as exchange routes, except that the bindings used to implement dynamic exchange routes are modified if the bindings in the destination exchange change.

A dynamic exchange route is always a pull route. It can never be a push route.

The syntax for creating and deleting queue routes is as follows:

	qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue>
	qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue>
      

For instance, the following creates a queue route that routes all messages from the queue named public on the source broker localhost:10002 to the amq.fanout exchange on the destination broker localhost:10001:

	$ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public
      

If the -d option is specified, this queue route is persistent, and will be restored if one or both of the brokers is restarted:

	$ qpid-route -d queue add localhost:10001 localhost:10002 amq.fanout public
      

The del command takes the same arguments as the add command. The following command deletes the queue route described above:

	$ qpid-route queue del localhost:10001 localhost:10002 amq.fanout public
      

The syntax for creating and deleting exchange routes is as follows:

	qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key>
	qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key>
	qpid-route [OPTIONS] flush [<broker>]
      

For instance, the following creates an exchange route that routes messages that match the binding key global.# from the amq.topic exchange on the source broker localhost:10002 to the amq.topic exchange on the destination broker localhost:10001:

	$ qpid-route route add localhost:10001 localhost:10002 amq.topic global.#
      

In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second exchange route, reversing the roles of the two exchanges:

	$ qpid-route route add localhost:10002 localhost:10001 amq.topic global.#
      

If the -d option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted:

	$ qpid-route -d route add localhost:10001 localhost:10002 amq.fanout public
      

The del command takes the same arguments as the add command. The following command deletes the first exchange route described above:

	$ qpid-route route del localhost:10001 localhost:10002 amq.topic global.#
      

Use the flush command to delete all routes for a given broker:

	qpid-route [OPTIONS] flush [<broker>]
      

For instance, the following command deletes all routes for the broker localhost:10001:

	$ qpid-route flush localhost:10001
      

The syntax for creating and deleting dynamic exchange routes is as follows:

	qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange>
	qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange>
      

In the following examples, we will route messages from a topic exchange. We will create a new topic exchange and federate it so that we are not affected by other all clients that use the built-in amq.topic exchange. The following commands create a new topic exchange on each of two brokers:

	$ qpid-config -a localhost:10003 add exchange topic fed.topic
	$ qpid-config -a localhost:10004 add exchange topic fed.topic
      

Now let's create a dynamic exchange route that routes messages from the fed.topic exchange on the source broker localhost:10004 to the fed.topic exchange on the destination broker localhost:10003 if they match any binding on the destination broker's fed.topic exchange:

	$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
      

Internally, this creates a private autodelete queue on the source broker, and binds that queue to the fed.topic exchange on the source broker, using each binding associated with the fed.topic exchange on the destination broker.

In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second dynamic exchange route, reversing the roles of the two exchanges:

	$ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
      

If the -d option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted:

	$ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic
      

When an exchange route is durable, the private queue used to store messages for the route on the source exchange is also durable. If the connection between the brokers is lost, messages for the destination exchange continue to accumulate until it can be restored.

The del command takes the same arguments as the add command. The following command deletes the first exchange route described above:

	$ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic
      

Internally, this deletes the bindings on the source exchange for the the private queues associated with the message route.

The route list command shows the routes associated with an individual broker. For instance, suppose we have created the following two routes:

	$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
	$ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
      

We can now use route list to show all routes for the broker localhost:10003:

	$ qpid-route route list localhost:10003
	localhost:10003 localhost:10004 fed.topic <dynamic>
      

Note that this shows only one of the two routes we created, the route for which localhost:10003 is a destination. If we want to see the route for which localhost:10004 is a destination, we need to do another route list:

	$ qpid-route route list localhost:10004
	localhost:10004 localhost:10003 fed.topic <dynamic>
      

The route map command shows all routes associated with a broker, and recursively displays all routes for brokers involved in federation relationships with the given broker. For instance, here is the output for the two brokers configured above:

	$ qpid-route route map localhost:10003

	Finding Linked Brokers:
	localhost:10003... Ok
	localhost:10004... Ok

	Dynamic Routes:

	Exchange fed.topic:
	localhost:10004 <=> localhost:10003

	Static Routes:
	none found
      

Note that the two dynamic exchange links are displayed as though they were one bidirectional link. The route map command is particularly helpful for larger, more complex networks. Let's configure a somewhat more complex network with 16 dynamic exchange routes:

	qpid-route dynamic add localhost:10001 localhost:10002 fed.topic
	qpid-route dynamic add localhost:10002 localhost:10001 fed.topic

	qpid-route dynamic add localhost:10003 localhost:10002 fed.topic
	qpid-route dynamic add localhost:10002 localhost:10003 fed.topic

	qpid-route dynamic add localhost:10004 localhost:10002 fed.topic
	qpid-route dynamic add localhost:10002 localhost:10004 fed.topic

	qpid-route dynamic add localhost:10002 localhost:10005 fed.topic
	qpid-route dynamic add localhost:10005 localhost:10002 fed.topic

	qpid-route dynamic add localhost:10005 localhost:10006 fed.topic
	qpid-route dynamic add localhost:10006 localhost:10005 fed.topic

	qpid-route dynamic add localhost:10006 localhost:10007 fed.topic
	qpid-route dynamic add localhost:10007 localhost:10006 fed.topic

	qpid-route dynamic add localhost:10006 localhost:10008 fed.topic
	qpid-route dynamic add localhost:10008 localhost:10006 fed.topic
      

Now we can use route map starting with any one broker, and see the entire network:

	$ ./qpid-route route map localhost:10001

	Finding Linked Brokers:
	localhost:10001... Ok
	localhost:10002... Ok
	localhost:10003... Ok
	localhost:10004... Ok
	localhost:10005... Ok
	localhost:10006... Ok
	localhost:10007... Ok
	localhost:10008... Ok

	Dynamic Routes:

	Exchange fed.topic:
	localhost:10002 <=> localhost:10001
	localhost:10003 <=> localhost:10002
	localhost:10004 <=> localhost:10002
	localhost:10005 <=> localhost:10002
	localhost:10006 <=> localhost:10005
	localhost:10007 <=> localhost:10006
	localhost:10008 <=> localhost:10006

	Static Routes:
	none found
      

When a broker route is created, or when a durable broker route is restored after broker restart, a connection is created between the source broker and the destination broker. The connections used between brokers are called resilient connections; if the connection fails due to a communication error, it attempts to reconnect. The retry interval begins at 2 seconds and, as more attempts are made, grows to 64 seconds, and continues to retry every 64 seconds thereafter. If the connection fails due to an authentication problem, it will not continue to retry.

The command list connections can be used to show the resilient connections for a broker:

	$ qpid-route list connections localhost:10001

	Host            Port    Transport Durable  State             Last Error
	=============================================================================
	localhost       10002   tcp          N     Operational
	localhost       10003   tcp          N     Operational
	localhost       10009   tcp          N     Waiting           Connection refused
      

In the above output, Last Error contains the string representation of the last connection error received for the connection. State represents the state of the connection, and may be one of the following values: