173 lines
12 KiB
XML
173 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<chapter id="queue-attributes">
|
||
<title>Queue Attributes</title>
|
||
<para>Queue attributes can be set in one of two ways. Either by configuring them using the
|
||
configuration file or by using the core API. This chapter will explain how to configure each
|
||
attribute and what effect the attribute has.</para>
|
||
<section id="predefined.queues">
|
||
<title>Predefined Queues</title>
|
||
<para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly
|
||
let's look at a JMS level.</para>
|
||
<para>The following shows a queue predefined in the <literal>hornetq-jms.xml</literal>
|
||
configuration file.</para>
|
||
<programlisting>
|
||
<queue name="selectorQueue">
|
||
<entry name="/queue/selectorQueue"/>
|
||
<selector string="color='red'"/>
|
||
<durable>true</durable>
|
||
</queue></programlisting>
|
||
<para>This name attribute of queue defines the name of the queue. When we do this at a jms
|
||
level we follow a naming convention so the actual name of the core queue will be
|
||
<literal>jms.queue.selectorQueue</literal>.</para>
|
||
<para>The entry element configures the name that will be used to bind the queue to JNDI.
|
||
This is a mandatory element and the queue can contain multiple of these to bind the same
|
||
queue to different names.</para>
|
||
<para>The selector element defines what JMS message selector the predefined queue will have.
|
||
Only messages that match the selector will be added to the queue. This is an optional
|
||
element with a default of null when omitted.</para>
|
||
<para>The durable element specifies whether the queue will be persisted. This again is
|
||
optional and defaults to true if omitted.</para>
|
||
<para>Secondly a queue can be predefined at a core level in the <literal
|
||
>hornetq-configuration.xml</literal> file. The following is an example.</para>
|
||
<programlisting>
|
||
<queues>
|
||
<queue name="jms.queue.selectorQueue">
|
||
<address>jms.queue.selectorQueue</address>
|
||
<filter string="color='red'"/>
|
||
<durable>true</durable>
|
||
</queue>
|
||
</queues></programlisting>
|
||
<para>This is very similar to the JMS configuration, with 3 real differences which
|
||
are.</para>
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The name attribute of queue is the actual name used for the queue with no
|
||
naming convention as in JMS.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>The address element defines what address is used for routing messages.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>There is no entry element.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>The filter uses the <emphasis>Core filter syntax</emphasis> (described in
|
||
<xref linkend="filter-expressions"/>), <emphasis>not</emphasis> the JMS
|
||
selector syntax.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</section>
|
||
<section>
|
||
<title>Using the API</title>
|
||
<para>Queues can also be created using the core API or the management API.</para>
|
||
<para>For the core API, queues can be created via the <literal
|
||
>org.apache.activemq.api.core.client.ClientSession</literal> interface. There are multiple
|
||
<literal>createQueue</literal> methods that support setting all of the previously
|
||
mentioned attributes. There is one extra attribute that can be set via this API which is
|
||
<literal>temporary</literal>. setting this to true means that the queue will be
|
||
deleted once the session is disconnected.</para>
|
||
<para>Take a look at <xref linkend="management"/> for a description of the management API
|
||
for creating queues.</para>
|
||
</section>
|
||
<section id="queue-attributes.address-settings">
|
||
<title>Configuring Queues Via Address Settings</title>
|
||
<para>There are some attributes that are defined against an address wildcard rather than a
|
||
specific queue. Here an example of an <literal>address-setting</literal> entry that
|
||
would be found in the <literal>hornetq-configuration.xml</literal> file.</para>
|
||
<programlisting>
|
||
<address-settings>
|
||
<address-setting match="jms.queue.exampleQueue">
|
||
<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
|
||
<max-delivery-attempts>3</max-delivery-attempts>
|
||
<redelivery-delay>5000</redelivery-delay>
|
||
<expiry-address>jms.queue.expiryQueue</expiry-address>
|
||
<last-value-queue>true</last-value-queue>
|
||
<max-size-bytes>100000</max-size-bytes>
|
||
<page-size-bytes>20000</page-size-bytes>
|
||
<redistribution-delay>0</redistribution-delay>
|
||
<send-to-dla-on-no-route>true</send-to-dla-on-no-route>
|
||
<address-full-policy>PAGE</address-full-policy>
|
||
<slow-consumer-threshold>-1</slow-consumer-threshold>
|
||
<slow-consumer-policy>NOTIFY</slow-consumer-policy>
|
||
<slow-consumer-check-period>5</slow-consumer-check-period>
|
||
</address-setting>
|
||
</address-settings></programlisting>
|
||
<para>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 <literal>match</literal> attribute. In the
|
||
above example the settings would only be applied to any addresses which exactly match
|
||
the address <literal>jms.queue.exampleQueue</literal>, but you can also use wildcards to apply sets of
|
||
configuration against many addresses. The wildcard syntax used is described <link linkend="wildcard-syntax">here</link>.</para>
|
||
<para>For example, if you used the <literal>match</literal> string <literal>jms.queue.#</literal> the settings would be applied
|
||
to all addresses which start with <literal>jms.queue.</literal> which would be all JMS queues.</para>
|
||
<para>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. </para>
|
||
<para><literal>max-delivery-attempts</literal> defines how many time a cancelled message can
|
||
be redelivered before sending to the <literal>dead-letter-address</literal>. A full
|
||
explanation can be found <link linkend="undelivered-messages.configuring"
|
||
>here</link>.</para>
|
||
<para><literal>redelivery-delay</literal> defines how long to wait before attempting
|
||
redelivery of a cancelled message. see <link linkend="undelivered-messages.delay"
|
||
>here</link>.</para>
|
||
<para><literal>expiry-address</literal> defines where to send a message that has expired.
|
||
see <link linkend="message-expiry.configuring">here</link>.</para>
|
||
<para><literal>expiry-delay</literal> defines the expiration time that will be used for messages which are using
|
||
the default expiration time (i.e. 0). For example, if <literal>expiry-delay</literal> 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 <literal>expiry-delay</literal> to "-1" will disable this feature. The
|
||
default is "-1".</para>
|
||
<para><literal>last-value-queue</literal> defines whether a queue only uses last values or
|
||
not. see <link linkend="last-value-queues">here</link>.</para>
|
||
<para><literal>max-size-bytes</literal> and <literal>page-size-bytes</literal> are used to
|
||
set paging on an address. This is explained <link linkend="paging">here</link>.</para>
|
||
<para><literal>redistribution-delay</literal> defines how long to wait when the last
|
||
consumer is closed on a queue before redistributing any messages. see <link
|
||
linkend="clusters">here</link>.</para>
|
||
<para><literal>send-to-dla-on-no-route</literal>. If a message is sent to an address, but the server does not route it to any queues,
|
||
for example, 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 set to true for that address, if the message is not routed to any queues it will instead
|
||
be sent to the dead letter address (DLA) for that address, if it exists.</para>
|
||
<para><literal>address-full-policy</literal>. This attribute can have one of the following values: PAGE, DROP, FAIL or BLOCK and determines what happens when
|
||
an address where <literal>max-size-bytes</literal> 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 following chapters for more info <xref linkend="flow-control"/>, <xref linkend="paging"/>.
|
||
</para>
|
||
<para><literal>slow-consumer-threshold</literal>. The minimum rate of message consumption allowed before a
|
||
consumer is considered "slow." Measured in messages-per-second. Default is -1 (i.e. disabled); any other valid
|
||
value must be greater than 0.</para>
|
||
<para><literal>slow-consumer-policy</literal>. What should happen when a slow consumer is detected.
|
||
<literal>KILL</literal> will kill the consumer's connection (which will obviously impact any other client
|
||
threads using that same connection). <literal>NOTIFY</literal> will send a CONSUMER_SLOW management
|
||
notification which an application could receive and take action with. See
|
||
<xref linkend="notification.types.and.headers"/> for more details on this notification.</para>
|
||
<para><literal>slow-consumer-check-period</literal>. How often to check for slow consumers on a particular queue.
|
||
Measured in minutes. Default is 5. See <xref linkend="slow-consumers"/> for more information about slow
|
||
consumer detection.</para>
|
||
</section>
|
||
</chapter>
|