Configuring Addresses and Queues via Address Settings

There are some attributes that are defined against an address wildcard rather than a specific address/queue. Here an example of an address-setting entry that would be found in the broker.xml file.

  1. <address-settings>
  2.    <address-setting match="order.foo">
  3.       <dead-letter-address>DLA</dead-letter-address>
  4.       <auto-create-dead-letter-resources>false</auto-create-dead-letter-resources>
  5.       <dead-letter-queue-prefix>DLQ.</dead-letter-queue-prefix>
  6.       <dead-letter-queue-suffix></dead-letter-queue-suffix>
  7.       <expiry-address>ExpiryQueue</expiry-address>
  8.       <auto-create-expiry-resources>false</auto-create-expiry-resources>
  9.       <expiry-queue-prefix>EXP.</expiry-queue-prefix>
  10.       <expiry-queue-suffix></expiry-queue-suffix>
  11.       <expiry-delay>123</expiry-delay>
  12.       <redelivery-delay>5000</redelivery-delay>
  13.       <redelivery-delay-multiplier>1.0</redelivery-delay-multiplier>
  14.       <redelivery-collision-avoidance-factor>0.0</redelivery-collision-avoidance-factor>
  15.       <max-redelivery-delay>10000</max-redelivery-delay>
  16.       <max-delivery-attempts>3</max-delivery-attempts>
  17.       <max-size-bytes>100000</max-size-bytes>
  18.       <max-size-messages>1000</max-size-messages>
  19.       <max-size-bytes-reject-threshold>-1</max-size-bytes-reject-threshold>
  20.       <page-size-bytes>20000</page-size-bytes>
  21.       <address-full-policy>PAGE</address-full-policy>
  22.       <message-counter-history-day-limit></message-counter-history-day-limit>
  23.       <last-value-queue>true</last-value-queue> <!-- deprecated! see default-last-value-queue -->
  24.       <default-last-value-queue>false</default-last-value-queue>
  25.       <default-non-destructive>false</default-non-destructive>
  26.       <default-exclusive-queue>false</default-exclusive-queue>
  27.       <default-consumers-before-dispatch>0</default-consumers-before-dispatch>
  28.       <default-delay-before-dispatch>-1</default-delay-before-dispatch>
  29.       <redistribution-delay>0</redistribution-delay>
  30.       <send-to-dla-on-no-route>false</send-to-dla-on-no-route>
  31.       <slow-consumer-threshold>-1</slow-consumer-threshold>
  32.       <slow-consumer-threshold-measurement-unit>MESSAGES_PER_SECOND</slow-consumer-threshold-measurement-unit>
  33.       <slow-consumer-policy>NOTIFY</slow-consumer-policy>
  34.       <slow-consumer-check-period>5</slow-consumer-check-period>
  35.       <auto-create-queues>true</auto-create-queues>
  36.       <auto-delete-queues>true</auto-delete-queues>
  37.       <auto-delete-created-queues>false</auto-delete-created-queues>
  38.       <auto-delete-queues-delay>0</auto-delete-queues-delay>
  39.       <auto-delete-queues-message-count>0</auto-delete-queues-message-count>
  40.       <config-delete-queues>OFF</config-delete-queues>
  41.       <config-delete-diverts>OFF</config-delete-diverts>
  42.       <auto-create-addresses>true</auto-create-addresses>
  43.       <auto-delete-addresses>true</auto-delete-addresses>
  44.       <auto-delete-addresses-delay>0</auto-delete-addresses-delay>
  45.       <config-delete-addresses>OFF</config-delete-addresses>
  46.       <management-browse-page-size>200</management-browse-page-size>
  47.       <management-message-attribute-size-limit>256</management-message-attribute-size-limit>
  48.       <default-purge-on-no-consumers>false</default-purge-on-no-consumers>
  49.       <default-max-consumers>-1</default-max-consumers>
  50.       <default-queue-routing-type></default-queue-routing-type>
  51.       <default-address-routing-type></default-address-routing-type>
  52.       <default-ring-size>-1</default-ring-size>
  53.       <retroactive-message-count>0</retroactive-message-count>
  54.       <enable-metrics>true</enable-metrics>
  55.       <enable-ingress-timestamp>false</enable-ingress-timestamp>
  56.    </address-setting>
  57. </address-settings>

The idea with address settings, is you can provide a block of settings which will be applied against any addresses that match the string in the match attribute. In the above example the settings would only be applied to the address “order.foo” address but you can also use wildcards to apply settings.

For example, if you used the match string queue.# the settings would be applied to all addresses which start with queue.

Address settings are hierarchical. Therefore, if more than one address-setting would match then the settings are applied in order of their specificity with the more specific match taking priority. A match on the any-words delimiter (#) is considered less specific than a match without it. A match with a single word delimiter * is considered less specific than a match on an exact queue name. In this way settings can be “layered” so that configuration details don’t need to be repeated.

The meaning of the specific settings are explained fully throughout the user manual, however here is a brief description with a link to the appropriate chapter if available.

dead-letter-address is the address to which messages are sent when they exceed max-delivery-attempts. If no address is defined here then such messages will simply be discarded. Read more about undelivered messages.

auto-create-dead-letter-resources determines whether or not the broker will automatically create the defined dead-letter-address and a corresponding dead-letter queue when a message is undeliverable. Read more in the chapter about undelivered messages.

dead-letter-queue-prefix defines the prefix used for automatically created dead-letter queues. Read more in the chapter about undelivered messages.

dead-letter-queue-suffix defines the suffix used for automatically created dead-letter queues. Read more in the chapter about undelivered messages.

expiry-address defines where to send a message that has expired. If no address is defined here then such messages will simply be discarded. Read more about message expiry.

auto-create-expiry-resources determines whether or not the broker will automatically create the defined expiry-address and a corresponding expiry queue when a message expired. Read more in the chapter about undelivered messages.

expiry-queue-prefix defines the prefix used for automatically created expiry queues. Read more in the chapter about message expiry.

expiry-queue-suffix defines the suffix used for automatically created expiry queues. Read more in the chapter about message expiry.

expiry-delay defines the expiration time that will be used for messages which are using the default expiration time (i.e. 0). For example, if expiry-delay is set to “10” and a message which is using the default expiration time (i.e. 0) arrives then its expiration time of “0” will be changed to “10.” However, if a message which is using an expiration time of “20” arrives then its expiration time will remain unchanged. Setting expiry-delay to “-1” will disable this feature. The default is “-1”. Read more about message expiry.

max-delivery-attempts defines how many time a cancelled message can be redelivered before sending to the dead-letter-address. Read more about undelivered messages.

redelivery-delay defines how long to wait before attempting redelivery of a cancelled message. Default is 0. Read more about undelivered messages.

redelivery-delay-multiplier defines the number by which the redelivery-delay will be multiplied on each subsequent redelivery attempt. Default is 1.0. Read more about undelivered messages.

redelivery-collision-avoidance-factor defines an additional factor used to calculate an adjustment to the redelivery-delay (up or down). Default is 0.0. Valid values are between 0.0 and 1.0. Read more about undelivered messages.

max-size-bytes, max-size-messages, page-size-bytes, max-read-page-messages & max-read-page-bytes are used to configure paging on an address. This is explained here.

max-size-bytes-reject-threshold is used with the address full BLOCK policy, the maximum size (in bytes) an address can reach before messages start getting rejected. Works in combination with max-size-bytes for AMQP clients only. Default is -1 (i.e. no limit).

address-full-policy. This attribute can have one of the following values: PAGE, DROP, FAIL or BLOCK and determines what happens when an address where max-size-bytes is specified becomes full. The default value is PAGE. If the value is PAGE then further messages will be paged to disk. If the value is DROP then further messages will be silently dropped. If the value is FAIL then further messages will be dropped and an exception will be thrown on the client-side. If the value is BLOCK then client message producers will block when they try and send further messages. See the Flow Control and Paging chapters for more info.

message-counter-history-day-limit is the number of days to keep message counter history for this address assuming that message-counter-enabled is true. Default is 0.

default-last-value-queue defines whether a queue only uses last values or not. Default is false. This value can be overridden at the queue level using the last-value boolean. Read more about last value queues.

default-exclusive-queue defines whether a queue will serve only a single consumer. Default is false. This value can be overridden at the queue level using the exclusive boolean. Read more about exclusive queues.

default-consumers-before-dispatch defines the number of consumers needed on a queue bound to the matching address before messages will be dispatched to those consumers. Default is 0. This value can be overridden at the queue level using the consumers-before-dispatch boolean. This behavior can be tuned using delay-before-dispatch on the queue itself or by using the default-delay-before-dispatch address-setting.

default-delay-before-dispatch defines the number of milliseconds the broker will wait for the configured number of consumers to connect to the matching queue before it will begin to dispatch messages. Default is -1 (wait forever).

redistribution-delay defines how long to wait when the last consumer is closed on a queue before redistributing any messages. Read more about clusters.

send-to-dla-on-no-route. If a message is sent to an address, but the server does not route it to any queues (e.g. there might be no queues bound to that address, or none of the queues have filters that match) then normally that message would be discarded. However, if this parameter is true then such a message will instead be sent to the dead-letter-address (DLA) for that address, if it exists. Default is false.

slow-consumer-threshold. The minimum rate of message consumption allowed before a consumer is considered “slow.” Measured in units specified by the slow-consumer-threshold-measurement-unit configuration option. Default is -1 (i.e. disabled); any other value must be greater than 0 to ensure a queue has messages, and it is the actual consumer that is slow. A value of 0 will allow a consumer with no messages pending to be considered slow. Read more about slow consumers.

slow-consumer-threshold-measurement-unit. The units used to measure the slow-consumer-threshold. Valid options are:

  • MESSAGES_PER_SECOND
  • MESSAGES_PER_MINUTE
  • MESSAGES_PER_HOUR
  • MESSAGES_PER_DAY

If no unit is specified the default MESSAGES_PER_SECOND will be used. Read more about slow consumers.

slow-consumer-policy. What should happen when a slow consumer is detected. KILL will kill the consumer’s connection (which will obviously impact any other client threads using that same connection). NOTIFY will send a CONSUMER_SLOW management notification which an application could receive and take action with. Read more about slow consumers.

slow-consumer-check-period. How often to check for slow consumers on a particular queue. Measured in seconds. Default is 5.

  • Note: This should be at least 2x the maximum time it takes a consumer to process 1 message. For example, if the slow-consumer-threshold is set to 1 and the slow-consumer-threshold-measurement-unit is set to MESSAGES_PER_MINUTE then this should be set to at least 2 x 60s i.e. 120s. Read more about slow consumers.

auto-create-queues. Whether or not the broker should automatically create a queue when a message is sent or a consumer tries to connect to a queue whose name fits the address match. Queues which are auto-created are durable, non-temporary, and non-transient. Default is true. Note: automatic queue creation does not work for the core client. The core API is a low-level API and is not meant to have such automation.

auto-delete-queues. Whether or not the broker should automatically delete auto-created queues when they have both 0 consumers and the message count is less than or equal to auto-delete-queues-message-count. Default is true.

auto-delete-created-queues. Whether or not the broker should automatically delete created queues when they have both 0 consumers and the message count is less than or equal to auto-delete-queues-message-count. Default is false.

auto-delete-queues-delay. How long to wait (in milliseconds) before deleting auto-created queues after the queue has 0 consumers and the message count is less than or equal to auto-delete-queues-message-count. Default is 0 (delete immediately). The broker’s address-queue-scan-period controls how often (in milliseconds) queues are scanned for potential deletion. Use -1 to disable scanning. The default scan value is 30000.

auto-delete-queues-message-count. The message count that the queue must be less than or equal to before deleting auto-created queues. To disable message count check -1 can be set. Default is 0 (empty queue).

Note: the above auto-delete address settings can also be configured individually at the queue level when a client auto creates the queue.

For Core API it is exposed in createQueue methods.

For Core JMS you can set it using the destination queue attributes my.destination?auto-delete=true&auto-delete-delay=120000&auto-delete-message-count=-1

config-delete-queues. How the broker should handle queues deleted on config reload, by delete policy: OFF or FORCE. Default is OFF. Read more about configuration reload.

config-delete-diverts. How the broker should handle diverts deleted on config reload, by delete policy: OFF or FORCE. Default is OFF. Read more about configuration reload. auto-create-addresses. Whether or not the broker should automatically create an address when a message is sent to or a consumer tries to consume from a queue which is mapped to an address whose name fits the address match. Default is true. Note: automatic address creation does not work for the core client. The core API is a low-level API and is not meant to have such automation.

auto-delete-addresses. Whether or not the broker should automatically delete auto-created addresses once the address no longer has any queues. Default is true.

auto-delete-addresses-delay. How long to wait (in milliseconds) before deleting auto-created addresses after they no longer have any queues. Default is 0 (delete immediately). The broker’s address-queue-scan-period controls how often (in milliseconds) addresses are scanned for potential deletion. Use -1 to disable scanning. The default scan value is 30000.

config-delete-addresses. How the broker should handle addresses deleted on config reload, by delete policy: OFF or FORCE. Default is OFF. Read more about configuration reload.

management-browse-page-size is the number of messages a management resource can browse. This is relevant for the browse, list and count-with-filter management methods exposed on the queue control. Default is 200.

management-message-attribute-size-limit is the number of bytes collected from the message for browse. This is relevant for the browse and list management methods exposed on the queue control. Message attributes longer than this value appear truncated. Default is 256. Use -1 to switch this limit off. Note that memory needs to be allocated for all messages that are visible at a given moment. Setting this value too high may impact the browser stability due to the large amount of memory that may be required to browse through many messages.

default-purge-on-no-consumers defines a queue’s default purge-on-no-consumers setting if none is provided on the queue itself. Default is false. This value can be overridden at the queue level using the purge-on-no-consumers boolean. Read more about this functionality.

default-max-consumers defines a queue’s default max-consumers setting if none is provided on the queue itself. Default is -1 (i.e. no limit). This value can be overridden at the queue level using the max-consumers boolean. Read more about this functionality.

default-queue-routing-type defines the routing-type for an auto-created queue if the broker is unable to determine the routing-type based on the client and/or protocol semantics. Default is MULTICAST. Read more about routing types.

default-address-routing-type defines the routing-type for an auto-created address if the broker is unable to determine the routing-type based on the client and/or protocol semantics. Default is MULTICAST. Read more about routing types.

default-consumer-window-size defines the default consumerWindowSize value for a CORE protocol consumer, if not defined the default will be set to 1 MiB (1024 * 1024 bytes). The consumer will use this value as the window size if the value is not set on the client. Read more about flow control.

default-ring-size defines the default ring-size value for any matching queue which doesn’t have ring-size explicitly defined. If not defined the default will be set to -1. Read more about ring queues.

retroactive-message-count defines the number of messages to preserve for future queues created on the matching address. Defaults to 0. Read more about retroactive addresses.

enable-metrics determines whether or not metrics will be published to any configured metrics plugin for the matching address. Default is true. Read more about metrics.

enable-ingress-timestamp determines whether or not the broker will add its time to messages sent to the matching address. When true the exact behavior will depend on the specific protocol in use. For AMQP messages the broker will add a long message annotation named x-opt-ingress-time. For core messages (used by the core and OpenWire protocols) the broker will add a long property named _AMQ_INGRESS_TIMESTAMP. For STOMP messages the broker will add a frame header named ingress-timestamp. The value will be the number of milliseconds since the epoch. Default is false.