| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Address Settings</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Address Settings</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#literal-matches">1. Literal Matches</a> |
| <ul class="sectlevel2"> |
| <li><a href="#configuring-a-literal-match">1.1. Configuring a Literal Match</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>With address settings you can provide a block of settings which will be applied to any addresses that match the string in the <code>match</code> attribute. |
| In the below example the settings would only be applied to the address <code>order.foo</code> address, but it is also possible to use <a href="wildcard-syntax.html#wildcard-syntax">wildcards</a> to apply settings.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, if you used the <code>match</code> string <code>queue.#</code> the settings would be applied to <em>all</em> addresses which start with <code>queue.</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Address settings are <strong>hierarchical</strong>. |
| Therefore, if more than one <code>address-setting</code> 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 (<code>#</code> by default) is considered less specific than a match without it. |
| A match with a single word delimiter (<code>*</code> by default) 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Address setting matches can also be "literal" which can be used to match wildcards literally, for further details see <a href="#literal-matches">literal matches</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here an example of an <code>address-setting</code> entry that might be found in the <code>broker.xml</code> file.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><address-settings></span> |
| <span class="nt"><address-setting</span> <span class="na">match=</span><span class="s">"order.foo"</span><span class="nt">></span> |
| <span class="nt"><dead-letter-address></span>DLA<span class="nt"></dead-letter-address></span> |
| <span class="nt"><auto-create-dead-letter-resources></span>false<span class="nt"></auto-create-dead-letter-resources></span> |
| <span class="nt"><dead-letter-queue-prefix></dead-letter-queue-prefix></span> |
| <span class="nt"><dead-letter-queue-suffix></dead-letter-queue-suffix></span> |
| <span class="nt"><expiry-address></span>ExpiryQueue<span class="nt"></expiry-address></span> |
| <span class="nt"><auto-create-expiry-resources></span>false<span class="nt"></auto-create-expiry-resources></span> |
| <span class="nt"><expiry-queue-prefix></expiry-queue-prefix></span> |
| <span class="nt"><expiry-queue-suffix></expiry-queue-suffix></span> |
| <span class="nt"><expiry-delay></span>123<span class="nt"></expiry-delay></span> |
| <span class="nt"><redelivery-delay></span>5000<span class="nt"></redelivery-delay></span> |
| <span class="nt"><redelivery-delay-multiplier></span>1.0<span class="nt"></redelivery-delay-multiplier></span> |
| <span class="nt"><redelivery-collision-avoidance-factor></span>0.0<span class="nt"></redelivery-collision-avoidance-factor></span> |
| <span class="nt"><max-redelivery-delay></span>10000<span class="nt"></max-redelivery-delay></span> |
| <span class="nt"><max-delivery-attempts></span>3<span class="nt"></max-delivery-attempts></span> |
| <span class="nt"><max-size-bytes></span>-1<span class="nt"></max-size-bytes></span> |
| <span class="nt"><max-size-messages></span>-1<span class="nt"></max-size-messages></span> |
| <span class="nt"><max-size-bytes-reject-threshold></span>-1<span class="nt"></max-size-bytes-reject-threshold></span> |
| <span class="nt"><page-size-bytes></span>10MB<span class="nt"></page-size-bytes></span> |
| <span class="nt"><address-full-policy></span>PAGE<span class="nt"></address-full-policy></span> |
| <span class="nt"><message-counter-history-day-limit></message-counter-history-day-limit></span> |
| <span class="nt"><last-value-queue></span>false<span class="nt"></last-value-queue></span> <span class="c"><!-- deprecated! see default-last-value-queue --></span> |
| <span class="nt"><default-last-value-queue></span>false<span class="nt"></default-last-value-queue></span> |
| <span class="nt"><default-non-destructive></span>false<span class="nt"></default-non-destructive></span> |
| <span class="nt"><default-exclusive-queue></span>false<span class="nt"></default-exclusive-queue></span> |
| <span class="nt"><default-consumers-before-dispatch></span>0<span class="nt"></default-consumers-before-dispatch></span> |
| <span class="nt"><default-delay-before-dispatch></span>-1<span class="nt"></default-delay-before-dispatch></span> |
| <span class="nt"><redistribution-delay></span>-1<span class="nt"></redistribution-delay></span> |
| <span class="nt"><send-to-dla-on-no-route></span>false<span class="nt"></send-to-dla-on-no-route></span> |
| <span class="nt"><slow-consumer-threshold></span>-1<span class="nt"></slow-consumer-threshold></span> |
| <span class="nt"><slow-consumer-threshold-measurement-unit></span>MESSAGES_PER_SECOND<span class="nt"></slow-consumer-threshold-measurement-unit></span> |
| <span class="nt"><slow-consumer-policy></span>NOTIFY<span class="nt"></slow-consumer-policy></span> |
| <span class="nt"><slow-consumer-check-period></span>5<span class="nt"></slow-consumer-check-period></span> |
| <span class="nt"><auto-create-queues></span>true<span class="nt"></auto-create-queues></span> |
| <span class="nt"><auto-delete-queues></span>true<span class="nt"></auto-delete-queues></span> |
| <span class="nt"><auto-delete-created-queues></span>false<span class="nt"></auto-delete-created-queues></span> |
| <span class="nt"><auto-delete-queues-delay></span>0<span class="nt"></auto-delete-queues-delay></span> |
| <span class="nt"><auto-delete-queues-message-count></span>0<span class="nt"></auto-delete-queues-message-count></span> |
| <span class="nt"><auto-delete-queues-skip-usage-check></span>false<span class="nt"></auto-delete-queues-skip-usage-check></span> |
| <span class="nt"><config-delete-queues></span>OFF<span class="nt"></config-delete-queues></span> |
| <span class="nt"><config-delete-diverts></span>OFF<span class="nt"></config-delete-diverts></span> |
| <span class="nt"><auto-create-addresses></span>true<span class="nt"></auto-create-addresses></span> |
| <span class="nt"><auto-delete-addresses></span>true<span class="nt"></auto-delete-addresses></span> |
| <span class="nt"><auto-delete-addresses-delay></span>0<span class="nt"></auto-delete-addresses-delay></span> |
| <span class="nt"><auto-delete-addresses-skip-usage-check></span>false<span class="nt"></auto-delete-addresses-skip-usage-check></span> |
| <span class="nt"><config-delete-addresses></span>OFF<span class="nt"></config-delete-addresses></span> |
| <span class="nt"><management-browse-page-size></span>200<span class="nt"></management-browse-page-size></span> |
| <span class="nt"><management-message-attribute-size-limit></span>256<span class="nt"></management-message-attribute-size-limit></span> |
| <span class="nt"><default-purge-on-no-consumers></span>false<span class="nt"></default-purge-on-no-consumers></span> |
| <span class="nt"><default-max-consumers></span>-1<span class="nt"></default-max-consumers></span> |
| <span class="nt"><default-queue-routing-type></span>MULTICAST<span class="nt"></default-queue-routing-type></span> |
| <span class="nt"><default-address-routing-type></span>MULTICAST<span class="nt"></default-address-routing-type></span> |
| <span class="nt"><default-consumer-window-size></span>1048576<span class="nt"></default-consumer-window-size></span> |
| <span class="nt"><default-ring-size></span>-1<span class="nt"></default-ring-size></span> |
| <span class="nt"><retroactive-message-count></span>0<span class="nt"></retroactive-message-count></span> |
| <span class="nt"><enable-metrics></span>true<span class="nt"></enable-metrics></span> |
| <span class="nt"><enable-ingress-timestamp></span>false<span class="nt"></enable-ingress-timestamp></span> |
| <span class="nt"><id-cache-size></span>500<span class="nt"></id-cache-size></span> |
| <span class="nt"></address-setting></span> |
| <span class="nt"></address-settings></span></code></pre> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">dead-letter-address</dt> |
| <dd> |
| <p>Is the address to which messages are sent when they exceed <code>max-delivery-attempts</code>. |
| If no address is defined here then such messages will simply be discarded. |
| Read more about <a href="undelivered-messages.html#configuring-dead-letter-addresses">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">auto-create-dead-letter-resources</dt> |
| <dd> |
| <p>Whether the broker will automatically create the defined <code>dead-letter-address</code> and a corresponding dead-letter queue when a message is undeliverable. |
| Read more in the chapter about <a href="undelivered-messages.html#message-redelivery-and-undelivered-messages">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">dead-letter-queue-prefix</dt> |
| <dd> |
| <p>The prefix used for automatically created dead-letter queues. |
| Default is empty. |
| Read more in the chapter about <a href="undelivered-messages.html#message-redelivery-and-undelivered-messages">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">dead-letter-queue-suffix</dt> |
| <dd> |
| <p>The suffix used for automatically created dead-letter queues. |
| Default is empty. |
| Read more in the chapter about <a href="undelivered-messages.html#message-redelivery-and-undelivered-messages">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">expiry-address</dt> |
| <dd> |
| <p>Where to send a message that has expired. |
| If no address is defined here then such messages will simply be discarded. |
| Read more about <a href="message-expiry.html#configuring-expiry-addresses">message expiry</a>.</p> |
| </dd> |
| <dt class="hdlist1">auto-create-expiry-resources</dt> |
| <dd> |
| <p>Determines whether or not the broker will automatically create the defined <code>expiry-address</code> and a corresponding expiry queue when a message expired. |
| Read more in the chapter about <a href="undelivered-messages.html#message-redelivery-and-undelivered-messages">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">expiry-queue-prefix</dt> |
| <dd> |
| <p>The prefix used for automatically created expiry queues. |
| Default is empty. |
| Read more in the chapter about <a href="message-expiry.html#message-expiry">message expiry</a>.</p> |
| </dd> |
| <dt class="hdlist1">expiry-queue-suffix</dt> |
| <dd> |
| <p>The suffix used for automatically created expiry queues. |
| Default is empty. |
| Read more in the chapter about <a href="message-expiry.html#message-expiry">message expiry</a>.</p> |
| </dd> |
| <dt class="hdlist1">expiry-delay</dt> |
| <dd> |
| <p>The expiration time that will be used for messages which are using the default expiration time (i.e. 0). |
| For example, if <code>expiry-delay</code> 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 <code>expiry-delay</code> to "-1" will disable this feature. |
| The default is "-1". |
| Read more about <a href="message-expiry.html#configuring-expiry-addresses">message expiry</a>.</p> |
| </dd> |
| <dt class="hdlist1">max-delivery-attempts</dt> |
| <dd> |
| <p>defines how many time a cancelled message can be redelivered before sending to the <code>dead-letter-address</code>. |
| Read more about <a href="undelivered-messages.html#configuring-dead-letter-addresses">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">redelivery-delay</dt> |
| <dd> |
| <p>defines how long to wait before attempting redelivery of a cancelled message. |
| Default is <code>0</code>. |
| Read more about <a href="undelivered-messages.html#configuring-delayed-redelivery">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">redelivery-delay-multiplier</dt> |
| <dd> |
| <p>The number by which the <code>redelivery-delay</code> will be multiplied on each subsequent redelivery attempt. |
| Default is <code>1.0</code>. |
| Read more about <a href="undelivered-messages.html#configuring-delayed-redelivery">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">redelivery-collision-avoidance-factor</dt> |
| <dd> |
| <p>defines an additional factor used to calculate an adjustment to the <code>redelivery-delay</code> (up or down). |
| Default is <code>0.0</code>. |
| Valid values are between 0.0 and 1.0. |
| Read more about <a href="undelivered-messages.html#configuring-delayed-redelivery">undelivered messages</a>.</p> |
| </dd> |
| <dt class="hdlist1">max-size-bytes</dt> |
| <dt class="hdlist1">max-size-messages</dt> |
| <dt class="hdlist1">page-size-bytes</dt> |
| <dt class="hdlist1">max-read-page-messages</dt> |
| <dt class="hdlist1">max-read-page-bytes</dt> |
| <dd> |
| <p>All these are used to configure paging on an address. |
| This is explained in the <a href="paging.html#configuration">paging documentation</a>.</p> |
| </dd> |
| <dt class="hdlist1">max-size-bytes-reject-threshold</dt> |
| <dd> |
| <p>is used with the address full <code>BLOCK</code> policy, the maximum size (in bytes) an address can reach before messages start getting rejected. |
| Works in combination with <code>max-size-bytes</code> <strong>for AMQP clients only</strong>. |
| Default is <code>-1</code> (i.e. no limit).</p> |
| </dd> |
| <dt class="hdlist1">address-full-policy</dt> |
| <dd> |
| <p>This attribute can have one of the following values: <code>PAGE</code>, <code>DROP</code>, <code>FAIL</code> or <code>BLOCK</code> and determines what happens when an address where <code>max-size-bytes</code> is specified becomes full. |
| The default value is <code>PAGE</code>. |
| If the value is <code>PAGE</code> then further messages will be paged to disk. |
| If the value is <code>DROP</code> then further messages will be silently dropped. |
| If the value is <code>FAIL</code> then further messages will be dropped and an exception will be thrown on the client-side. |
| If the value is <code>BLOCK</code> then client message producers will block when they try and send further messages. |
| See the <a href="flow-control.html#flow-control">Flow Control</a> and <a href="paging.html#paging">Paging</a> chapters for more info.</p> |
| </dd> |
| <dt class="hdlist1">message-counter-history-day-limit</dt> |
| <dd> |
| <p>is the number of days to keep message counter history for this address assuming that <code>message-counter-enabled</code> is <code>true</code>. |
| Default is <code>0</code>.</p> |
| </dd> |
| <dt class="hdlist1">default-last-value-queue</dt> |
| <dd> |
| <p>Whether a queue only uses last values or not. |
| Default is <code>false</code>. |
| This value can be overridden at the queue level using the <code>last-value</code> boolean. |
| Read more about <a href="last-value-queues.html#last-value-queues">last value queues</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-exclusive-queue</dt> |
| <dd> |
| <p>Whether a queue will serve only a single consumer. |
| Default is <code>false</code>. |
| This value can be overridden at the queue level using the <code>exclusive</code> boolean. |
| Read more about <a href="exclusive-queues.html#exclusive-queues">exclusive queues</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-consumers-before-dispatch</dt> |
| <dd> |
| <p>The number of consumers needed on a queue bound to the matching address before messages will be dispatched to those consumers. |
| Default is <code>0</code>. |
| This value can be overridden at the queue level using the <code>consumers-before-dispatch</code> boolean. |
| This behavior can be tuned using <code>delay-before-dispatch</code> on the queue itself or by using the <code>default-delay-before-dispatch</code> address-setting.</p> |
| </dd> |
| <dt class="hdlist1">default-delay-before-dispatch</dt> |
| <dd> |
| <p>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 <code>-1</code> (wait forever).</p> |
| </dd> |
| <dt class="hdlist1">redistribution-delay</dt> |
| <dd> |
| <p>How long to wait when the last consumer is closed on a queue before redistributing any messages. |
| Default is <code>-1</code>. |
| Read more about <a href="clusters.html#message-redistribution">clusters</a>.</p> |
| </dd> |
| <dt class="hdlist1">send-to-dla-on-no-route</dt> |
| <dd> |
| <p>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 <code>true</code> then such a message will instead be sent to the <code>dead-letter-address</code> (DLA) for that address, if it exists. |
| Default is <code>false</code>.</p> |
| </dd> |
| <dt class="hdlist1">slow-consumer-threshold</dt> |
| <dd> |
| <p>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 <code>-1</code> (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 <a href="slow-consumers.html#detecting-slow-consumers">slow consumers</a>.</p> |
| </dd> |
| <dt class="hdlist1">slow-consumer-threshold-measurement-unit</dt> |
| <dd> |
| <p>The units used to measure the slow-consumer-threshold. |
| Valid options are:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>MESSAGES_PER_SECOND</p> |
| </li> |
| <li> |
| <p>MESSAGES_PER_MINUTE</p> |
| </li> |
| <li> |
| <p>MESSAGES_PER_HOUR</p> |
| </li> |
| <li> |
| <p>MESSAGES_PER_DAY</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If no unit is specified the default MESSAGES_PER_SECOND will be used. |
| Read more about <a href="slow-consumers.html#detecting-slow-consumers">slow consumers</a>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">slow-consumer-policy</dt> |
| <dd> |
| <p>What should happen when a slow consumer is detected. |
| <code>KILL</code> will kill the consumer’s connection (which will obviously impact any other client threads using that same connection). |
| <code>NOTIFY</code> will send a CONSUMER_SLOW management notification which an application could receive and take action with. |
| Read more about <a href="slow-consumers.html#detecting-slow-consumers">slow consumers</a>.</p> |
| </dd> |
| <dt class="hdlist1">slow-consumer-check-period</dt> |
| <dd> |
| <p>How often to check for slow consumers on a particular queue. |
| Measured in <em>seconds</em>. |
| Default is <code>5</code>.</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| This should be at least 2x the maximum time it takes a consumer to process 1 message. |
| For example, if the <code>slow-consumer-threshold</code> is set to 1 and the <code>slow-consumer-threshold-measurement-unit</code> is set to <code>MESSAGES_PER_MINUTE</code> then this should be set to at least 2 x 60s i.e. 120s. |
| Read more about <a href="slow-consumers.html#detecting-slow-consumers">slow consumers</a>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </dd> |
| <dt class="hdlist1">auto-create-queues</dt> |
| <dd> |
| <p>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 <code>match</code>. |
| Queues which are auto-created are durable, non-temporary, and non-transient. |
| Default is <code>true</code>.</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Automatic queue creation does <em>not</em> work for the core client. |
| The core API is a low-level API and is not meant to have such automation. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| Automatic queue creation is for queues that <em>would not otherwise be created during normal operation</em>. |
| For example, when a remote application creates a consumer on a JMS topic then a queue will be created representing that subscription as described in the <a href="jms-core-mapping.html">JMS-to-core mapping chapter</a>. |
| This queue will be created regardless of how <code>auto-create-queues</code> is configured because it is required for <em>normal operation</em>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">auto-delete-queues</dt> |
| <dd> |
| <p>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 <code>auto-delete-queues-message-count</code>. |
| Default is <code>true</code>.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-created-queues</dt> |
| <dd> |
| <p>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 <code>auto-delete-queues-message-count</code>. |
| Default is <code>false</code>.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-queues-delay</dt> |
| <dd> |
| <p>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 <code>auto-delete-queues-message-count</code>. |
| Default is <code>0</code> (delete immediately). |
| The broker’s <code>address-queue-scan-period</code> controls how often (in milliseconds) queues are scanned for potential deletion. |
| Use <code>-1</code> to disable scanning. |
| The default scan value is <code>30000</code>.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-queues-message-count</dt> |
| <dd> |
| <p>The message count that the queue must be less than or equal to before deleting auto-created queues. |
| To disable message count check <code>-1</code> can be set. |
| Default is <code>0</code> (empty queue).</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-queues-skip-usage-check</dt> |
| <dd> |
| <p>A queue will only be auto-deleted by default if it has actually been "used." A queue is considered "used" if any messages have been sent to it or any consumers have connected to it during its life. |
| However, there are use-cases where it’s useful to skip this check. |
| When set to <code>true</code> it is <strong>imperative</strong> to also set <code>auto-delete-queues-delay</code> to a value greater than <code>0</code> otherwise queues may be deleted almost immediately after being created. |
| In this case the queue will be deleted based on when it was created rather then when it was last "used." Default is <code>false</code>.</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| the above auto-delete address settings can also be configured individually at the queue level when a client auto creates the queue. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>For Core API it is exposed in createQueue methods.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For Core JMS you can set it using the destination queue attributes <code>my.destination?auto-delete=true&auto-delete-delay=120000&auto-delete-message-count=-1</code></p> |
| </div> |
| </dd> |
| <dt class="hdlist1">config-delete-queues</dt> |
| <dd> |
| <p>How the broker should handle queues deleted on config reload, by delete policy: <code>OFF</code> or <code>FORCE</code>. |
| Default is <code>OFF</code>. |
| Read more about <a href="config-reload.html#configuration-reload">configuration reload</a>.</p> |
| </dd> |
| <dt class="hdlist1">config-delete-diverts</dt> |
| <dd> |
| <p>How the broker should handle diverts deleted on config reload, by delete policy: <code>OFF</code> or <code>FORCE</code>. |
| Default is <code>OFF</code>. |
| Read more about <a href="config-reload.html#configuration-reload">configuration reload</a>.</p> |
| </dd> |
| <dt class="hdlist1">auto-create-addresses</dt> |
| <dd> |
| <p>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 <code>match</code>. |
| Default is <code>true</code>.</p> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| automatic address creation does <em>not</em> work for the core client. |
| The core API is a low-level API and is not meant to have such automation. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </dd> |
| <dt class="hdlist1">auto-delete-addresses</dt> |
| <dd> |
| <p>Whether or not the broker should automatically delete auto-created addresses once the address no longer has any queues. |
| Default is <code>true</code>.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-addresses-delay</dt> |
| <dd> |
| <p>How long to wait (in milliseconds) before deleting auto-created addresses after they no longer have any queues. |
| Default is <code>0</code> (delete immediately). |
| The broker’s <code>address-queue-scan-period</code> controls how often (in milliseconds) addresses are scanned for potential deletion. |
| Use <code>-1</code> to disable scanning. |
| The default scan value is <code>30000</code>.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-addresses-skip-usage-check</dt> |
| <dd> |
| <p>An address will only be auto-deleted by default if it has actually been "used." An address is considered "used" if any queues have been created on it during its life. |
| However, there are use-cases where it’s useful to skip this check. |
| When set to <code>true</code> it is <strong>imperative</strong> to also set <code>auto-delete-addresses-delay</code> to a value greater than <code>0</code> otherwise addresses may be deleted almost immediately after being created. |
| In this case the address will be deleted based on when it was created rather then when it was last "used." Default is <code>false</code>.</p> |
| </dd> |
| <dt class="hdlist1">config-delete-addresses</dt> |
| <dd> |
| <p>How the broker should handle addresses deleted on config reload, by delete policy: <code>OFF</code> or <code>FORCE</code>. |
| Default is <code>OFF</code>. |
| Read more about <a href="config-reload.html#configuration-reload">configuration reload</a>.</p> |
| </dd> |
| <dt class="hdlist1">management-browse-page-size</dt> |
| <dd> |
| <p>is the number of messages a management resource can browse. |
| This is relevant for the <code>browse, list and count-with-filter</code> management methods exposed on the queue control. |
| Default is <code>200</code>.</p> |
| </dd> |
| <dt class="hdlist1">management-message-attribute-size-limit</dt> |
| <dd> |
| <p>is the number of bytes collected from the message for browse. |
| This is relevant for the <code>browse and list</code> management methods exposed on the queue control. |
| Message attributes longer than this value appear truncated. |
| Default is <code>256</code>. |
| Use <code>-1</code> 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.</p> |
| </dd> |
| <dt class="hdlist1">default-purge-on-no-consumers</dt> |
| <dd> |
| <p>defines a queue’s default <code>purge-on-no-consumers</code> setting if none is provided on the queue itself. |
| Default is <code>false</code>. |
| This value can be overridden at the queue level using the <code>purge-on-no-consumers</code> boolean. |
| Read more about <a href="address-model.html#non-durable-subscription-queue">this functionality</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-max-consumers</dt> |
| <dd> |
| <p>defines a queue’s default <code>max-consumers</code> setting if none is provided on the queue itself. |
| Default is <code>-1</code> (i.e. no limit). |
| This value can be overridden at the queue level using the <code>max-consumers</code> boolean. |
| Read more about <a href="address-model.html#shared-durable-subscription-queue-using-max-consumers">this functionality</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-queue-routing-type</dt> |
| <dd> |
| <p>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 <code>MULTICAST</code>. |
| Read more about <a href="address-model.html#routing-type">routing types</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-address-routing-type</dt> |
| <dd> |
| <p>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 <code>MULTICAST</code>. |
| Read more about <a href="address-model.html#routing-type">routing types</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-consumer-window-size</dt> |
| <dd> |
| <p>The default <code>consumerWindowSize</code> value for a <code>CORE</code> 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 <a href="flow-control.html#flow-control">flow control</a>.</p> |
| </dd> |
| <dt class="hdlist1">default-ring-size</dt> |
| <dd> |
| <p>The default <code>ring-size</code> value for any matching queue which doesn’t have <code>ring-size</code> explicitly defined. |
| If not defined the default will be set to -1. |
| Read more about <a href="ring-queues.html#ring-queue">ring queues</a>.</p> |
| </dd> |
| <dt class="hdlist1">retroactive-message-count</dt> |
| <dd> |
| <p>The number of messages to preserve for future queues created on the matching address. |
| Defaults to 0. |
| Read more about <a href="retroactive-addresses.html#retroactive-addresses">retroactive addresses</a>.</p> |
| </dd> |
| <dt class="hdlist1">enable-metrics</dt> |
| <dd> |
| <p>determines whether or not metrics will be published to any configured metrics plugin for the matching address. |
| Default is <code>true</code>. |
| Read more about <a href="metrics.html#metrics">metrics</a>.</p> |
| </dd> |
| <dt class="hdlist1">enable-ingress-timestamp</dt> |
| <dd> |
| <p>determines whether or not the broker will add its time to messages sent to the matching address. |
| When <code>true</code> the exact behavior will depend on the specific protocol in use. |
| For AMQP messages the broker will add a <code>long</code> <em>message annotation</em> named <code>x-opt-ingress-time</code>. |
| For core messages (used by the core and OpenWire protocols) the broker will add a long property named <code>_AMQ_INGRESS_TIMESTAMP</code>. |
| For STOMP messages the broker will add a frame header named <code>ingress-timestamp</code>. |
| The value will be the number of milliseconds since the <a href="https://en.wikipedia.org/wiki/Unix_time">epoch</a>. |
| Default is <code>false</code>.</p> |
| </dd> |
| <dt class="hdlist1">id-cache-size</dt> |
| <dd> |
| <p>defines the maximum size of the duplicate ID cache for an address, as each address has it’s own cache |
| that helps to detect and prevent the processing of duplicate messages based on their unique identification. |
| By default, the <code>id-cache-size</code> setting inherits from the global <code>id-cache-size</code>, with a default of <code>20000</code> |
| elements if not explicitly configured. Read more about <a href="duplicate-detection.html#configuring-the-duplicate-id-cache">duplicate id cache sizes</a>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="literal-matches"><a class="anchor" href="#literal-matches"></a><a class="link" href="#literal-matches">1. Literal Matches</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>A <em>literal</em> match is a match that contains wildcards but should be applied <em>without regard</em> to those wildcards. In other words, the wildcards should be ignored and the address settings should only be applied to the literal (i.e. exact) match.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This can be useful when an application uses a <a href="wildcard-routing.html">wildcard address</a>. For example, if an application creates a multicast queue on the address <code>orders.#</code> and that queue needs a different configuration than other matching addresses like <code>orders.retail</code> and <code>orders.wholesale</code>. Generally speaking this kind of use-case is rare, but wildcard addresses are often used by MQTT clients, and this kind of configuration flexiblity is useful.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="configuring-a-literal-match"><a class="anchor" href="#configuring-a-literal-match"></a><a class="link" href="#configuring-a-literal-match">1.1. Configuring a Literal Match</a></h3> |
| <div class="paragraph"> |
| <p>If you want to configure a literal match the first thing to do is to configure the <code>literal-match-markers</code> parameter in <code>broker.xml</code>. This defines the beginning and ending characters used to mark the literal match, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><core></span> |
| ... |
| <span class="nt"><literal-match-markers></span>()<span class="nt"></literal-match-markers></span> |
| ... |
| <span class="nt"></core></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>By default, no value is defined for <code>literal-match-markers</code> which means that literal matches are disabled by default. The value must be only 2 characters.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Once <code>literal-match-markers</code> is defined you can then use those markers in the <code>match</code> of the address setting, e.g.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><address-settings></span> |
| <span class="nt"><address-setting</span> <span class="na">match=</span><span class="s">"(orders.#)"</span><span class="nt">></span> |
| <span class="nt"><enable-metrics></span>true<span class="nt"></enable-metrics></span> |
| <span class="nt"></address-setting></span> |
| <span class="nt"><address-setting</span> <span class="na">match=</span><span class="s">"orders.#"</span><span class="nt">></span> |
| <span class="nt"><enable-metrics></span>false<span class="nt"></enable-metrics></span> |
| <span class="nt"></address-setting></span> |
| <span class="nt"></address-settings></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Using these settings metrics will be enabled on the address <code>orders.#</code> and any queues bound directly on that address, but metrics will <em>not</em> be enabled for other matching addresses like <code>orders.retail</code> or <code>orders.wholesale</code> and any queues bound to those addresses.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
