Chapter 7. Routing

Routing is the process by which messages are delivered to their destinations. To accomplish this, AMQ Interconnect provides two routing mechanisms: message routing and link routing.

Message routing

Routing is performed on messages as producers send them to a router. When a message arrives on a router, the router routes the message and its settlement based on the message’s address and routing pattern.

Figure 7.1. Message Routing

In this diagram, the message producer attaches a link to the router, and then sends a message over the link. When the router receives the message, it identifies the message’s destination based on the message’s address, and then uses its routing table to determine the best route to deliver the message either to its destination or to the next hop in the route. All dispositions (including settlement) are propagated along the same path that the original message transfer took. Flow control is handled between the sender and the router, and then between the router and the receiver.

Link routing

Routing is performed on link-attach frames, which are chained together to form a virtual messaging path that directly connects a sender and receiver. Once a link route is established, the transfer of message deliveries, flow frames, and dispositions is performed across the link route.

Figure 7.2. Link Routing

In this diagram, a router is connected to clients and to a broker, and it provides a link route to a queue on the broker (my_queue). The sender connects to the router, and the router propagates the link-attaches to the broker to form a direct link between the sender and the broker. The sender can begin sending messages to the queue, and the router passes the deliveries along the link route directly to the broker queue.

7.1. Comparison of Message Routing and Link Routing

While you can use either message routing or link routing to deliver messages to a destination, they differ in several important ways. Understanding these differences will enable you to choose the proper routing approach for any particular use case.

7.1.1. When to Use Message Routing

Message routing is the default routing mechanism. You can use it to route messages on a per-message basis between clients directly (direct-routed messaging), or to and from broker queues (brokered messaging).

Message routing is best suited to the following requirements:

Default, basic message routing.
AMQ Interconnect automatically routes messages by default, so manual configuration is only required if you want routing behavior that is different than the default.
Message-based routing patterns.
Message routing supports both anycast and multicast routing patterns. You can load-balance individual messages across multiple consumers, and multicast (or fan-out) messages to multiple subscribers.
Sharding messages across multiple broker instances when message delivery order is not important.
Sharding messages from one producer might cause that producer’s messages to be received in a different order than the order in which they were sent.

Message routing is not suitable for any of the following requirements:

Dedicated path through the router network.
For inter-router transfers, all message deliveries are placed on the same inter-router link. This means that the traffic for one address might affect the delivery of the traffic for another address.
Granular, end-to-end flow control.
With message routing, end-to-end flow control is based on the settlement of deliveries and therefore might not be optimal in every case.
Transaction support.
Server-side selectors.

7.1.2. When to Use Link Routing

Link routing requires more detailed configuration than message routing as well as an AMQP container that can accept incoming link-attaches (typically a broker). However, link routing enables you to satisfy more advanced use cases than message routing.

You can use link routing if you need to meet any of the following requirements:

Dedicated path through the router network.
With link routing, each link route has dedicated inter-router links through the network. Each link has its own dedicated message buffers, which means that the address will not have "head-of-line" blocking issues with other addresses.
Sharding messages across multiple broker instances with guaranteed delivery order.
Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance.
End-to-end flow control.
Flow control is "real" in that credits flow across the link route from the receiver to the sender.
Transaction support.
Link routing supports local transactions to a broker.
Server-side selectors.
With a link route, consumers can provide server-side selectors for broker subscriptions.

7.2. Configuring Message Routing

With message routing, routing is performed on messages as producers send them to a router. When a message arrives on a router, the router routes the message and its settlement based on the message’s address and routing pattern.

With message routing, you can do the following:

Route messages between clients (direct-routed, or brokerless messaging)
This involves configuring an address with a routing pattern. All messages sent to the address will be routed based on the routing pattern.
Route messages through a broker queue (brokered messaging)
This involves configuring a waypoint address to identify the broker queue and then connecting the router to the broker. All messages sent to the waypoint address will be routed to the broker queue.

7.2.1. Addresses

Addresses determine how messages flow through your router network. An address designates an endpoint in your messaging network, such as:

Endpoint processes that consume data or offer a service
Topics that match multiple consumers to multiple producers
Entities within a messaging broker:
- Queues
- Durable Topics
- Exchanges

When a router receives a message, it uses the message’s address to determine where to send the message (either its destination or one step closer to its destination).

7.2.2. Routing Patterns

Each address has one of the following routing patterns, which define the path that a message with the address can take across the messaging network:

Balanced

An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and AMQ Interconnect attempts to balance the traffic load across the router network.

If multiple consumers are attached to the same address, each router determines which outbound path should receive a message by considering each path’s current number of unsettled deliveries. This means that more messages will be delivered along paths where deliveries are settled at higher rates.

Note

AMQ Interconnect neither measures nor uses message settlement time to determine which outbound path to use.

In this scenario, the messages are spread across both receivers regardless of path length:

Figure 7.3. Balanced Message Routing

Closest

An anycast method in which every message is sent along the shortest path to reach the destination, even if there are other consumers for the same address.

AMQ Interconnect determines the shortest path based on the topology cost to reach each of the consumers. If there are multiple consumers with the same lowest cost, messages will be spread evenly among those consumers.

In this scenario, all messages sent by Sender will be delivered to Receiver 1:

Figure 7.4. Closest Message Routing

Multicast

Messages are sent to all consumers attached to the address. Each consumer will receive one copy of the message.

In this scenario, all messages are sent to all receivers:

Figure 7.5. Multicast Message Routing

7.2.3. Message Settlement

Message settlement is negotiated between the producer and the router when the producer establishes a link to the router. Depending on the settlement pattern, messages might be delivered with any of the following degrees of reliability:

At most once
At least once
Exactly once

AMQ Interconnect treats all messages as either pre-settled or unsettled, and it is responsible for propagating the settlement of each message it routes.

Pre-settled

Sometimes called fire and forget, the router settles the incoming and outgoing deliveries and propagates the settlement to the message’s destination. However, it does not guarantee delivery.

Unsettled

The router propagates the settlement between the sender and receiver, and guarantees one of the following outcomes:

The message is delivered and settled, with the consumer’s disposition indicated.
The delivery is settled with a disposition of RELEASED.
This means that the message did not reach its destination.
The delivery is settled with a disposition of MODIFIED.
This means that the message might or might not have reached its destination. The delivery is considered to be "in-doubt" and should be re-sent if "at least once" delivery is required.
The link, session, or connection to AMQ Interconnect was dropped, and all deliveries are "in-doubt".

7.2.4. Routing Messages Between Clients

You can route messages between clients without using a broker. In a brokerless scenario (sometimes called direct-routed messaging), AMQ Interconnect routes messages between clients directly.

To route messages between clients, you configure an address with a routing distribution pattern. When a router receives a message with this address, the message is routed to its destination or destinations based on the address’s routing distribution pattern.

Procedure

In the router’s configuration file, add an address section:
```
address {
    prefix: ADDRESS_PREFIX
    distribution: balanced|closest|multicast
    ...
}
```
prefix
The address prefix. All messages that match this prefix will be distributed according to the distribution pattern you specify.
The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1.
distribution
The message distribution pattern. The default is balanced, but you can specify any of the following options:
balanced - Messages sent to the address will be routed to one of the receivers, and the routing network will attempt to balance the traffic load based on the rate of settlement.
closest - Messages sent to the address are sent on the shortest path to reach the destination. It means that if there are multiple receivers for the same address, only the closest one will receive the message.
multicast - Messages are sent to all receivers that are attached to the address in a publish/subscribe model.
For more information about message distribution patterns, see Routing Patterns.
For information about additional attributes, see Address in the Configuration Reference.
Add the same address section to any other routers that need to use the address.
The address that you added to this router configuration file only controls how this router distributes messages sent to the address. If you have additional routers in your router network that should distribute messages for this address, then you must add the same address section to each of their configuration files.

7.2.5. Routing Messages Through a Broker Queue

You can route messages to and from a broker queue to provide clients with access to the queue through a router. In this scenario, clients connect to a router to send and receive messages, and the router routes the messages to or from the broker queue.

You can route messages to a queue hosted on a single broker, or route messages to a sharded queue distributed across multiple brokers.

Figure 7.6. Brokered Messaging

In this diagram, the sender connects to the router and sends messages to my_queue. The router attaches an outgoing link to the broker, and then sends the messages to my_queue. Later, the receiver connects to the router and requests messages from my_queue. The router attaches an incoming link to the broker to receive the messages from my_queue, and then delivers them to the receiver.

You can also route messages to a sharded queue, which is a single, logical queue comprised of multiple, underlying physical queues. Using queue sharding, it is possible to distribute a single queue over multiple brokers. Clients can connect to any of the brokers that hold a shard to send and receive messages.

Figure 7.7. Brokered Messaging with Sharded Queue

In this diagram, a sharded queue (my_queue) is distributed across two brokers. The router is connected to the clients and to both brokers. The sender connects to the router and sends messages to my_queue. The router attaches an outgoing link to each broker, and then sends messages to each shard (by default, the routing distribution is balanced). Later, the receiver connects to the router and requests all of the messages from my_queue. The router attaches an incoming link to one of the brokers to receive the messages from my_queue, and then delivers them to the receiver.

Procedure

Add a waypoint address.
This address identifies the queue to which you want to route messages.
Add autolinks to connect the router to the broker.
Autolinks connect the router to the broker queue identified by the waypoint address.
If the queue is sharded, add autolinks for each additional broker that hosts a shard.

7.2.5.1. Configuring Waypoint Addresses

A waypoint address identifies a queue on a broker to which you want to route messages. You need to configure the waypoint address on each router that needs to use the address. For example, if a client is connected to Router A to send messages to the broker queue, and another client is connected to Router B to receive those messages, then you would need to configure the waypoint address on both Router A and Router B.

Prerequisites

An incoming connection (listener) to which the clients can connect should be configured. This connection defines how the producers and consumers connect to the router to send and receive messages. For more information, see Adding Incoming Connections.

Procedure

Create waypoint addresses on each router that needs to use the address:
```
address {
    prefix: ADDRESS_PREFIX
    waypoint: yes
}
```
prefix
The address prefix that matches the broker queue to which you want to route messages.
The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1.
waypoint
Set this attribute to yes so that the router handles messages sent to this address as a waypoint.

7.2.5.2. Connecting a Router to the Broker

After you add waypoint addresses to identify the broker queue, you must connect a router to the broker using autolinks.

With autolinks, client traffic is handled on the router, not the broker. Clients attach their links to the router, and then the router uses internal autolinks to connect to the queue on the broker. Therefore, the queue will always have a single producer and a single consumer regardless of how many clients are attached to the router.

If this router is different than the router that is connected to the clients, then add the waypoint address.
Add an outgoing connection to the broker:
```
connector {
    name: NAME
    host: HOST_NAME/ADDRESS
    port: PORT_NUMBER/NAME
    role: route-container
    ...
}
```
name
The name of the connector. Specify a name that describes the broker.
host
Either an IP address (IPv4 or IPv6) or hostname on which the router should connect to the broker.
port
The port number or symbolic service name on which the router should connect to the broker.
role
Specify route-container to indicate that this connection is for an external container (broker).
For information about additional attributes, see Connector in the Configuration Reference.
If you want to send messages to the broker queue, create an outgoing autolink to the broker queue:
```
autoLink {
    addr: ADDRESS
    connection: CONNECTOR_NAME
    dir: out
    ...
}
```
addr
The address of the broker queue. When the autolink is created, it will be attached to this address.
connection | containerID
How the router should connect to the broker. You can specify either an outgoing connection (connection) or the container ID of the broker (containerID).
dir
Set this attribute to out to specify that this autolink can send messages from the router to the broker.
For information about additional attributes, see autoLink in the Configuration Reference.
If you want to receive messages from the broker queue, create an incoming autolink from the broker queue:
```
autoLink {
    addr: ADDRESS
    connection: CONNECTOR_NAME
    dir: in
    ...
}
```
addr
The address of the broker queue. When the autolink is created, it will be attached to this address.
connection | containerID
How the router should connect to the broker. You can specify either an outgoing connection (connection) or the container ID of the broker (containerID).
dir
Set this attribute to in to specify that this autolink can receive messages from the broker to the router.
For information about additional attributes, see autoLink in the Configuration Reference.

7.3. Configuring Link Routing

Link routing provides an alternative strategy for brokered messaging. A link route represents a private messaging path between a sender and a receiver in which the router passes the messages between end points. You can think of a link route as a "virtual connection" or "tunnel" that travels from a sender, through the router network, to a receiver.

With link routing, routing is performed on link-attach frames, which are chained together to form a virtual messaging path that directly connects a sender and receiver. Once a link route is established, the transfer of message deliveries, flow frames, and dispositions is performed across the link route.

7.3.1. Link Route Addresses

A link route address represents a broker queue, topic, or other service. When a client attaches a link route address to a router, the router propagates a link attachment to the broker resource identified by the address.

7.3.2. Link Route Routing Patterns

Routing patterns are not used with link routing, because there is a direct link between the sender and receiver. The router only makes a routing decision when it receives the initial link-attach request frame. Once the link is established, the router passes the messages along the link in a balanced distribution.

7.3.3. Link Route Flow Control

Unlike message routing, with link routing, the sender and receiver handle flow control directly: the receiver grants link credits, which is the number of messages it is able to receive. The router sends them directly to the sender, and then the sender sends the messages based on the credits that the receiver granted.

7.3.4. Creating a Link Route

Link routes establish a link between a sender and a receiver that travels through a router. You can configure inward and outward link routes to enable the router to receive link-attaches from clients and to send them to a particular destination.

With link routing, client traffic is handled on the broker, not the router. Clients have a direct link through the router to a broker’s queue. Therefore, each client is a separate producer or consumer.

Procedure

In the router configuration file, add an outgoing connection to the broker:
```
connector {
    name: NAME
    host: HOST_NAME/ADDRESS
    port: PORT_NUMBER/NAME
    role: route-container
    ...
}
```
name
The name of the connector. You should specify a name that describes the broker.
host
Either an IP address (IPv4 or IPv6) or hostname on which the router should connect to the broker.
port
The port number or symbolic service name on which the router should connect to the broker.
role
Specify route-container to indicate that this connection is for an external container (broker).
For information about additional attributes, see Connector in the Configuration Reference.
If you want clients to send messages on this link route, create an incoming link route:
```
linkRoute {
    prefix: ADDRESS_PREFIX
    connection: CONNECTOR_NAME
    dir: in
    ...
}
```
prefix
The address prefix that matches the broker queue to which you want to send messages. All messages that match this prefix will be distributed along the link route.
The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1. The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1.
connection | containerID
How the router should connect to the broker. You can specify either an outgoing connection (connection) or the container ID of the broker (containerID).
If multiple brokers are connected to the router through this connection, requests for addresses matching the link route’s prefix are balanced across the brokers. Alternatively, if you want to specify a particular broker, use containerID and add the broker’s container ID.
dir
Set this attribute to in to specify that clients can send messages into the router network on this link route.
For information about additional attributes, see linkRoute in the Configuration Reference.
If you want clients to receive messages on this link route, create an outgoing link route:
```
linkRoute {
    prefix: ADDRESS_PREFIX
    connection: CONNECTOR_NAME
    dir: out
    ...
}
```
prefix
The address prefix that matches the broker queue to which you want to receive messages. All messages that match this prefix will be distributed along the link route.
The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1. The prefix can match either an exact address or a segment within an address that is delimited by either a . or / character. For example, the prefix my_address would match the address my_address as well as my_address.1 and my_address/1. However, it would not match my_address1.
connection | containerID
How the router should connect to the broker. You can specify either an outgoing connection (connection) or the container ID of the broker (containerID).
If multiple brokers are connected to the router through this connection, requests for addresses matching the link route’s prefix are balanced across the brokers. Alternatively, if you want to specify a particular broker, use containerID and add the broker’s container ID.
dir
Set this attribute to out to specify that this link route is for receivers.
For information about additional attributes, see linkRoute in the Configuration Reference.

Chapter 7. Routing

7.1. Comparison of Message Routing and Link Routing

7.1.1. When to Use Message Routing

7.1.2. When to Use Link Routing

7.2. Configuring Message Routing

7.2.1. Addresses

7.2.2. Routing Patterns

7.2.3. Message Settlement

7.2.4. Routing Messages Between Clients

7.2.5. Routing Messages Through a Broker Queue

7.2.5.1. Configuring Waypoint Addresses

7.2.5.2. Connecting a Router to the Broker

7.3. Configuring Link Routing

7.3.1. Link Route Addresses

7.3.2. Link Route Routing Patterns

7.3.3. Link Route Flow Control

7.3.4. Creating a Link Route

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links