172 lines
12 KiB
XML
172 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!-- ============================================================================= -->
|
|
<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
|
|
<!-- contributor license agreements. See the NOTICE file distributed with -->
|
|
<!-- this work for additional information regarding copyright ownership. -->
|
|
<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
|
|
<!-- (the "License"); you may not use this file except in compliance with -->
|
|
<!-- the License. You may obtain a copy of the License at -->
|
|
<!-- -->
|
|
<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
|
|
<!-- -->
|
|
<!-- Unless required by applicable law or agreed to in writing, software -->
|
|
<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
|
|
<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
|
|
<!-- See the License for the specific language governing permissions and -->
|
|
<!-- limitations under the License. -->
|
|
<!-- ============================================================================= -->
|
|
|
|
<!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 "ActiveMQ_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>activemq-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
|
|
>activemq-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>activemq-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>
|