Chapter 6. Address Settings

The messaging-activemq subsystem has several configurable options which control aspects of how and when a message is delivered, how many attempts should be made, and when the message expires. These configuration options all exist within the <address-setting> configuration element. You can configure JBoss EAP to apply a single <address-setting> to multiple destinations by using a wildcard syntax.

6.1. Wildcard Syntax

Wildcards can be used to match similar addresses with a single statement, much like how many systems use the asterisk character, *, to match multiple files or strings with a single query. The following table lists the special characters that can be used to define an <address-setting>.

Table 6.1. JMS Wildcard Syntax

CharacterDescription

. (a single period)

Denotes the space between words in a wildcard expression.

# (a pound or hash symbol)

Matches any sequence of zero or more words.

* (an asterisk)

Matches a single word.

The examples in the table below illustrate how wildcards are used to match a set of addresses.

Table 6.2. JMS Wildcard Examples

ExampleDescription

news.europe.#

Matches news.europe, news.europe.sport, news.europe.politics.fr, but not news.usa or europe.

news.*

Matches news.europe and news.usa, but not news.europe.sport.

news.*.sport

Matches news.europe.sport and news.usa.sport, but not news.europe.fr.sport.

6.2. Default address-setting

Out of the box, JBoss EAP includes a single address-setting element as part of the configuration for the messaging-activemq subsystem:

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
  <server name="default">
      ...
      <address-setting
        name="#"
        dead-letter-address="jms.queue.DLQ"
        expiry-address="jms.queue.ExpiryQueue"
        max-size-bytes="10485760"
        page-size-bytes="2097152"
        message-counter-history-day-limit="10" />
      ...
  </server>
</subsystem>
Note

The use of a single # for the name attribute makes this default address-setting the configuration to be used for all destinations since # matches any address. You can continue to apply this catch-all configuration to all of your addresses, or you can add a new address-setting for each address or group of addresses that requires its own configuration set.

Configuring Address Settings Using the Management CLI

Configuring address settings is done by using either the management CLI or the management console, but the management CLI exposes more of the configuration attributes for editing. See Address Setting Attributes in the appendix of this guide for the full list of attributes.

Add a new address-setting

Use the add operation to create a new address setting if required. You can run this command from the root of the management CLI session, which in the following examples creates a new pattern named . You can include configuration attributes for the address-setting. Below, a new address-setting matching news.europe.# is created with its dead-letter-address attribute set to the queue DLQ.news, which was created beforehand. Examples for both a standalone server and a managed server domain using the full profile are shown respectively.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:add(dead-letter-address=DLQ.news)
/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:add(dead-letter-address=DLQ.news)

Edit an address-setting attribute

Use the write-attribute operation to write a new value to an attribute. You can use tab completion to help complete the command string as you type, as well as to expose the available attributes. The following example updates the max-delivery-attempts value to 10.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:write-attribute(name=max-delivery-attempts,value=10)
/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:write-attribute(name=max-delivery-attempts,value=10)

Read address-setting Attributes

Confirm the values are changed by running the read-resource operation with the include-runtime=true parameter to expose all current values active in the server model.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:read-resource(include-runtime=true)
/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:read-resource(include-runtime=true)

Configuring Address Settings Using the Management Console

You can use the management console to create and review address settings by following these steps:

  1. Log in to the management console.
  2. Select the Configuration tab at the top of the screen. When running a managed domain, select the profile to update.
  3. Select Messaging (ActiveMQ)Server.
  4. Select a messaging server. In the default configuration, only one server, called default, is shown.
  5. Select Destinations and click View.
  6. Select the Address Setting tab to configure address settings.

Remember that when adding a new pattern, for example news.europe.#, the Pattern field refers to the name attribute of the address-setting element. You enter this value when using the management CLI to read or write attributes.

You can edit only the dead-letter-address, expiry-address, redelivery-delay, and max-delivery-attempts attributes while using the management console. Other attributes must be configured using the management CLI.

6.3. Last-value Queues

Last-value queues are special queues which discard any messages when a newer message with the same value for a well-defined last-value property is put in the queue. In other words, a last-value queue only retains the last value. A typical application of a last-value queue might involve stock prices, where you are interested only in the latest price of a particular stock.

Important

Last-value queues will not work as expected if the queue has paging enabled. Be sure to disable paging before using a last-value queue.

Configuring Last-value Queues

Last-value queues are defined within the address-setting configuration element:

<address-setting name="jms.queue.lastValueQueue" last-value-queue="true" />

Use the management CLI to read the value of last-value-queue for a given address-setting:

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#:read-attribute(name=last-value-queue)
{
    "outcome" => "success",
    "result" => false
}

The accepted values for last-value-queue are true or false. Use the management CLI to set either value, like so:

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#:write-attribute(name=last-value-queue,value=true)

/subsystem=messaging-activemq/server=default/address-setting=news.asia.#:write-attribute(name=last-value-queue,value=false)

Using the Last-value Property

The property name used to identify the last value is _AMQ_LVQ_NAME (or the constant Message.HDR_LAST_VALUE_NAME from the Core API). Let the following Java code illustrate how to use the last-value property.

  • First, the publisher sends a message to the last-value queue
TextMessage message = session.createTextMessage("My 1st message with the last-value property set");
message.setStringProperty("_AMQ_LVQ_NAME", "MY_MESSAGE");
producer.send(message);
  • Then it sends another message to the queue using the same last-value
message = session.createTextMessage("My 2nd message with the last-value property set");
message.setStringProperty("_AMQ_LVQ_NAME", "MY_MESSAGE");
producer.send(message);
  • Next, the consumer receives the message with the last-value
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());

In the above example the client’s output would be "My 2nd message with the last-value property set" since both messages set _AMQ_LVQ_NAME to "MY_MESSAGE", and the second message was received in the queue after the first.