You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ro...@apache.org on 2012/11/25 22:12:32 UTC

svn commit: r1413422 [12/19] - in /qpid/site/docs/books/0.20: ./ AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html/ AMQP-Messaging-Broker-CPP-Book/html/css/ AMQP-Messaging-Broker-CPP-Book/html/images/ AMQP-Messaging-Broker-CPP-Book/pd...

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues-OtherTypes.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues-OtherTypes.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues-OtherTypes.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues-OtherTypes.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1,113 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>7.2. Other Queue Types</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="Java-Broker-Queues.html" title="Chapter 7. Queues"><link rel="prev" href="Java-Broker-Queues.html" title="Chapter 7. Queues"><link rel="next" href="Java-Broker-Stores.html" title="Chapter 8. Stores"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.
 html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A>
 </LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.
 apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-link"><a href="Java-Broker-Queues.html">Queues</a></span> &gt; <span class="breadcrumb-node">Other Queue Types</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Queues-OtherTypes"></a>7.2. Other Queue Types</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-Introduction"></a>7.2.1. Introduction</h3></div></div></div><p> In addition
  to the standard queue type where messages are delivered in the same order
+      that they were sent, the Java Broker supports three additional queue types which allows for
+      alternative delivery behaviours. These are <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Priority" title="7.2.2. Priority Queues">priority-queues</a>, <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Sorted" title="7.2.3. Sorted Queues">sorted-queues</a>-, and
+        <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-LVQ" title="7.2.4. Last Value Queues (LVQ)">last-value-queues</a> (LVQs). </p><p> In the following sections, the semantics of each queue type is described, followed by a
+      description of how instances of these queue can be created via <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-CreateUsingConfig" title="7.2.5.1. Using configuration">configuration</a> or <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx" title="7.2.5.2. Using JMX or AMQP">programmatically</a>. </p><p>The final section discusses the importance of using a <a class="link" href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-SetLowPrefetch" title="7.2.6. Low pre-fetch">low client pre-fetch</a> with these queued.
+    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-Priority"></a>7.2.2. Priority Queues</h3></div></div></div><p>In a priority queue, messages on the queue are delivered in an order determined by the
+        <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSPriority()" target="_top">JMS priority message
+        header</a> 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. </p><p>It is possible to reduce the effective number of priorities if desired.</p><p>JMS defines the <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#DEFAULT_PRIORITY" target="_top">
+        default message priority</a> as 4. Messages sent without a specified priority use this
+      default. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-Sorted"></a>7.2.3. Sorted Queues</h3></div></div></div><p>Sorted queues allow the message delivery order to be determined by value of an arbitrary
+        <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getStringProperty()" target="_top">JMS message
+        property</a>. Sort order is alpha-numeric and the property value must have a type
+      java.lang.String.</p><p>Messages sent to a sorted queue without the specified JMS message property will be
+      inserted into the 'last' position in the queue.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-LVQ"></a>7.2.4. Last Value Queues (LVQ)</h3></div></div></div><p>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 <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getPropertyNames()" target="_top">JMS message
+        property</a>.</p><p>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. </p><p>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).</p><p>Messages sent to an LVQ without the specified property will be delivered as normal and
+      will never be "replaced".</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-Create"></a>7.2.5. Creating a Priority, Sorted or LVQ Queue</h3></div></div></div><p>To create a priority, sorted or LVQ queue, it can be defined in the virtualhost
+      configuration file, or the queue can be created programmtically from a client via AMQP (using
+      an extension to JMS), or using JMX. These methods are described below. </p><p>Once a queue is created you cannot change its type (without deleting it and re-creating).
+      Also note you cannot currently mix the natures of these queue types, for instance, you cannot
+      define a queue which it both an LVQ and a priority-queue.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Queues-OtherTypes-CreateUsingConfig"></a>7.2.5.1. Using configuration</h4></div></div></div><p>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml
+        to the virtualhost.xml configuration file within the <code class="varname">queues</code>
+        element.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Priority"></a>Priority</h5></div></div></div><p> To defining a priority queue, add a &lt;priority&gt;true&lt;/priority&gt; element. By
+          default the queue will have 10 distinct priorities. </p><div class="example"><a name="id2492825"></a><p class="title"><b>Example 7.1. Configuring a priority queue</b></p><div class="example-contents"><pre class="programlisting">&lt;queue&gt;
+    &lt;name&gt;myqueue&lt;/name&gt;
+    &lt;myqueue&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;priority&gt;true&lt;/priority&gt;
+    &lt;/myqueue&gt;
+&lt;/queue&gt;</pre></div></div><br class="example-break"><p> If you require fewer priorities, it is possible to specify a
+            <code class="varname">priorities</code> element (whose value is a integer value between 2 and 10
+          inclusive) which will give the queue that number of distinct priorities. When messages are
+          sent to that queue, their effective priority will be calculated by partitioning the
+          priority space. If the number of effective priorities is 2, then messages with priority
+          0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated
+          equivalently as "higher priority". </p><div class="example"><a name="id2495190"></a><p class="title"><b>Example 7.2. Configuring a priority queue with fewer priorities</b></p><div class="example-contents"><pre class="programlisting">&lt;queue&gt;
+    &lt;name&gt;myqueue&lt;/name&gt;
+    &lt;myqueue&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;priority&gt;true&lt;/priority&gt;
+        &lt;priorities&gt;4&lt;/priorities&gt;
+    &lt;/myqueue&gt;
+&lt;/queue&gt;</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Sorted"></a>Sorted</h5></div></div></div><p> To define a sorted queue, add a <code class="varname">sortKey</code> element. The value of the
+            <code class="varname">sortKey</code> element defines the message property to use the value of when
+          sorting the messages put onto the queue. </p><div class="example"><a name="id2495228"></a><p class="title"><b>Example 7.3. Configuring a sorted queue</b></p><div class="example-contents"><pre class="programlisting">&lt;queue&gt;
+    &lt;name&gt;myqueue&lt;/name&gt;
+    &lt;myqueue&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;sortKey&gt;message-property-to-sort-by&lt;/sortKey&gt;
+    &lt;/myqueue&gt;
+&lt;/queue&gt;</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="Java-Broker-Queues-OtherTypes-CreateUsingConfig-LVQ"></a>LVQ</h5></div></div></div><p> To define a LVQ, add a <code class="varname">lvq</code> element with the value
+            <code class="constant">true</code>. Without any further configuration this will define an LVQ
+          which uses the JMS message property <code class="constant">qpid.LVQ_key</code> as the key for
+          replacement. </p><div class="example"><a name="id2495407"></a><p class="title"><b>Example 7.4. Configuring a LVQ queue</b></p><div class="example-contents"><pre class="programlisting">&lt;queue&gt;
+    &lt;name&gt;myqueue&lt;/name&gt;
+    &lt;myqueue&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;lvq&gt;true&lt;/lvq&gt;
+    &lt;/myqueue&gt;
+&lt;/queue&gt;</pre></div></div><br class="example-break"><p> If you wish to define your own property then you can do so using the
+            <code class="varname">lvqKey</code> element.</p><div class="example"><a name="id2495426"></a><p class="title"><b>Example 7.5. Configuring a LVQ queue with custom message property name</b></p><div class="example-contents"><pre class="programlisting">&lt;queue&gt;
+    &lt;name&gt;myqueue&lt;/name&gt;
+    &lt;myqueue&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;lvq&gt;true&lt;/lvq&gt;
+        &lt;lvqKey&gt;ISIN&lt;/lvqKey&gt;
+    &lt;/myqueue&gt;
+&lt;/queue&gt;</pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx"></a>7.2.5.2. Using JMX or AMQP</h4></div></div></div><p>To create a priority, sorted or LVQ queue programmatically from JMX or using a Qpid
+        extension to JMS, pass the appropriate queue-declare arguments.</p><div class="table"><a name="id2495459"></a><p class="title"><b>Table 7.1. Queue-declare arguments understood for priority, sorted and LVQ queues</b></p><div class="table-contents"><table summary="Queue-declare arguments understood for priority, sorted and LVQ queues" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Queue type</th><th>Argument name</th><th>Argument name</th><th>Argument Description</th></tr></thead><tbody><tr><td>priority</td><td>priorities</td><td>java.lang.Integer</td><td>Specifies a priority queue with given number priorities</td></tr><tr><td>sorted</td><td>qpid.queue_sort_key</td><td>java.lang.String</td><td>Specifies sorted queue with given message property used to sort the
+                entries</td></tr><tr><td>lvq</td><td>qpid.last_value_queue_key</td><td>java.lang.String</td><td>Specifies lvq queue with given message property used to conflate the
+                entries</td></tr></tbody></table></div></div><br class="table-break"><p>The following example illustrates the creation of the a LVQ queue from a
+        javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and
+        involves casting the session object back to its Qpid base-class.</p><div class="example"><a name="id2494793"></a><p class="title"><b>Example 7.6. Creation of an LVQ using the Qpid extension to JMS</b></p><div class="example-contents"><pre class="programlisting">Map&lt;String,Object&gt; arguments = new HashMap&lt;String, Object&gt;();
+arguments.put("qpid.last_value_queue_key","ISIN");
+((AMQSession&lt;?,?&gt;) session).createQueue(queueName, autoDelete, durable, exclusive, arguments);</pre></div></div><br class="example-break"><p> The following example illustrates the creation of the sorted queue from a the JMX
+        interface using the ManagedBroker interface. </p><div class="example"><a name="id2494813"></a><p class="title"><b>Example 7.7. Creation of a sorted queue using JMX</b></p><div class="example-contents"><pre class="programlisting">Map&lt;String, Object&gt; environment = new HashMap&lt;String, Object&gt;();
+environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"});
+// Connect to service
+JMXServiceURL url =  new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi");
+JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);
+MBeanServerConnection mbsc =  jmxConnector.getMBeanServerConnection();
+// Object name for ManagedBroker for virtualhost myvhost
+ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=myvhost");
+// Get the ManagedBroker object
+ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);;
+
+// Create the queue passing arguments
+Map&lt;String,Object&gt; arguments = new HashMap&lt;String, Object&gt;();
+arguments.put("qpid.queue_sort_key","myheader");
+managedBroker.createNewQueue("myqueue", null, true, arguments);</pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Queues-OtherTypes-SetLowPrefetch"></a>7.2.6. Low pre-fetch</h3></div></div></div><p>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value.
+      The current default is 500. </p><p>However, if you use the default value you will probably <span class="emphasis"><em>not</em></span> see
+      desirable behaviour when using priority, sorted or lvq 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. </p><p>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.</p><p> So, you need to set the prefetch values for your client (consumer) to make this sensible.
+      To do this set the Java system property <code class="varname">max_prefetch</code> on the client
+      environment (using -D) before creating your consumer. </p><p>A default for all client connections can be set via a system property: </p><pre class="programlisting">
+-Dmax_prefetch=1
+</pre><p> The prefetch can be also be adjusted on a per connection basis by adding a
+      <code class="varname">maxprefetch</code> value to the <a class="ulink" href="../../Programming-In-Apache-Qpid/html/QpidJNDI.html#section-jms-connection-url" target="_top">Connection URLs</a>
+    </p><pre class="programlisting">
+amqp://guest:guest@client1/development?maxprefetch='1'&amp;brokerlist='tcp://localhost:5672'
+</pre><p>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.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Queues.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Java-Broker-Queues.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Stores.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Queues </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Stores</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Queues.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 7. Queues</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="prev" href="Java-Broker-Exchanges.html" title="Chapter 6. Exchanges"><link rel="next" href="Java-Broker-Queues-OtherTypes.html" title="7.2. Other Queue Types"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/
 download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing 
 Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="ht
 tp://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-node">Queues</span></DIV><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Queues"></a>Chapter 7. Queues</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="Java-Broker-Queues.html#Queues-Messaging-Groups">7.1. Messaging Groups</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html">7.2. Other Queue Types</a></span></dt><dd><dl><dt><span c
 lass="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Introduction">7.2.1. Introduction</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Priority">7.2.2. Priority Queues</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Sorted">7.2.3. Sorted Queues</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-LVQ">7.2.4. Last Value Queues (LVQ)</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-Create">7.2.5. Creating a Priority, Sorted or LVQ Queue</a></span></dt><dt><span class="section"><a href="Java-Broker-Queues-OtherTypes.html#Java-Broker-Queues-OtherTypes-SetLowPrefetch">7.2.6. Low pre-fetch</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div>
 <h2 class="title"><a name="Queues-Messaging-Groups"></a>7.1. Messaging Groups</h2></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Exchanges.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Queues-OtherTypes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Exchanges </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7.2. Other Queue Types</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Alerts.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Alerts.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Alerts.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Alerts.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>11.2. Alerts</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="Java-Broker-Runtime.html" title="Chapter 11. Runtime"><link rel="prev" href="Java-Broker-Runtime.html" title="Chapter 11. Runtime"><link rel="next" href="Java-Broker-Runtime-Disk-Space-Management.html" title="11.3. Disk Space Management"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http:/
 /qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lis
 ts.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></L
 I><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-link"><a href="Java-Broker-Runtime.html">Runtime</a></span> &gt; <span class="breadcrumb-node">Alerts</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Runtime-Alerts"></a>11.2. Alerts</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Runtime.html">Prev</a> </td><td width
 ="20%" align="center"><a accesskey="u" href="Java-Broker-Runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Runtime-Disk-Space-Management.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Runtime </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 11.3. Disk Space Management</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Disk-Space-Management.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Disk-Space-Management.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Disk-Space-Management.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime-Disk-Space-Management.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1,132 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>11.3. Disk Space Management</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="Java-Broker-Runtime.html" title="Chapter 11. Runtime"><link rel="prev" href="Java-Broker-Runtime-Alerts.html" title="11.2. Alerts"><link rel="next" href="Java-Broker-High-Availability.html" title="Chapter 12. High Availability"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="h
 ttp://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailin
 g_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</
 A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-link"><a href="Java-Broker-Runtime.html">Runtime</a></span> &gt; <span class="breadcrumb-node">Disk Space Management</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Runtime-Disk-Space-Management"></a>11.3. Disk Space Management</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Qpid-Producer-Flow-Control"></a>11.3.1. Producer Fl
 ow Control</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-GeneralInformation"></a>11.3.1.1. General Information</h4></div></div></div><p>
+            The Qpid 0.6 release introduced a simplistic producer-side flow control mechanism
+            into the Java Messaging Broker, causing producers to be flow-controlled when they
+            attempt to send messages to an overfull queue. Qpid 0.18 introduced a similar
+            mechanism triggered by an overfull persistent message store on a virtual host.
+        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-ServerConfiguration"></a>11.3.1.2. Server Configuration</h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="id2492591"></a>Configuring a Queue to use flow control</h5></div></div></div><p>
+                Flow control is enabled on a producer when it sends a message to a Queue
+                which is "overfull". The producer flow control will be rescinded when all
+                Queues on which a producer is blocking become "underfull". A Queue is defined
+                as overfull when the size (in bytes) of the messages on the queue exceeds the
+                "capacity" of the Queue. A Queue becomes "underfull" when its size becomes
+                less than the "flowResumeCapacity".
+
+
+             </p><div class="example"><a name="id2492610"></a><p class="title"><b>Example 11.1. Configuring a queue depth limit</b></p><div class="example-contents"><pre class="programlisting">
+                
+&lt;queue&gt;
+    &lt;name&gt;test&lt;/name&gt;
+    &lt;test&gt;
+        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+        &lt;capacity&gt;10485760&lt;/capacity&gt;                     &lt;!-- set the queue capacity to 10Mb --&gt;
+        &lt;flowResumeCapacity&gt;8388608&lt;/flowResumeCapacity&gt;  &lt;!-- set the resume capacity to 8Mb --&gt;
+    &lt;/test&gt;
+&lt;/queue&gt;
+                
+                </pre></div></div><p><br class="example-break">
+
+                The default for all queues on a virtual host can also be set
+
+             </p><div class="example"><a name="id2492627"></a><p class="title"><b>Example 11.2. Configuring a default queue depth limit on a virtualhost</b></p><div class="example-contents"><pre class="programlisting">
+                
+&lt;virtualhosts&gt;
+    &lt;virtualhost&gt;
+        &lt;name&gt;localhost&lt;/name&gt;
+        &lt;localhost&gt;
+            &lt;capacity&gt;10485760&lt;/capacity&gt;                     &lt;!-- set the queue capacity to 10Mb --&gt;
+            &lt;flowResumeCapacity&gt;8388608&lt;/flowResumeCapacity&gt;  &lt;!-- set the resume capacity to 8Mb --&gt;
+        &lt;/localhost&gt;
+    &lt;/virtualhost&gt;
+&lt;/virtualhosts&gt;
+                
+                </pre></div></div><p><br class="example-break">
+
+                Where no flowResumeCapacity is set, the flowResumeCapacity is set to be equal
+                to the capacity. Where no capacity is set, capacity is defaulted to 0 meaning
+                there is no capacity limit.
+            </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="id2492650"></a>Broker Log Messages</h6></div></div></div><p>
+                    There are four new Broker log messages that may occur if flow control through queue capacity limits is enabled.
+                    Firstly, when a capacity limited queue becomes overfull, a log message similar to the following is produced
+                </p><pre class="programlisting">
+MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1003 : Overfull : Size : 1,200 bytes, Capacity : 1,000
+                </pre><p>Then for each channel which becomes blocked upon the overful queue a log message similar to the following is produced:</p><pre class="programlisting">
+MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1] CHN-1005 : Flow Control Enforced (Queue MyQueue)
+                </pre><p>When enough messages have been consumed from the queue that it becomes underfull, then the following log is generated: </p><pre class="programlisting">
+MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1004 : Underfull : Size : 600 bytes, Resume Capacity : 800
+                </pre><p>And for every channel which becomes unblocked you will see a message similar to: </p><pre class="programlisting">
+MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1] CHN-1006 : Flow Control Removed
+                </pre><p>Obviously the details of connection, virtual host, queue, size, capacity, etc would depend on the configuration in use.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="id2494513"></a>Disk quota-based flow control</h5></div></div></div><p>
+                Since version 0.18 of Qpid Broker, flow control can be triggered when a
+                configured disk quota is exceeded. This is supported by the BDB and Derby message stores.
+            </p><p>
+                This functionality blocks all producers on reaching the disk overflow limit. When consumers
+                consume the messages, causing disk space usage to falls below the underflow limit, the
+                producers are unblocked and continue working as normal.
+            </p><p>
+                Two limits can be configured:
+            </p><p>
+                overfull limit - the maximum space on disk (in bytes) which can be used by store.
+            </p><p>
+                underfull limit - when the space on disk drops below this limit, producers are allowed to resume publishing.
+            </p><p>
+                An example of quota configuration for the BDB message store is provided below.
+            </p><div class="example"><a name="id2494559"></a><p class="title"><b>Example 11.3. Configuring a limit on a store</b></p><div class="example-contents"><pre class="programlisting">
+            
+&lt;store&gt;
+   &lt;class&gt;org.apache.qpid.server.store.berkeleydb.BDBMessageStore&lt;/class&gt;
+   &lt;environment-path&gt;${work}/bdbstore/test&lt;/environment-path&gt;
+   &lt;overfull-size&gt;50000000&lt;/overfull-size&gt;
+   &lt;underfull-size&gt;45000000&lt;/underfull-size&gt;
+&lt;/store&gt;
+            
+            </pre></div></div><br class="example-break"><p>
+                The disk quota functionality is based on "best effort" principle. This means the broker
+                cannot guarantee that the disk space limit will not be exceeded. If several concurrent
+                transactions are started before the limit is reached, which collectively cause the limit
+                to be exceeded, the broker may allow all of them to be committed.
+            </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="id2494585"></a>Broker Log Messages for quota flow control</h6></div></div></div><p>
+                    There are 2 new broker log messages that may occur if flow control through disk quota limits is enabled.
+                    When the virtual host is blocked due to exceeding of the disk quota limit the following message
+                    appears in the broker log
+                    </p><pre class="programlisting">
+[vh(/test)/ms(BDBMessageStore)] MST-1008 : Store overfull, flow control will be enforced
+                    </pre><p>
+                    When virtual host is unblocked after cleaning the disk space the following message appears in the broker log
+                    </p><pre class="programlisting">
+[vh(/test)/ms(BDBMessageStore)] MST-1009 : Store overfull condition cleared
+                    </pre><p>
+                </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-ClientImpact"></a>11.3.1.3. Client impact and configuration</h4></div></div></div><p>
+            If a producer sends to a queue which is overfull, the broker will respond by
+            instructing the client not to send any more messages. The impact of this is
+            that any future attempts to send will block until the broker rescinds the flow control order.
+        </p><p>
+            While blocking the client will periodically log the fact that it is blocked waiting on flow control.
+        </p><pre class="programlisting">
+WARN   Message send delayed by 5s due to broker enforced flow control
+WARN   Message send delayed by 10s due to broker enforced flow control
+        </pre><p>
+            After a set period the send will timeout and throw a JMSException to the calling code.
+        </p><p>
+            If such a JMSException is thrown, the message will not be sent to the broker,
+            however the underlying Session may still be active - in particular if the
+            Session is transactional then the current transaction will not be automatically
+            rolled back. Users may choose to either attempt to resend the message, or to
+            roll back any transactional work and close the Session.
+        </p><p>
+            Both the timeout delay and the periodicity of the warning messages can be set
+            using Java system properties.
+        </p><p>
+            The amount of time (in milliseconds) to wait before timing out
+            is controlled by the property qpid.flow_control_wait_failure.
+        </p><p>
+            The frequency at which the log message informing that the producer is flow
+            controlled is sent is controlled by the system property qpid.flow_control_wait_notify_period.
+        </p><p>
+            Adding the following to the command line to start the client would result in a timeout of one minute,
+            with warning messages every ten seconds:
+        </p><pre class="programlisting">
+-Dqpid.flow_control_wait_failure=60000
+-Dqpid.flow_control_wait_notify_period=10000
+        </pre><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="id2496151"></a>Older Clients</h5></div></div></div><p>
+                The flow control feature was first added to the Java broker/client in the 0.6 release. If an older client connects to the broker then the flow control commands will be ignored by it and it will not be blocked. So to fully benefit from this feature both Client and Broker need to be at least version 0.6.
+            </p></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Runtime-Alerts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Java-Broker-Runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-High-Availability.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.2. Alerts </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. High Availability</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Runtime.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 11. Runtime</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="prev" href="Java-Broker-Security-SSL.html" title="10.5. SSL"><link rel="next" href="Java-Broker-Runtime-Alerts.html" title="11.2. Alerts"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.html">Downloa
 d</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A h
 ref="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.apache.org/fo
 undation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-node">Runtime</span></DIV><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Runtime"></a>Chapter 11. Runtime</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="Java-Broker-Runtime.html#Java-Broker-Runtime-Log-Files">11.1. Log Files</a></span></dt><dt><span class="section"><a href="Java-Broker-Runtime-Alerts.html">11.2. Alerts</a></span></dt><dt><span class="section"><a href="Java-Broker-Ru
 ntime-Disk-Space-Management.html">11.3. Disk Space Management</a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Runtime-Disk-Space-Management.html#Qpid-Producer-Flow-Control">11.3.1. Producer Flow Control</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Runtime-Log-Files"></a>11.1. Log Files</h2></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Security-SSL.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Runtime-Alerts.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.5. SSL </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 11.2. Alerts</td></t
 r></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Security-ACLs.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Security-ACLs.html?rev=1413422&view=auto
==============================================================================
--- qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Security-ACLs.html (added)
+++ qpid/site/docs/books/0.20/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Security-ACLs.html Sun Nov 25 21:12:24 2012
@@ -0,0 +1,232 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>10.4. Access Control Lists</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Java)"><link rel="up" href="Java-Broker-Security.html" title="Chapter 10. Security"><link rel="prev" href="Java-Broker-Security-Authentication-Providers.html" title="10.3. Authentication Providers"><link rel="next" href="Java-Broker-Security-SSL.html" title="10.5. SSL"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI>
 <A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">Latest Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.
 org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.o
 rg">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Java)</a></span> &gt; <span class="breadcrumb-link"><a href="Java-Broker-Security.html">Security</a></span> &gt; <span class="breadcrumb-node">Access Control Lists</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Java-Broker-Security-ACLs"></a>10.4. Access Control Lists</h2></div></div></div><p>
+    In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user.
+    To enable, the &lt;acl/&gt; element is used within the &lt;security/&gt; element of the configuration XML.
+    In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual
+    hosts.  The  &lt;acl/&gt; configuration references a text file containing the ACL rules.
+    By convention, this file should have a .acl extension.
+  </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Security-ACLs-EnablingACL"></a>10.4.1. 
+       Enabling ACLs
+    </h3></div></div></div><p>
+      To apply an ACL broker-wide, add the following to the config.xml (assuming that <em class="replaceable"><code>conf</code></em> has been set to a suitable
+      location such as ${QPID_HOME}/etc):
+    </p><pre class="programlisting">
+      &lt;broker&gt;
+        ...
+        &lt;security&gt;
+          ...
+          &lt;acl&gt;<em class="replaceable"><code>${conf}/broker.acl</code></em>&lt;/acl&gt;
+        &lt;/security&gt;
+      &lt;/broker&gt;
+    </pre><p>
+    </p><p>
+      To apply an ACL on a single virtualhost named <em class="replaceable"><code>test</code></em>, add the following to the config.xml:
+    </p><pre class="programlisting">
+      &lt;virtualhost&gt;
+        ...
+        &lt;name&gt;test&lt;/name&gt;
+        &lt;test&gt;
+          ...
+          &lt;security&gt;
+            &lt;acl&gt;<em class="replaceable"><code>${conf}/vhost_test.acl</code></em>&lt;/acl&gt;
+          &lt;/security&gt;
+        &lt;/test&gt;
+      &lt;/virtualhost&gt;
+    </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Security-ACLs-WriteACL"></a>10.4.2. 
+       Writing .acl files
+    </h3></div></div></div><p>
+      The ACL file consists of a series of rules associating behaviour for a user or group. Use of groups can serve to make the ACL file more concise. See <a class="link" href="Java-Broker-Security-Group-Providers.html" title="10.2. Configuring Group Providers">Configuring Group Providers</a> for more information on defining groups.
+    </p><p>
+      Each ACL rule grants or denies a particular action on an object to a user/group.  The rule may be augmented with one or more properties, restricting
+      the rule's applicability.
+    </p><pre class="programlisting">
+      ACL ALLOW alice CREATE QUEUE              # Grants alice permission to create all queues.
+      ACL DENY bob CREATE QUEUE name="myqueue"  # Denies bob permission to create a queue called "myqueue"
+    </pre><p>
+      The ACL is considered in strict line order with the first matching rule taking precedence over all those that follow. In the following
+      example, if the user bob tries to create an exchange "myexch", the operation will be allowed by the first rule.  The second rule will
+      never be considered.
+    </p><pre class="programlisting">
+      ACL ALLOW bob ALL EXCHANGE
+      ACL DENY bob CREATE EXCHANGE name="myexch"  # Dead rule
+    </pre><p>
+      If the desire is to allow bob to create all exchanges except "myexch", order of the rules must be reversed:
+    </p><pre class="programlisting">
+      ACL DENY bob CREATE EXCHANGE name="myexch"
+      ACL ALLOW bob ALL EXCHANGE
+    </pre><p>
+      All ACL files end with an implict rule denying all operations to all users.  It is as if each file ends with
+      </p><pre class="programlisting">ACL DENY ALL ALL </pre><p>
+      If instead you wish to <span class="emphasis"><em>allow</em></span> all operations other than those controlled by earlier rules,
+      add </p><pre class="programlisting">ACL ALLOW ALL ALL</pre><p> to the bottom of the ACL file.
+    </p><p>
+      When writing a new ACL, a good approach is to begin with an .acl file containing only </p><pre class="programlisting">ACL DENY-LOG ALL ALL</pre><p>
+      which will cause the Broker to deny all operations with details of the denial logged to the Qpid log file. Build up the ACL rule by rule,
+      gradually working through the use-cases of your system.  Once the ACL is complete, consider switching the DENY-LOG actions to DENY
+      to improve performamce and reduce log noise.
+    </p><p>
+      ACL rules are very powerful: it is possible to write very granular rules specifying many broker objects and their
+      properties.  Most projects probably won't need this degree of flexibility.  A reasonable approach is to choose to apply permissions
+      at a certain level of abstraction (e.g. QUEUE) and apply them consistently across the whole system.
+    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Security-ACLs-Syntax"></a>10.4.3. 
+       Syntax
+    </h3></div></div></div><p>
+       ACL rules follow this syntax:
+    </p><pre class="programlisting">
+     ACL {permission} {&lt;group-name&gt;|&lt;user-name&gt;&gt;|ALL} {action|ALL} [object|ALL] [property="&lt;property-value&gt;"]
+    </pre><p>
+       Comments may be introduced with the hash (#) character and are ignored.  Long lines can be broken with the slash (\) character.
+    </p><pre class="programlisting">
+      # A comment
+      ACL ALLOW admin CREATE ALL # Also a comment
+      ACL DENY guest \
+      ALL ALL   # A broken line
+    </pre></div><div class="table"><a name="table-Java-Broker-Security-ACLs-Syntax_permissions"></a><p class="title"><b>Table 10.1. List of ACL permission</b></p><div class="table-contents"><table summary="List of ACL permission" border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="command"><strong>ALLOW</strong></span></td><td><p>Allow the action</p></td></tr><tr><td><span class="command"><strong>ALLOW-LOG</strong></span></td><td><p> Allow the action and log the action in the log </p></td></tr><tr><td><span class="command"><strong>DENY</strong></span></td><td><p> Deny the action</p></td></tr><tr><td><span class="command"><strong>DENY-LOG</strong></span></td><td><p> Deny the action and log the action in the log</p></td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-Java-Broker-Security-ACLs-Syntax_actions"></a><p class="title"><b>Table 10.2. List of ACL actions</b></p><div class="table-contents"><table 
 summary="List of ACL actions" border="1"><colgroup><col><col></colgroup><tbody><tr><td> <span class="command"><strong>CONSUME</strong></span> </td><td> <p> Applied when subscriptions are created </p> </td></tr><tr><td> <span class="command"><strong>PUBLISH</strong></span> </td><td> <p> Applied on a per message basis on publish message transfers</p> </td></tr><tr><td> <span class="command"><strong>CREATE</strong></span> </td><td> <p> Applied when an object is created, such as bindings, queues, exchanges</p> </td></tr><tr><td> <span class="command"><strong>ACCESS</strong></span> </td><td> <p> Applied when an object is read or accessed</p> </td></tr><tr><td> <span class="command"><strong>BIND</strong></span> </td><td> <p> Applied when queues are bound to exchanges</p> </td></tr><tr><td> <span class="command"><strong>UNBIND</strong></span> </td><td> <p> Applied when queues are unbound from exchanges</p> </td></tr><tr><td> <span class="command"><strong>DELETE</strong></span> </td
 ><td> <p> Applied when objects are deleted </p> </td></tr><tr><td> <span class="command"><strong>PURGE</strong></span> </td><td>
+          <p>Applied when purge the contents of a queue</p> </td></tr><tr><td> <span class="command"><strong>UPDATE</strong></span> </td><td> <p> Applied when an object is updated </p> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-Java-Broker-Security-ACLs-Syntax_objects"></a><p class="title"><b>Table 10.3. List of ACL objects</b></p><div class="table-contents"><table summary="List of ACL objects" border="1"><colgroup><col><col></colgroup><tbody><tr><td> <span class="command"><strong>VIRTUALHOST</strong></span> </td><td> <p>A virtualhost (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>MANAGEMENT </strong></span> </td><td> <p>Management - for web and JMX (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>QUEUE</strong></span> </td><td> <p>A queue </p> </td></tr><tr><td> <span class="command"><strong>EXCHANGE</strong></span> </td><td> <p>An exchange </p> </td></tr><tr><td> <spa
 n class="command"><strong>USER</strong></span> </td><td> <p>A user (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>GROUP</strong></span> </td><td> <p>A group (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>METHOD</strong></span> </td><td> <p>Management or agent or broker method (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>LINK</strong></span> </td><td> <p>A federation or inter-broker link (not currently used in Java Broker)</p> </td></tr><tr><td> <span class="command"><strong>BROKER</strong></span> </td><td> <p>The broker (not currently used in Java Broker)</p> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-Java-Broker-Security-ACLs-Syntax_properties"></a><p class="title"><b>Table 10.4. List of ACL properties</b></p><div class="table-contents"><table summary="List of ACL properties" border="1"><colgroup><col><col></colgroup><tbody><tr><td><span cl
 ass="command"><strong>name</strong></span> </td><td> <p> String. Object name, such as a queue name, exchange name or JMX method name.  </p> </td></tr><tr><td> <span class="command"><strong>durable</strong></span> </td><td> <p> Boolean. Indicates the object is durable </p> </td></tr><tr><td> <span class="command"><strong>routingkey</strong></span> </td><td> <p> String. Specifies routing key </p> </td></tr><tr><td> <span class="command"><strong>passive</strong></span> </td><td> <p> Boolean. Indicates the presence of a <em class="parameter"><code>passive</code></em> flag </p> </td></tr><tr><td> <span class="command"><strong>autodelete</strong></span> </td><td> <p> Boolean. Indicates whether or not the object gets deleted when the connection is closed </p> </td></tr><tr><td> <span class="command"><strong>exclusive</strong></span> </td><td> <p> Boolean. Indicates the presence of an <em class="parameter"><code>exclusive</code></em> flag </p> </td></tr><tr><td> <span class="command
 "><strong>temporary</strong></span> </td><td> <p> Boolean. Indicates the presence of an <em class="parameter"><code>temporary</code></em> flag </p> </td></tr><tr><td> <span class="command"><strong>type</strong></span> </td><td> <p> String. Type of object, such as topic, fanout, or xml </p> </td></tr><tr><td> <span class="command"><strong>alternate</strong></span> </td><td> <p> String. Name of the alternate exchange </p> </td></tr><tr><td> <span class="command"><strong>queuename</strong></span> </td><td> <p> String. Name of the queue (used only when the object is something other than <em class="parameter"><code>queue</code></em> </p> </td></tr><tr><td> <span class="command"><strong>component</strong></span> </td><td> <p> String. JMX component name (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>schemapackage</strong></span> </td><td> <p> String. QMF schema package name (Not used in Java Broker)</p> </td></tr><tr><td> <span class="command"><strong>schem
 aclass</strong></span> </td><td> <p> String. QMF schema class name (Not used in Java Broker)</p> </td></tr><tr><td> <span class="command"><strong>from_network</strong></span> </td><td>
+            <p>
+              Comma-separated strings representing IPv4 address ranges.
+            </p>
+            <p>
+              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
+            </p>
+            <p>
+              The rule matches if any of the address ranges match the IPv4 address of the messaging client.
+              The address ranges are specified using either Classless Inter-Domain Routing notation
+              (e.g. 192.168.1.0/24; see <a class="ulink" href="http://tools.ietf.org/html/rfc4632" target="_top">RFC 4632</a>)
+              or wildcards (e.g. 192.169.1.*).
+            </p>
+            <p>
+              Java Broker only.
+            </p>
+          </td></tr><tr><td> <span class="command"><strong>from_hostname</strong></span> </td><td>
+            <p>
+              Comma-separated strings representing hostnames, specified using Perl-style regular
+              expressions, e.g. .*\.example\.company\.com
+            </p>
+            <p>
+              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
+            </p>
+            <p>
+              The rule matches if any of the patterns match the hostname of the messaging client.
+            </p>
+            <p>
+              To look up the client's hostname, Qpid uses Java's DNS support, which internally caches its results.
+            </p>
+            <p>
+              You can modify the time-to-live of cached results using the *.ttl properties described on the
+              Java <a class="ulink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html" target="_top">Networking
+              Properties</a> page.
+            </p>
+            <p>
+              For example, you can either set system property sun.net.inetaddr.ttl from the command line
+              (e.g. export QPID_OPTS="-Dsun.net.inetaddr.ttl=0") or networkaddress.cache.ttl in
+              $JAVA_HOME/lib/security/java.security. The latter is preferred because it is JVM
+              vendor-independent.
+            </p>
+            <p>
+              Java Broker only.
+            </p>
+          </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-Java-Broker-Security-ACLs-Syntax_javacomponents"></a><p class="title"><b>Table 10.5. List of ACL rules</b></p><div class="table-contents"><table summary="List of ACL rules" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td> <span class="command"><strong>UserManagement</strong></span> </td><td> <p>User maintainance; create/delete/view users, change passwords etc</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>ConfigurationManagement</strong></span> </td><td> <p>Dynammically reload configuration from disk.</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>LoggingManagement</strong></span> </td><td> <p>Dynammically control Qpid logging level</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><stron
 g>ServerInformation</strong></span> </td><td> <p>Read-only information regarding the Qpid: version number etc</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>VirtualHost.Queue</strong></span> </td><td> <p>Queue maintainance; copy/move/purge/view etc</p> </td><td class="auto-generated"> </td></tr><tr><td> <span class="command"><strong>VirtualHost.Exchange</strong></span> </td><td> <p>Exchange maintenance; bind/unbind queues to exchanges</p> </td><td class="auto-generated"> </td></tr><tr><td> <span class="command"><strong>VirtualHost.VirtualHost</strong></span> </td><td> <p>Virtual host maintainace; create/delete exchanges, queues etc</p> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Java-Broker-Security-ACLs-WorkedExamples"></a>10.4.4. 
+      Worked Examples
+    </h3></div></div></div><p>
+      Here are some example ACLs illustrating common use cases.
+      In addition, note that the Java broker provides a complete example ACL file, located at etc/broker_example.acl.
+    </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Security-ACLs-WorkedExample1"></a>10.4.4.1. 
+        Worked example 1 - Management rights
+      </h4></div></div></div><p>
+        Suppose you wish to permission two users: a user 'operator' must be able to perform all Management operations, and
+        a user 'readonly' must be enable to perform only read-only functions.  Neither 'operator' nor 'readonly'
+        should be allowed to connect clients for messaging.
+      </p><pre class="programlisting">
+# Deny (loggged) operator/readonly permission to connect messaging clients.
+ACL DENY-LOG operator ACCESS VIRTUALHOST
+ACL DENY-LOG readonly ACCESS VIRTUALHOST
+# Give operator permission to perfom all other actions
+ACL ALLOW operator ALL ALL
+# Give readonly permission to execute only read-only actions
+ACL ALLOW readonly ACCESS ALL
+...
+... rules for other users
+...
+# Explicitly deny all (log) to eveyone
+ACL DENY-LOG ALL ALL
+      </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Security-ACLs-WorkedExample2"></a>10.4.4.2. 
+        Worked example 2 - User maintainer group
+      </h4></div></div></div><p>
+        Suppose you wish to restrict User Management operations to users belonging to a
+        <a class="link" href="Java-Broker-Security-Group-Providers.html" title="10.2. Configuring Group Providers">group</a> 'usermaint'.  No other user
+        is allowed to perform user maintainence  This example illustrates the permissioning of an individual component.
+      </p><pre class="programlisting">
+# Give usermaint access to management and permission to execute all JMX Methods on the
+# UserManagement MBean and perform all actions for USER objects
+ACL ALLOW usermaint ACCESS MANAGEMENT
+ACL ALLOW usermaint ALL METHOD component="UserManagement"
+ACL ALLOW usermaint ALL USER
+ACL DENY ALL ALL METHOD component="UserManagement"
+ACL DENY ALL ALL USER
+...
+... rules for other users
+...
+ACL DENY-LOG ALL ALL
+      </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Security-ACLs-WorkedExample3"></a>10.4.4.3. 
+        Worked example 3 - Request/Response messaging
+      </h4></div></div></div><p>
+        Suppose you wish to permission a system using a request/response paradigm. Two users: 'client' publishes requests;
+        'server' consumes the requests and generates a response.  This example illustrates the permissioning of AMQP exchanges
+        and queues.
+      </p><pre class="programlisting">
+# Allow client and server to connect to the virtual host.
+ACL ALLOW client ACCESS VIRTUALHOST
+ACL ALLOW server ACCESS VIRTUALHOST
+
+# Client side
+# Allow the 'client' user to publish requests to the request queue. As is the norm for the request/response paradigm, the client
+# is required to create a temporary queue on which the server will respond.  Consequently, there are rules to allow the creation
+# of the temporary queues and consumption of messages from it.
+ACL ALLOW client CREATE QUEUE temporary="true"
+ACL ALLOW client CONSUME QUEUE temporary="true"
+ACL ALLOW client DELETE QUEUE temporary="true"
+ACL ALLOW client BIND EXCHANGE name="amq.direct" temporary="true"
+ACL ALLOW client UNBIND EXCHANGE name="amq.direct" temporary="true"
+ACL ALLOW client PUBLISH EXCHANGE name="amq.direct" routingKey="example.RequestQueue"
+
+# Server side
+# Allow the 'server' user to consume from the request queue and publish a response to the temporary response queue created by
+# client.  We also allow the server to create the request queue.
+ACL ALLOW server CREATE QUEUE name="example.RequestQueue"
+ACL ALLOW server CONSUME QUEUE name="example.RequestQueue"
+ACL ALLOW server BIND EXCHANGE
+ACL ALLOW server PUBLISH EXCHANGE name="amq.direct" routingKey="TempQueue*"
+
+ACL DENY-LOG all all
+      </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Java-Broker-Security-ACLs-WorkedExample4"></a>10.4.4.4. 
+        Worked example 4 - firewall-like access control
+      </h4></div></div></div><p>
+        This example illustrates how to set up an ACL that restricts the IP addresses and hostnames
+        of messaging clients that can access a virtual host.
+      </p><pre class="programlisting">
+################
+# Hostname rules
+################
+
+# Allow messaging clients from company1.com and company1.co.uk to connect
+ACL ALLOW all ACCESS VIRTUALHOST from_hostname=".*\.company1\.com,.*\.company1\.co\.uk"
+
+# Deny messaging clients from hosts within the dev subdomain
+ACL DENY-LOG all ACCESS VIRTUALHOST from_hostname=".*\.dev\.company1\.com"
+
+##################
+# IP address rules
+##################
+
+# Deny access to all users in the IP ranges 192.168.1.0-192.168.1.255 and 192.168.2.0-192.168.2.255,
+# using the notation specified in RFC 4632, "Classless Inter-domain Routing (CIDR)"
+ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
+  from_network="192.168.1.0/24,192.168.2.0/24"
+
+# Deny access to all users in the IP ranges 192.169.1.0-192.169.1.255 and 192.169.2.0-192.169.2.255,
+# using wildcard notation.
+ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
+  from_network="192.169.1.*,192.169.2.*"
+
+ACL DENY-LOG all all
+      </pre></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Security-Authentication-Providers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Java-Broker-Security.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Security-SSL.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.3. Authentication Providers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 10.5. SSL</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org