From 3385198ba2f67d14ebf2ab73721e6ab76c112efa Mon Sep 17 00:00:00 2001 From: Robert Godfrey Date: Sun, 15 Mar 2015 22:26:32 +0000 Subject: QPID-6453 : [Java Broker] add documentation for new Queue attributes git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1666849 13f79535-47bb-0310-9956-ffa450edef68 --- .../concepts/Java-Broker-Concepts-Queues.xml | 342 +++++++++++++++++++++ .../Java-Broker-Management-Managing-Queues.xml | 221 +------------ 2 files changed, 351 insertions(+), 212 deletions(-) (limited to 'qpid/doc') diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml index ea806fe348..a3e10f8b22 100644 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml @@ -20,6 +20,10 @@ --> + +%entities; +]>
Queues Queues are named entities within a Virtualhost that @@ -27,4 +31,342 @@ linkend="Java-Broker-Concepts-Exchanges">Exchange for passing messages to a queue. Consumers subscribe to a queue in order to receive messages for it. The Broker supports different queue types, each with different delivery semantics. It also messages on a queue to be treated as a group. +
+ Types + The Broker supports four different queue types, each with different delivery semantics. + + Standard - a simple First-In-First-Out (FIFO) queue + + + Priority - delivery order depends on the priority of each message + + + Sorted - + delivery order depends on the value of the sorting key property in each message + + + Last Value + Queue - also known as an LVQ, retains only the last (newest) message received + with a given LVQ key value + + +
+ Standard + A simple First-In-First-Out (FIFO) queue +
+
+ Priority + In a priority queue, messages on the queue are delivered in an order determined by the + JMS priority message + header within the message. By default Qpid supports the 10 priority levels + mandated by JMS, with priority value 0 as the lowest priority and 9 as the highest. + It is possible to reduce the effective number of priorities if desired. + JMS defines the + default message priority as 4. Messages sent without a specified priority use this + default. +
+
+ Sorted Queues + Sorted queues allow the message delivery order to be determined by value of an arbitrary + JMS message + property. Sort order is alpha-numeric and the property value must have a type + java.lang.String. + Messages sent to a sorted queue without the specified JMS message property will be + inserted into the 'last' position in the queue. +
+
+ Last Value Queues (LVQ) + LVQs (or conflation queues) are special queues that automatically discard any message + when a newer message arrives with the same key value. The key is specified by arbitrary + JMS message + property. + An example of an LVQ might be where a queue represents prices on a stock exchange: when + you first consume from the queue you get the latest quote for each stock, and then as new + prices come in you are sent only these updates. + Like other queues, LVQs can either be browsed or consumed from. When browsing an + individual subscriber does not remove the message from the queue when receiving it. This + allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and + bind a separate LVQ for each subscriber who wishes to receive the contents of the + LVQ). + Messages sent to an LVQ without the specified property will be delivered as normal and + will never be "replaced". +
+
+
+ Queue Declare Arguments + To create a priority, sorted or LVQ queue programmatically from JMX or AMQP, pass the + appropriate queue-declare arguments. + + Queue-declare arguments understood for priority, sorted and LVQ queues + + + + Queue type + Argument name + Argument name + Argument Description + + + + + priority + x-qpid-priorities + java.lang.Integer + Specifies a priority queue with given number priorities + + + sorted + qpid.queue_sort_key + java.lang.String + Specifies sorted queue with given message property used to sort the + entries + + + lvq + qpid.last_value_queue_key + java.lang.String + Specifies lvq queue with given message property used to conflate the + entries + + + +
+
+
+ Messaging Grouping + The broker allows messaging applications to classify a set of related messages as + belonging to a group. This allows a message producer to indicate to the consumer that a group + of messages should be considered a single logical operation with respect to the application. + The broker can use this group identification to enforce policies controlling how messages + from a given group can be distributed to consumers. For instance, the broker can be configured + to guarantee all the messages from a particular group are processed in order across multiple + consumers. + For example, assume we have a shopping application that manages items in a virtual + shopping cart. A user may add an item to their shopping cart, then change their mind and + remove it. If the application sends an add message to the broker, + immediately followed by a remove message, they will be queued in the + proper order - add, followed by remove. + However, if there are multiple consumers, it is possible that once a consumer acquires + the add message, a different consumer may acquire the + remove message. This allows both messages to be processed in parallel, + which could result in a "race" where the remove operation is incorrectly + performed before the add operation. +
+ Grouping Messages + In order to group messages, the application would designate a particular message header + as containing a message's group identifier. The group identifier stored + in that header field would be a string value set by the message producer. Messages from the + same group would have the same group identifier value. The key that identifies the header + must also be known to the message consumers. This allows the consumers to determine a + message's assigned group. + The header that is used to hold the group identifier, as well as the values used as + group identifiers, are totally under control of the application. +
+
+ The Role of the Broker in Message Grouping + The broker will apply the following processing on each grouped message: + + Enqueue a received message on the destination queue. + + + Determine the message's group by examining the message's group identifier + header. + + + Enforce consumption ordering among messages belonging to the + same group. Consumption ordering means one of two things + depending on how the queue has been configured. + + + In default mode, a group gets assigned to a single consumer for the lifetime + of that consumer, and the broker will pass all subsequent messages in the group to + that consumer. + + + In 'shared groups' mode (which gives the same behaviour as the Qpid C++ + Broker) the broker enforces a looser guarantee, namely that all the + currently unacknowledged messages in a group are sent to + the same consumer, but the consumer used may change over time even if the + consumers do not. This means that only one consumer can be processing messages + from a particular group at any given time, however if the consumer acknowledges + all of its acquired messages then the broker may pass the + next pending message in that group to a different consumer. + + + + + + The absence of a value in the designated group header field of a message is treated as + follows: + + In default mode, failure for a message to specify a group is treated as a desire + for the message not to be grouped at all. Such messages will be distributed to any + available consumer, without the ordering quarantees imposed by grouping. + + + In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker) + the broker assigns messages without a group value to a 'default group'. Therefore, all + such "unidentified" messages are considered by the broker as part of the same group, + which will handled like any other group. The name of this default group is + "qpid.no-group", although it can be customised as detailed below. + + + + Note that message grouping has no effect on queue browsers. + Note well that distinct message groups would not block each other from delivery. For + example, assume a queue contains messages from two different message groups - say group "A" + and group "B" - and they are enqueued such that "A"'s messages are in front of "B". If the + first message of group "A" is in the process of being consumed by a client, then the + remaining "A" messages are blocked, but the messages of the "B" group are available for + consumption by other consumers - even though it is "behind" group "A" in the queue. +
+
+
+ Using low pre-fetch with special queue types + Qpid clients receive buffered messages in batches, sized according to the pre-fetch value. + The current default is 500. + However, if you use the default value you will probably not see + desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has + sent a message to the client its delivery order is then fixed, regardless of the special + behaviour of the queue. + For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with + priority 2, the broker will send these messages to the client. If then a new message arrives + will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will + be delivered at the front of the next batch of messages to be sent to the client. + So, you need to set the prefetch values for your client (consumer) to make this sensible. + To do this set the Java system property max_prefetch on the client + environment (using -D) before creating your consumer. + A default for all client connections can be set via a system property: + +-Dmax_prefetch=1 + + The prefetch can be also be adjusted on a per connection basis by adding a + maxprefetch value to the Connection URLs + + +amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672' + + Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the + client however, this brings a performance cost. You could test with a slightly higher + pre-fetch to trade-off between throughput and exact semantics. +
+
+ Forcing all consumers to be non-destructive + When a consumer attaches to a queue, the normal behaviour is that messages are + sent to that consumer are acquired exclusively by that consumer, and when the consumer + acknowledges them, the messages are removed from the queue. + Another common pattern is to have queue "browsers" which send all messages to the + browser, but do not prevent other consumers from receiving the messages, and do not + remove them from the queue when the browser is done with them. Such a browser is an + instance of a "non-destructive" consumer. + If every consumer on a queue is non destructive then we can obtain some interesting + behaviours. In the case of a LVQ + then the queue will always contain the most up to date value for every key. For + a standard queue, if every consumer is non-destructive then we have something that + behaves like a topic (every consumer receives every message) except that instead of + only seeing messages that arrive after the point at which the consumer is created, all + messages which have not been reoved due to TTL expiry (or, in the case of LVQs, + overwirtten by newer values for the same key). + A queue can be created to enforce all consumers are non-destructive. This can be + be achieved using the following queue declare argument: + + + + + Argument name + Argument name + Argument Description + + + + + qpid.ensure_nondestructive_consumers + java.lang.Boolean + Set to true if the queue should make all consumers attached to it behave + non-destructively. (Default is false). + + + +
+ Through the REST api, + the equivalent attribute is named ensureNondestructiveConsumers. + +
+ Bounding size using min/max TTL + For queues other than LVQs, having only non-destructive consumers could mean that + messages would never get deleted, leaving the queue to grow unconstrainedly. To + prevent this you can use the ability to set the maximum TTL of the queue. To ensure + all messages have the same TTL you could also set the minimum TTL to the same value. + + Minimum/Maximum TTL for a queue can only be set using the REST API or by hand + editing the configuration file (for JSON configuration stores). The attribute names + are minimumMessageTtl and maximumMessageTtl + and the TTL value is given in milliseconds. +
+
+ Choosing to receive messages based on arrival time + A queue with no destructive consumers will retain all messages until they expire + due to TTL. It may be the case that a consumer only wishes to receive messages + that have been sent in the last 60 minutes, and any new messages that arrive, or + alternatively it may wish only to receive newly arriving messages and not any that + are already in the queue. This can be achieved by using a filter on the arrival + time. + A special parameter x-qpid-replay-period can be used in the + consumer declaration to control the messages the consumer wishes to receive. The + value of x-qpid-replay-period is the time, in seconds, for which + the consumer wishes to see messages. A replay period of 0 indicates only newly + arriving messages should be sent. A replay period of 3600 indicates that only + messages sent in the last hour - along with any newly arriving messages - should be + sent. + + Setting the replay period + + + + Syntax + Example + + + + + Addressing + myqueue ; { link : { x-subscribe: { arguments : { x-qpid-replay-period : '3600' } } } } + + + Binding URL + direct://amq.direct/myqueue/myqueue?x-qpid-replay-period='3600' + + + +
+
+
+ Setting a default filter + A common case might be that the desired default behaviour is that newly attached consumers + see only newly arriving messages (i.e. standard topic-like behaviour) but other consumers + may wish to start their message stream from some point in the past. This can be achieved by + setting a default filter on the queue so that consumers which do not explicitly set a replay + period get a default (in this case the desired default would be 0). + The default filter set for a queue can be set via the REST API using the attribute named + defaultFilters. This value is a map from filter name to type and arguments. + To set the default behaviour for the queue to be that consumers only receive newly arrived + messages, then you should set this attribute to the value: + + { "x-qpid-replay-period" : { [ "x-qpid-replay-period", "0" ] } } + + + If the desired default behaviour is that each consumer should see all messages arriving in + the last minute, as well as all new messages then the value would need to be: + + { "x-qpid-replay-period" : { [ "x-qpid-replay-period", "60" ] } } + + +
+ + +
+
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml index 66755f718f..8fd11e6803 100644 --- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml @@ -33,64 +33,23 @@ Types The Broker supports four different queue types, each with different delivery semantics. - Standard - a simple First-In-First-Out (FIFO) queue - Priority - delivery order depends on the priority of each message - Sorted - + Sorted - delivery order depends on the value of the sorting key property in each message - Last Value + Last Value Queue - also known as an LVQ, retains only the last (newest) message received with a given LVQ key value -
- Standard - A simple First-In-First-Out (FIFO) queue -
-
- Priority - In a priority queue, messages on the queue are delivered in an order determined by the - JMS priority message - header within the message. By default Qpid supports the 10 priority levels - mandated by JMS, with priority value 0 as the lowest priority and 9 as the highest. - It is possible to reduce the effective number of priorities if desired. - JMS defines the - default message priority as 4. Messages sent without a specified priority use this - default. -
-
- Sorted Queues - Sorted queues allow the message delivery order to be determined by value of an arbitrary - JMS message - property. Sort order is alpha-numeric and the property value must have a type - java.lang.String. - Messages sent to a sorted queue without the specified JMS message property will be - inserted into the 'last' position in the queue. -
-
- Last Value Queues (LVQ) - LVQs (or conflation queues) are special queues that automatically discard any message - when a newer message arrives with the same key value. The key is specified by arbitrary - JMS message - property. - An example of an LVQ might be where a queue represents prices on a stock exchange: when - you first consume from the queue you get the latest quote for each stock, and then as new - prices come in you are sent only these updates. - Like other queues, LVQs can either be browsed or consumed from. When browsing an - individual subscriber does not remove the message from the queue when receiving it. This - allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and - bind a separate LVQ for each subscriber who wishes to receive the contents of the - LVQ). - Messages sent to an LVQ without the specified property will be delivered as normal and - will never be "replaced". -
Attributes @@ -101,10 +60,10 @@ Type of the queue. Can be either standard, priority, sorted, or lvq. + linkend="Java-Broker-Concepts-Queues-Types-Standard">standard, priority, sorted, or lvq. Durable. Whether the queue survives a restart. Messages on a @@ -140,7 +99,7 @@ Message Groups. See + linkend="Java-Broker-Concepts-Queues-Message-Grouping"/>
@@ -158,167 +117,5 @@ Lifecycle Not supported -
- Queue Declare Arguments - To create a priority, sorted or LVQ queue programmatically from JMX or AMQP, pass the - appropriate queue-declare arguments. - - Queue-declare arguments understood for priority, sorted and LVQ queues - - - - Queue type - Argument name - Argument name - Argument Description - - - - - priority - x-qpid-priorities - java.lang.Integer - Specifies a priority queue with given number priorities - - - sorted - qpid.queue_sort_key - java.lang.String - Specifies sorted queue with given message property used to sort the - entries - - - lvq - qpid.last_value_queue_key - java.lang.String - Specifies lvq queue with given message property used to conflate the - entries - - - -
-
- -
- Messaging Grouping - The broker allows messaging applications to classify a set of related messages as - belonging to a group. This allows a message producer to indicate to the consumer that a group - of messages should be considered a single logical operation with respect to the application. - The broker can use this group identification to enforce policies controlling how messages - from a given group can be distributed to consumers. For instance, the broker can be configured - to guarantee all the messages from a particular group are processed in order across multiple - consumers. - For example, assume we have a shopping application that manages items in a virtual - shopping cart. A user may add an item to their shopping cart, then change their mind and - remove it. If the application sends an add message to the broker, - immediately followed by a remove message, they will be queued in the - proper order - add, followed by remove. - However, if there are multiple consumers, it is possible that once a consumer acquires - the add message, a different consumer may acquire the - remove message. This allows both messages to be processed in parallel, - which could result in a "race" where the remove operation is incorrectly - performed before the add operation. -
- Grouping Messages - In order to group messages, the application would designate a particular message header - as containing a message's group identifier. The group identifier stored - in that header field would be a string value set by the message producer. Messages from the - same group would have the same group identifier value. The key that identifies the header - must also be known to the message consumers. This allows the consumers to determine a - message's assigned group. - The header that is used to hold the group identifier, as well as the values used as - group identifiers, are totally under control of the application. -
-
- The Role of the Broker in Message Grouping - The broker will apply the following processing on each grouped message: - - Enqueue a received message on the destination queue. - - - Determine the message's group by examining the message's group identifier - header. - - - Enforce consumption ordering among messages belonging to the - same group. Consumption ordering means one of two things - depending on how the queue has been configured. - - - In default mode, a group gets assigned to a single consumer for the lifetime - of that consumer, and the broker will pass all subsequent messages in the group to - that consumer. - - - In 'shared groups' mode (which gives the same behaviour as the Qpid C++ - Broker) the broker enforces a looser guarantee, namely that all the - currently unacknowledged messages in a group are sent to - the same consumer, but the consumer used may change over time even if the - consumers do not. This means that only one consumer can be processing messages - from a particular group at any given time, however if the consumer acknowledges - all of its acquired messages then the broker may pass the - next pending message in that group to a different consumer. - - - - - - The absence of a value in the designated group header field of a message is treated as - follows: - - In default mode, failure for a message to specify a group is treated as a desire - for the message not to be grouped at all. Such messages will be distributed to any - available consumer, without the ordering quarantees imposed by grouping. - - - In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker) - the broker assigns messages without a group value to a 'default group'. Therefore, all - such "unidentified" messages are considered by the broker as part of the same group, - which will handled like any other group. The name of this default group is - "qpid.no-group", although it can be customised as detailed below. - - - - Note that message grouping has no effect on queue browsers. - Note well that distinct message groups would not block each other from delivery. For - example, assume a queue contains messages from two different message groups - say group "A" - and group "B" - and they are enqueued such that "A"'s messages are in front of "B". If the - first message of group "A" is in the process of being consumed by a client, then the - remaining "A" messages are blocked, but the messages of the "B" group are available for - consumption by other consumers - even though it is "behind" group "A" in the queue. -
- -
-
- Using low pre-fetch with special queue types - Qpid clients receive buffered messages in batches, sized according to the pre-fetch value. - The current default is 500. - However, if you use the default value you will probably not see - desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has - sent a message to the client its delivery order is then fixed, regardless of the special - behaviour of the queue. - For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with - priority 2, the broker will send these messages to the client. If then a new message arrives - will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will - be delivered at the front of the next batch of messages to be sent to the client. - So, you need to set the prefetch values for your client (consumer) to make this sensible. - To do this set the Java system property max_prefetch on the client - environment (using -D) before creating your consumer. - A default for all client connections can be set via a system property: - --Dmax_prefetch=1 - - The prefetch can be also be adjusted on a per connection basis by adding a - maxprefetch value to the Connection URLs - - -amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672' - - Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the - client however, this brings a performance cost. You could test with a slightly higher - pre-fetch to trade-off between throughput and exact semantics. -
- -- cgit v1.2.1