Chapter 4. Configuring addresses and queues

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add a <wildcard-addresses> section to the configuration, as in the example below.

   <configuration>
     <core>
       ...
       <wildcard-addresses> //
         <enabled>true</enabled> //
         <delimiter>,</delimiter> //
         <any-words>@</any-words> //
         <single-word>$</single-word>
       </wildcard-addresses>
       ...
     </core>
   </configuration>

   enabled

   When set to true, instruct the broker to use your custom settings.

   delimiter

   Provide a custom character to use as the delimiter instead of the default, which is ..

   any-words

   The character provided as the value for any-words is used to mean 'match any sequence of zero or more words' and will replace the default #. Use this character at the end of your expression.

   single-word

   The character provided as the value for single-word is used to mean 'match a single word' and will replaced the default *. Use this character anywhere within your expression.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Wrap an anycast configuration element around the chosen queue element of an address. Ensure that the values of the name attribute for both the address and queue elements are the same. For example:

   <configuration ...>
     <core ...>
       ...
       <address name="my.anycast.destination">
         <anycast>
           <queue name="my.anycast.destination"/>
         </anycast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Wrap an anycast configuration element around the queue elements in the address element. For example:

   <configuration ...>
     <core ...>
       ...
       <address name="my.anycast.destination">
         <anycast>
           <queue name="q1"/>
           <queue name="q2"/>
         </anycast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add the durable configuration element to a chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.durable.address">
         <multicast>
           <queue name="q1">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

   Note

   Because queues are durable by default, including the durable element and setting the value to true is not strictly necessary to create a durable queue. However, explicitly including the element enables you to later change the behavior of the queue to non-durable, if necessary.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add the durable configuration element to each chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.shared.durable.address">
         <multicast>
           <queue name="orders1">
             <durable>true</durable>
           </queue>
           <queue name="orders2">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

   Note

   Because queues are durable by default, including the durable element and setting the value to true is not strictly necessary to create a durable queue. However, explicitly including the element enables you to later change the behavior of the queue to non-durable, if necessary.

3. Add the max-consumers attribute to each chosen queue. Set a value of 1.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.shared.durable.address">
         <multicast>
           <queue name="orders1" max-consumers="1">
             <durable>true</durable>
           </queue>
           <queue name="orders2" max-consumers="1">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add the purge-on-no-consumers attribute to each chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.durable.address">
           <multicast>
               <queue name="orders1" purge-on-no-consumers="true"/>
           </multicast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Configure an address-setting for automatic creation and deletion. The following example uses all of the configuration elements mentioned in the previous table.

   <configuration ...>
    <core ...>
     ...
     <address-settings>
       <address-setting match="activemq.#">
         <auto-create-addresses>true</auto-create-addresses>
         <auto-delete-addresses>true</auto-delete-addresses>
         <auto-create-queues>true</auto-create-queues>
         <auto-delete-queues>true</auto-delete-queues>
         <default-address-routing-type>ANYCAST</default-address-routing-type>
       </address-setting>
     </address-settings>
     ...
    </core>
   </configuration>

   address-setting

   The configuration of the address-setting element is applied to any address or queue that matches the wildcard address activemq.#.

   auto-create-addresses

   When a client requests to connect to an address that does not yet exist, the broker creates the address.

   auto-delete-addresses

   An automatically created address is deleted when it no longer has any queues associated with it.

   auto-create-queues

   When a client requests to connect to a queue that does not yet exist, the broker creates the queue.

   auto-delete-queues

   An automatically created queue is deleted when it no longer has any consumers or messages.

   default-address-routing-type

   If the client does not specify a routing type when connecting, the broker uses ANYCAST when delivering messages to an address. The default value is MULTICAST.

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. For a given queue, add the last-value-key key and specify a custom value. For example:

   <address name="my.address">
       <multicast>
           <queue name="prices1" last-value-key="stock_ticker"/>
       </multicast>
   </address>

3. Alternatively, you can configure a last value queue that uses the default last value key name of _AMQ_LVQ_NAME. To do this, add the last-value key to a given queue. Set the value to true. For example:

   <address name="my.address">
       <multicast>
           <queue name="prices1" last-value="true"/>
       </multicast>
   </address>

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. In the address-setting element, for a matching address, add default-last-value-key. Specify a custom value. For example:

   <address-setting match="lastValue">
      <default-last-value-key>stock_ticker</default-last-value-key>
   </address-setting>

   Based on the preceding configuration, all queues associated with the lastValue address use a last value key of stock_ticker. By default, the value of default-last-value-key is not set.

3. To configure last value queues for a set of addresses, you can specify an address wildcard. For example:

   <address-setting match="lastValue.*">
      <default-last-value-key>stock_ticker</default-last-value-key>
   </address-setting>

4. Alternatively, you can configure all queues associated with an address or set of addresses to use the default last value key name of _AMQ_LVQ_NAME. To do this, add default-last-value-queue instead of default-last-value-key. Set the value to true. For example:

   <address-setting match="lastValue">
      <default-last-value-queue>true</default-last-value-queue>
   </address-setting>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. If you previously configured a queue individually as a last value queue, add the non-destructive key. Set the value to true. For example:

   <address name="my.address">
      <multicast>
         <queue name="orders1" last-value-key="stock_ticker" non-destructive="true" />
      </multicast>
   </address>

3. If you previously configured an address or set of addresses for last value queues, add the default-non-destructive key. Set the value to true. For example:

   <address-setting match="lastValue">
      <default-last-value-key>stock_ticker </default-last-value-key>
      <default-non-destructive>true</default-non-destructive>
   </address-setting>

   Note

   By default, the value of default-non-destructive is false.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. In the core element, set the message-expiry-scan-period to specify how frequently the broker scans for expired messages.

   <configuration ...>
      <core ...>
         ...
         <message-expiry-scan-period>1000</message-expiry-scan-period>
         ...

   Based on the preceding configuration, the broker scans queues for expired messages every 1000 milliseconds.

3. In the address-setting element for a matching address or set of addresses, specify an expiry address. Also, set a message expiration time. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <expiry-delay>10</expiry-delay>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   expiry-address

   Expiry address for the matching address or addresses. In the preceding example, the broker sends expired messages for the stocks address to an expiry address called ExpiryAddress.

   expiry-delay

   Expiration time, in milliseconds, that the broker applies to messages that are using the default expiration time. By default, messages have an expiration time of 0, meaning that they don’t expire. For messages with an expiration time greater than the default, expiry-delay has no effect.

   For example, suppose you set expiry-delay on an address to 10, as shown in the preceding example. If a message with the default expiration time of 0 arrives to a queue at this address, then the broker changes the expiration time of the message from 0 to 10. However, if another message that is using an expiration time of 20 arrives, then its expiration time is unchanged. If you set expiry-delay to -1, this feature is disabled. By default, expiry-delay is set to -1.

4. Alternatively, instead of specifying a value for expiry-delay, you can specify minimum and maximum expiry delay values. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <min-expiry-delay>10</min-expiry-delay>
               <max-expiry-delay>100</max-expiry-delay>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   min-expiry-delay

   Minimum expiration time, in milliseconds, that the broker applies to messages.

   max-expiry-delay

   Maximum expiration time, in milliseconds, that the broker applies to messages.

   The broker applies the values of min-expiry-delay and max-expiry-delay as follows:

   • For a message with the default expiration time of 0, the broker sets the expiration time to the specified value of max-expiry-delay. If you have not specified a value for max-expiry-delay, the broker sets the expiration time to the specified value of min-expiry-delay. If you have not specified a value for min-expiry-delay, the broker does not change the expiration time of the message.
   • For a message with an expiration time above the value of max-expiry-delay, the broker sets the expiration time to the specified value of max-expiry-delay.
   • For a message with an expiration time below the value of min-expiry-delay, the broker sets the expiration time to the specified value of min-expiry-delay.
   • For a message with an expiration between the values of min-expiry-delay and max-expiry-delay, the broker does not change the expiration time of the message.
   • If you specify a value for expiry-delay (that is, other than the default value of -1), this overrides any values that you specify for min-expiry-delay and max-expiry-delay.
   • The default value for both min-expiry-delay and max-expiry-delay is -1 (that is, disabled).

5. In the addresses element of your configuration file, configure the address previously specified for expiry-address. Define a queue at this address. For example:

   <addresses>
       ...
       <address name="ExpiryAddress">
           <anycast>
               <queue name="ExpiryQueue"/>
           </anycast>
       </address>
       ...
   </addresses>

   The preceding example configuration associates an expiry queue, ExpiryQueue, with the expiry address, ExpiryAddress.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Locate the <address-setting> element that you previously added to the configuration file to define an expiry address for a matching address or set of addresses. For example:

   <configuration ...>
   
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

3. In the <address-setting> element, add configuration items that instruct the broker to automatically create expiry resources (that is, addresses and queues) and how to name these resources. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <auto-create-expiry-resources>true</auto-create-expiry-resources>
               <expiry-queue-prefix>EXP.</expiry-queue-prefix>
               <expiry-queue-suffix></expiry-queue-suffix>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   auto-create-expiry-resources

   Specifies whether the broker automatically creates an expiry address and queue to receive expired messages. The default value is false.

   If the parameter value is set to true, the broker automatically creates an <address> element that defines an expiry address and an associated expiry queue. The name value of the automatically-created <address> element matches the name value specified for <expiry-address>.

   The automatically-created expiry queue has the multicast routing type. By default, the broker names the expiry queue to match the address to which expired messages were originally sent, for example, stocks.

   The broker also defines a filter for the expiry queue that uses the _AMQ_ORIG_ADDRESS property. This filter ensures that the expiry queue receives only messages sent to the corresponding original address.

   expiry-queue-prefix

   Prefix that the broker applies to the name of the automatically-created expiry queue. The default value is EXP.

   When you define a prefix value or keep the default value, the name of the expiry queue is a concatenation of the prefix and the original address, for example, EXP.stocks.

   expiry-queue-suffix

   Suffix that the broker applies to the name of an automatically-created expiry queue. The default value is not defined (that is, the broker applies no suffix).

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. In an <address-setting> element that matches your queue name(s), set values for the dead letter address name and the maximum number of delivery attempts. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

   match

   Address to which the broker applies the configuration in this address-setting section. You can specify a wildcard expression for the match attribute of the <address-setting> element. Using a wildcard expression is useful if you want to associate the dead letter settings configured in the <address-setting> element with a matching set of addresses.

   dead-letter-address

   Name of the dead letter address. In this example, the broker moves undelivered messages from the queue exampleQueue to the dead letter address, DLA.

   max-delivery-attempts

   Maximum number of delivery attempts made by the broker before it moves an undelivered message to the configured dead letter address. In this example, the broker moves undelivered messages to the dead letter address after three unsuccessful delivery attempts. The default value is 10. If you want the broker to make an infinite number of redelivery attempts, specify a value of -1.

3. In the addresses section, add an address element for the dead letter address, DLA. To associate a dead letter queue with the dead letter address, specify a name value for queue. For example:

   <configuration ...>
      <core ...>
         ...
         <addresses>
            <address name="DLA">
               <anycast>
                  <queue name="DLQ" />
               </anycast>
            </address>
         ...
         </addresses>
      </core>
   </configuration>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Locate the <address-setting> element that you previously added to define a dead letter address for a matching queue or set of queues. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

3. In the <address-setting> element, add configuration items that instruct the broker to automatically create dead letter resources (that is, addresses and queues) and how to name these resources. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
               <auto-create-dead-letter-resources>true</auto-create-dead-letter-resources>
               <dead-letter-queue-prefix>DLQ.</dead-letter-queue-prefix>
               <dead-letter-queue-suffix></dead-letter-queue-suffix>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

   auto-create-dead-letter-resources

   Specifies whether the broker automatically creates a dead letter address and queue to receive undelivered messages. The default value is false.

   If auto-create-dead-letter-resources is set to true, the broker automatically creates an <address> element that defines a dead letter address and an associated dead letter queue. The name of the automatically-created <address> element matches the name value that you specify for <dead-letter-address>.

   The dead letter queue that the broker defines in the automatically-created <address> element has the multicast routing type . By default, the broker names the dead letter queue to match the original address of the undelivered message, for example, stocks.

   The broker also defines a filter for the dead letter queue that uses the _AMQ_ORIG_ADDRESS property. This filter ensures that the dead letter queue receives only messages sent to the corresponding original address.

   dead-letter-queue-prefix

   Prefix that the broker applies to the name of an automatically-created dead letter queue. The default value is DLQ.

   When you define a prefix value or keep the default value, the name of the dead letter queue is a concatenation of the prefix and the original address, for example, DLQ.stocks.

   dead-letter-queue-suffix

   Suffix that the broker applies to an automatically-created dead letter queue. The default value is not defined (that is, the broker applies no suffix).

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. For a given queue, add the exclusive key. Set the value to true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.address">
         <multicast>
           <queue name="orders1" exclusive="true"/>
         </multicast>
       </address>
     </core>
   </configuration>

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. In the address-setting element, for a matching address, add the default-exclusive-queue key. Set the value to true.

   <address-setting match="myAddress">
       <default-exclusive-queue>true</default-exclusive-queue>
   </address-setting>

   Based on the preceding configuration, all queues associated with the myAddress address are exclusive. By default, the value of default-exclusive-queue is false.

3. To configure exclusive queues for a set of addresses, you can specify an address wildcard. For example:

   <address-setting match="myAddress.*">
       <default-exclusive-queue>true</default-exclusive-queue>
   </address-setting>

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. To define a default ring size for all queues on matching addresses that don’t have an explicit ring size set, specify a value for default-ring-size in the address-setting element. For example:

   <address-settings>
      <address-setting match="ring.#">
         <default-ring-size>3</default-ring-size>
      </address-setting>
   </address-settings>

   The default-ring-size parameter is especially useful for defining the default size of auto-created queues. The default value of default-ring-size is -1 (that is, no size limit).

3. To define a ring size on a specific queue, add the ring-size key to the queue element. Specify a value. For example:

   <addresses>
      <address name="myRing">
         <anycast>
            <queue name="myRing" ring-size="5" />
         </anycast>
      </address>
   </addresses>

1. A producer sends three messages to a ring queue configured with ring-size="3".

2. All messages are immediately dispatched to a consumer.

   At this point, messageCount= 3 and deliveringCount= 3.

3. The producer sends another message to the queue. The message is then dispatched to the consumer.

   Now, messageCount = 4 and deliveringCount = 4. The message count of 4 is greater than the configured ring size of 3. However, the broker is obliged to allow this situation because it cannot remove the in-delivery messages from the queue.

4. Now, suppose that the consumer is closed without acknowledging any of the messages.

   In this case, the four in-delivery, unacknowledged messages are canceled back to the broker and added to the head of the queue in the reverse order from which they were consumed. This action puts the queue over its configured ring size. Because a ring queue prefers messages at the tail of the queue over messages at the head, the queue discards the first message sent by the producer, because this was the last message added back to the head of the queue. Transaction or core session rollbacks are treated in the same way.

1. At 12:00, a producer sends a message, A, to a ring queue configured with ring-size="3". The message is scheduled for 12:05.

   At this point, messageCount= 1 and scheduledCount= 1.

2. At 12:01, producer sends message B to the same ring queue.

   Now, messageCount= 2 and scheduledCount= 1.

3. At 12:02, producer sends message C to the same ring queue.

   Now, messageCount= 3 and scheduledCount= 1.

4. At 12:03, producer sends message D to the same ring queue.

   Now, messageCount= 4 and scheduledCount= 1.

   The message count for the queue is now 4, one greater than the configured ring size of 3. However, the scheduled message is not technically on the queue yet (that is, it is on the broker and scheduled to be put on the queue). At the scheduled delivery time of 12:05, the broker puts the message on the head of the queue. However, since the ring queue has already reached its configured size, the scheduled message A is immediately removed.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add a new <federations> element that includes a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   Name of the federation configuration. In this example, the name corresponds to the name of the local broker.

   user

   Shared user name for connection to the upstream brokers.

   password

   Shared password for connection to the upstream brokers.

   Note

   If user and password credentials differ for remote brokers, you can separately specify credentials for those brokers when you add them to the configuration. This is described later in this procedure.

3. Within the federation element, add an <address-policy> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
           </address-policy>
   
       </federation>
   </federations>

   name

   Name of the address policy. All address policies that are configured on the broker must have unique names.

   auto-delete

   During address federation, the local broker dynamically creates a durable queue at the remote address. The value of the auto-delete property specifies whether the remote queue should be deleted once the local broker disconnects and the values of the auto-delete-delay and auto-delete-message-count properties have also been reached. This is a useful option if you want to automate the cleanup of dynamically-created queues. It is also a useful option if you want to prevent a buildup of messages on a remote broker if the local broker is disconnected for a long time. However, you might set this option to false if you want messages to always remain queued for the local broker while it is disconnected, avoiding message loss on the local broker.

   auto-delete-delay

   After the local broker has disconnected, the value of this property specifies the amount of time, in milliseconds, before dynamically-created remote queues are eligible to be automatically deleted.

   auto-delete-message-count

   After the local broker has been disconnected, the value of this property specifies the maximum number of messages that can still be in a dynamically-created remote queue before that queue is eligible to be automatically deleted.

   enable-divert-bindings

   Setting this property to true enables divert bindings to be listened-to for demand. If there is a divert binding with an address that matches the included addresses for the address policy, then any queue bindings that match the forwarding address of the divert will create demand. The default value is false.

   max-hops

   Maximum number of hops that a message can make during federation. Particular topologies require specific values for this property. To learn more about these requirements, see Section 4.22.2, “Common topologies for address federation”.

   transformer-ref

   Name of a transformer configuration. You might add a transformer configuration if you want to transform messages during federated message transmission. Transformer configuration is described later in this procedure.

4. Within the <address-policy> element, add address-matching patterns to include and exclude addresses from the address policy. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
   </federations>

   include

   The value of the address-match property of this element specifies addresses to include in the address policy. You can specify an exact address, for example, queue.bbc.new or queue.usatoday. Or, you can use a wildcard expression to specify a matching set of addresses. In the preceding example, the address policy also includes all address names that start with the string queue.news.

   exclude

   The value of the address-match property of this element specifies addresses to exclude from the address policy. You can specify an exact address name or use a wildcard expression to specify a matching set of addresses. In the preceding example, the address policy excludes all address names that start with the string queue.news.sport.

5. (Optional) Within the federation element, add a transformer element to reference a custom transformer implementation. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   Name of the transformer configuration. This name must be unique on the local broker. This is the name that you specify as a value for the transformer-ref property of the address policy.

   class-name

   Name of a user-defined class that implements the org.apache.activemq.artemis.core.server.transformer.Transformer interface.

   The transformer’s transform() method is invoked with the message before the message is transmitted. This enables you to transform the message header or body before it is federated.

   property

   Used to hold key-value pairs for specific transformer configuration.

6. Within the federation element, add one or more upstream elements. Each upstream element defines a connection to a remote broker and the policies to apply to that connection. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   Contains a list of connector-ref elements that reference connector elements that are defined elsewhere in the broker.xml configuration file of the local broker. A connector defines what transport (TCP, SSL, HTTP, and so on) and server connection parameters (host, port, and so on) to use for outgoing connections. The next step of this procedure shows how to add the connectors that are referenced in the static-connectors element.

   policy-ref

   Name of the address policy configured on the downstream broker that is applied to the upstream broker.

   The additional options that you can specify for an upstream element are described below:

   name

   Name of the upstream broker configuration. In this example, the names correspond to upstream brokers called eu-east-1 and eu-west-1.

   user

   User name to use when creating the connection to the upstream broker. If not specified, the shared user name that is specified in the configuration of the federation element is used.

   password

   Password to use when creating the connection to the upstream broker. If not specified, the shared password that is specified in the configuration of the federation element is used.

   call-failover-timeout

   Similar to call-timeout, but used when a call is made during a failover attempt. The default value is -1, which means that the timeout is disabled.

   call-timeout

   Time, in milliseconds, that a federation connection waits for a reply from a remote broker when it transmits a packet that is a blocking call. If this time elapses, the connection throws an exception. The default value is 30000.

   check-period

   Period, in milliseconds, between consecutive “keep-alive” messages that the local broker sends to a remote broker to check the health of the federation connection. If the federation connection is healthy, the remote broker responds to each keep-alive message. If the connection is unhealthy, when the downstream broker fails to receive a response from the upstream broker, a mechanism called a circuit breaker is used to block federated consumers. See the description of the circuit-breaker-timeout parameter for more information. The default value of the check-period parameter is 30000.

   circuit-breaker-timeout

   A single connection between a downstream and upstream broker might be shared by many federated queue and address consumers. In the event that the connection between the brokers is lost, each federated consumer might try to reconnect at the same time. To avoid this, a mechanism called a circuit breaker blocks the consumers. When the specified timeout value elapses, the circuit breaker re-tries the connection. If successful, consumers are unblocked. Otherwise, the circuit breaker is applied again.

   connection-ttl

   Time, in milliseconds, that a federation connection stays alive if it stops receiving messages from the remote broker. The default value is 60000.

   discovery-group-ref

   As an alternative to defining static connectors for connections to upstream brokers, this element can be used to specify a discovery group that is already configured elsewhere in the broker.xml configuration file. Specifically, you specify an existing discovery group as a value for the discovery-group-name property of this element. For more information about discovery groups, see Section 14.1.6, “Broker discovery methods”.

   ha

   Specifies whether high availability is enabled for the connection to the upstream broker. If the value of this parameter is set to true, the local broker can connect to any available broker in an upstream cluster and automatically fails over to a backup broker if the live upstream broker shuts down. The default value is false.

   initial-connect-attempts

   Number of initial attempts that the downstream broker will make to connect to the upstream broker. If this value is reached without a connection being established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   max-retry-interval

   Maximum time, in milliseconds, between subsequent reconnection attempts when connection to the remote broker fails. The default value is 2000.

   reconnect-attempts

   Number of times that the downstream broker will try to reconnect to the upstream broker if the connection fails. If this value is reached without a connection being re-established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   retry-interval

   Period, in milliseconds, between subsequent reconnection attempts, if connection to the remote broker has failed. The default value is 500.

   retry-interval-multiplier

   Multiplying factor that is applied to the value of the retry-interval parameter. The default value is 1.

   share-connection

   If there is both a downstream and upstream connection configured for the same broker, then the same connection will be shared, as long as both of the downstream and upstream configurations set the value of this parameter to true. The default value is false.

7. On the local broker, add connectors to the remote brokers. These are the connectors referenced in the static-connectors elements of your federated address configuration. For example:

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>

Procedure

1. On the local broker, open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add a <federations> element that includes a <federation> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
       </federation>
   </federations>

3. Add an address policy configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
     ...
   </federations>

4. If you want to transform messages before transmission, add a transformer configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. Add a downstream element for each remote broker. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
                   <static-connectors>
                       <connector-ref>eu-east-connector1</connector-ref>
                   </static-connectors>
                   <upstream-connector-ref>netty-connector</upstream-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
                   <static-connectors>
                       <connector-ref>eu-west-connector1</connector-ref>
                   </static-connectors>
                   <upstream-connector-ref>netty-connector</upstream-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   As shown in the preceding configuration, the remote brokers are now considered to be downstream of the local broker. The downstream brokers use the connection information in the configuration to connect back to the local (that is, upstream) broker.

6. On the local broker, add connectors and acceptors used by the local and remote brokers to establish the federation connection. For example:

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   Connector configuration that the local broker sends to the remote broker. The remote broker use this configuration to connect back to the local broker.

   connector name="eu-west-1-connector", connector name="eu-east-1-connector"

   Connectors to remote brokers. The local broker uses these connectors to connect to the remote brokers and share the configuration that the remote brokers need to connect back to the local broker.

   acceptor name="netty-acceptor"

   Acceptor on the local broker that corresponds to the connector used by the remote broker to connect back to the local broker.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Within a new <federations> element, add a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   Name of the federation configuration. In this example, the name corresponds to the name of the downstream broker.

   user

   Shared user name for connection to the upstream brokers.

   password

   Shared password for connection to the upstream brokers.

   Note
   • If user and password credentials differ for upstream brokers, you can separately specify credentials for those brokers when you add them to the configuration. This is described later in this procedure.

3. Within the federation element, add a <queue-policy> element. Specify values for properties of the <queue-policy> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
           </queue-policy>
   
       </federation>
   </federations>

   name

   Name of the queue policy. All queue policies that are configured on the broker must have unique names.

   include-federated

   When the value of this property is set to false, the configuration does not re-federate an already-federated consumer (that is, a consumer on a federated queue). This avoids a situation where in a symmetric or closed-loop topology, there are no non-federated consumers, and messages flow endlessly around the system.

   You might set the value of this property to true if you do not have a closed-loop topology. For example, suppose that you have a chain of three brokers, BrokerA, BrokerB, and BrokerC, with a producer at BrokerA and a consumer at BrokerC. In this case, you would want BrokerB to re-federate the consumer to BrokerA.

   priority-adjustment

   When a consumer connects to a queue, its priority is used when the upstream (that is federated) consumer is created. The priority of the federated consumer is adjusted by the value of the priority-adjustment property. The default value of this property is -1, which ensures that the local consumer get prioritized over the federated consumer during load balancing. However, you can change the value of the priority adjustment as needed.

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

2. Add a <federations> element that includes a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

3. Add a queue policy configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
     ...
   </federations>

4. If you want to transform messages before transmission, add a transformer configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. Add a downstream element for each remote broker. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <upstream-connector-ref>netty-connector</upstream-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <upstream-connector-ref>netty-connector</upstream-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   As shown in the preceding configuration, the remote brokers are now considered to be downstream of the local broker. The downstream brokers use the connection information in the configuration to connect back to the local (that is, upstream) broker.

6. On the local broker, add connectors and acceptors used by the local and remote brokers to establish the federation connection. For example:

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   Connector configuration that the local broker sends to the remote broker. The remote broker use this configuration to connect back to the local broker.

   connector name="eu-west-1-connector" , connector name="eu-east-1-connector"

   Connectors to remote brokers. The local broker uses these connectors to connect to the remote brokers and share the configuration that the remote brokers need to connect back to the local broker.

   acceptor name="netty-acceptor"

   Acceptor on the local broker that corresponds to the connector used by the remote broker to connect back to the local broker.