qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgodf...@apache.org
Subject svn commit: r1227030 [3/8] - in /qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book: html-single/ html/ html/css/ pdf/
Date Wed, 04 Jan 2012 02:22:59 GMT
Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,248 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.2.  Configuring ACLs</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="next" href="Qpid-Java-SSL.html" title="2.3.  Configure Java Qpid to use a SSL connection."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.2. 
+      Configuring ACLs
+  </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Qpid-Java-Broker-HowTos.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="Qpid-Java-SSL.html">Next</a></td></tr></table><hr></div><div class="section" title="2.2.  Configuring ACLs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Configuring-ACLS"></a>2.2. 
+      Configuring ACLs
+  </h2></div></div></div>
+  
+  <p>
+    In Qpid, ACLs specify which actions can be performed by each authenticated user. To enable the ACL &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; references a text file containing the ACL rules.  By convention, this file should have a .acl extension.
+  </p>
+
+
+  <div class="section" title="2.2.1.  Enabling ACLs"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-EnablingACL"></a>2.2.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" title="2.2.2.  Writing .acl files"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-WriteACL"></a>2.2.2. 
+       Writing .acl files
+    </h3></div></div></div>
+    
+
+    <p>
+      The ACL file consists of a series of rules and group definitions.  Each rule grants or denies specific rights to a user or group. Group
+      definitions declare groups of users and serve to make the ACL file more concise.
+    </p>
+    <p>
+      Each ACL rule grants (or denies) a particular action on a object to a user.  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 a 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>
+      To allow all operations, other than those controlled by earlier use </p><pre class="programlisting">ACL ALLOW ALL ALL </pre><p> instead.
+    </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, switch the DEBY-LOG to DENY for optimum performamce.
+    </p>
+    <p>
+      ACL rules are very powerful: it is possible to write very expressive rules permissioning every AMQP objects enumerating all object
+      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 (i.e. QUEUE) and apply consistently across the whole system.
+    </p>
+  </div>
+
+  <div class="section" title="2.2.3.  Syntax"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-Syntax"></a>2.2.3. 
+       Syntax
+    </h3></div></div></div>
+    
+
+    <p>
+       ACL rules must 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>
+       GROUP definitions must follow this syntax:
+    </p>
+    <pre class="programlisting">
+     GROUP {group name} {username 1}..{username n} # Where username is a username, or a groupname.
+    </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
+      GROUP securegroup bob \
+      alice # Another broker line
+    </pre>
+  </div>
+  <div class="table"><a name="tabl-ConfigureACLs-Syntax_permissions"></a><p class="title"><b>Table 2.2. ACL Rules: permission</b></p><div class="table-contents">
+    
+    <table summary="ACL Rules: 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="tabl-ConfigureACLs-Syntax_actions"></a><p class="title"><b>Table 2.3. ACL Rules:action</b></p><div class="table-contents">
+    
+    <table summary="ACL Rules:action" 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></sp
 an> </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="tabl-ConfigureACLs-Syntax_objects"></a><p class="title"><b>Table 2.4. ACL Rules:object</b></p><div class="table-contents">
+    
+    <table summary="ACL Rules:object" border="1"><colgroup><col><col></colgroup><tbody><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> <span class="command"><strong>VIRTUALHOST</strong></span> </td><td> <p> A virtualhost (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>BROKER</strong></span> </td><td> <p> The broker (not currently used in Java Broker)</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></tbody></table>
+  </div></div><br class="table-break">
+  <div class="table"><a name="tabl-ConfigureACLs-Syntax_properties"></a><p class="title"><b>Table 2.5. ACL Rules:property</b></p><div class="table-contents">
+    
+    <table summary="ACL Rules:property" border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="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>schemaclass</strong></span> </td><td> <p> String. QMF schema class name (Not used in Java Broker)</p> </td></tr></tbody></table>
+  </div></div><br class="table-break">
+  <div class="table"><a name="tabl-ConfigureACLs-Syntax_javacomponents"></a><p class="title"><b>Table 2.6. ACL rules:components (Java Broker only)</b></p><div class="table-contents">
+    
+    <table summary="ACL rules:components (Java Broker only)" 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"><strong>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>VirtualH
 ost.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" title="2.2.4.  Worked Examples"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-WorkedExamples"></a>2.2.4. 
+      Worked Examples
+    </h3></div></div></div>
+    
+    <p>
+       Here are three example ACLs illustrating some common use-cases.
+    </p>
+    <div class="section" title="2.2.4.1.  Worked example 1 - Management rights"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample1"></a>2.2.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 allow to connect for messaging.
+      </p>
+      <pre class="programlisting">
+        # Give operator permission to execute all JMX Methods
+        ACL ALLOW operator ALL METHOD
+        # Give operator permission to execute only read-only JMX Methods
+        ACL ALLOW readonly ACCESS METHOD
+        # Deny operator/readonly permission to perform messaging.
+        ACL DENY operator ACCESS VIRTUALHOST
+        ACL DENY readonly ACCESS VIRTUALHOST
+        ...
+        ... rules for other users
+        ...
+        # Explicitly deny all (log) to eveyone 
+        ACL DENY-LOG ALL ALL
+      </pre>
+    </div>
+    <div class="section" title="2.2.4.2.  Worked example 2 - User maintainer group"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample2"></a>2.2.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 group 'usermaint'.  No other user
+         is allowed to perform user maintainence  This example illustrates the permissioning of a individual component 
+         and a group definition.
+      </p>
+      <pre class="programlisting">
+        # Create a group usermaint with members bob and alice
+        GROUP usermaint bob alice
+        # Give operator permission to execute all JMX Methods
+        ACL ALLOW usermaint ALL METHOD component="UserManagement"
+        ACL DENY ALL ALL METHOD component="UserManagement"
+        ...
+        ... rules for other users
+        ...
+        ACL DENY-LOG ALL ALL
+      </pre>
+    </div>
+    <div class="section" title="2.2.4.3.  Worked example 3 - Request/Response messaging"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample3"></a>2.2.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 response.  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>
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Broker-HowTos.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-SSL.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. How Tos </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.3. 
+      Configure Java Qpid to use a SSL connection.
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/How-to-Tune-M3-Java-Broker-Performance.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/How-to-Tune-M3-Java-Broker-Performance.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/How-to-Tune-M3-Java-Broker-Performance.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/How-to-Tune-M3-Java-Broker-Performance.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,141 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.8.  How to Tune M3 Java Broker Performance</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Java-Broker-Debug-Logging.html" title="2.7.  Debug using log4j"><link rel="next" href="Qpid-Java-Build-HowTo.html" title="2.9.  Qpid Java Build How To"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.8. 
+      How to Tune M3 Java Broker Performance
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Java-Broker-Debug-Logging.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="Qpid-Java-Build-HowTo.html">Next</a></td></tr></table><hr></div><div class="section" title="2.8.  How to Tune M3 Java Broker Performance"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="How-to-Tune-M3-Java-Broker-Performance"></a>2.8. 
+      How to Tune M3 Java Broker Performance
+    </h2></div></div></div>
+  
+  <div class="section" title="2.8.1.  Problem Statement"><div class="titlepage"><div><div><h3 class="title"><a name="HowtoTuneM3JavaBrokerPerformance-ProblemStatement"></a>2.8.1. 
+            Problem
+            Statement
+          </h3></div></div></div>
+    
+  <p>
+            During destructive testing of the Qpid M3 Java Broker, we tested
+            some tuning techniques and deployment changes to improve the Qpid
+            M3 Java Broker's capacity to maintain high levels of throughput,
+            particularly in the case of a slower consumer than produceer
+            (i.e. a growing backlog).
+          </p>
+  <p>
+            The focus of this page is to detail the results of tuning &amp;
+            deployment changes trialled.
+          </p>
+  <p>
+            The successful tuning changes are applicable for any deployment
+            expecting to see bursts of high volume throughput (1000s of
+            persistent messages in large batches). Any user wishing to use
+            these options <span class="emphasis"><em>must test them thoroughly in their own
+            environment with representative volumes</em></span>.
+          </p>
+  
+  </div>
+
+  <div class="section" title="2.8.2.  Successful Tuning Options"><div class="titlepage"><div><div><h3 class="title"><a name="HowtoTuneM3JavaBrokerPerformance-SuccessfulTuningOptions"></a>2.8.2. 
+            Successful
+            Tuning Options
+          </h3></div></div></div>
+    
+  <p>
+            The key scenario being taregetted by these changes is a broker
+            under heavy load (processing a large batch of persistent
+            messages)can be seen to perform slowly when filling up with an
+            influx of high volume transient messages which are queued behind
+            the persistent backlog. However, the changes suggested will be
+            equally applicable to general heavy load scenarios.
+          </p>
+  <p>
+            The easiest way to address this is to separate streams of
+            messages. Thus allowing the separate streams of messages to be
+            processed, and preventing a backlog behind a particular slow
+            consumer.
+          </p>
+  <p>
+            These strategies have been successfully tested to mitigate this
+            problem:
+          </p>
+  <div class="table"><a name="id1329244"></a><p class="title"><b>Table 2.7. </b></p><div class="table-contents">
+    
+    <table summary="" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+                  Strategy
+                </td><td>
+                  Result
+                </td></tr><tr><td>
+                  Seperate connections to one broker for separate streams of
+                  messages.
+                </td><td>
+                  Messages processed successfully, no problems experienced
+                </td></tr><tr><td>
+                  Seperate brokers for transient and persistent messages.
+                </td><td>
+                  Messages processed successfully, no problems experienced
+                </td></tr></tbody></table>
+  </div></div><br class="table-break">
+  <p>
+            <span class="emphasis"><em>Separate Connections</em></span>
+            Using separate connections effectively means that the two streams
+            of data are not being processed via the same buffer, and thus the
+            broker gets &amp; processes the transient messages while
+            processing the persistent messages. Thus any build up of
+            unprocessed data is minimal and transitory.
+          </p>
+  <p>
+            <span class="emphasis"><em>Separate Brokers</em></span>
+            Using separate brokers may mean more work in terms of client
+            connection details being changed, and from an operational
+            perspective. However, it is certainly the most clear cut way of
+            isolating the two streams of messages and the heaps impacted.
+          </p>
+  <div class="section" title="2.8.2.1.  Additional tuning"><div class="titlepage"><div><div><h4 class="title"><a name="HowtoTuneM3JavaBrokerPerformance-Additionaltuning"></a>2.8.2.1. 
+            Additional
+            tuning
+          </h4></div></div></div>
+    
+  <p>
+            It is worth testing if changing the size of the Qpid read/write
+            thread pool improves performance (eg. by setting
+            JAVA_OPTS="-Damqj.read_write_pool_size=32" before running
+            qpid-server). By default this is equal to the number of CPU
+            cores, but a higher number may show better performance with some
+            work loads.
+          </p>
+  <p>
+            It is also important to note that you should give the Qpid broker
+            plenty of memory - for any serious application at least a -Xmx of
+            3Gb. If you are deploying on a 64 bit platform, a larger heap is
+            definitely worth testing with. We will be testing tuning options
+            around a larger heap shortly.
+          </p>
+    
+  </div>
+    
+  </div>
+
+  <div class="section" title="2.8.3.  Next Steps"><div class="titlepage"><div><div><h3 class="title"><a name="HowtoTuneM3JavaBrokerPerformance-NextSteps"></a>2.8.3. 
+            Next
+            Steps
+          </h3></div></div></div>
+    
+  <p>
+            These two options have been testing using a Qpid test case, and
+            demonstrated that for a test case with a profile of persistent
+            heavy load following by constant transient high load traffic they
+            provide significant improvment.
+          </p>
+  <p>
+            However, the deploying project <span class="emphasis"><em>must</em></span> complete their own
+            testing, using the same destructive test cases, representative
+            message paradigms &amp; volumes, in order to verify the proposed
+            mitigation options.
+          </p>
+  <p>
+            The using programme should then choose the option most applicable
+            for their deployment and perform BAU testing before any
+            implementation into a production or pilot environment.
+          </p>
+    
+  </div>
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Debug-Logging.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-Build-HowTo.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.7. 
+      Debug using log4j
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.9. 
+      Qpid Java Build How To
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Configuration-Guide.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Configuration-Guide.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Configuration-Guide.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Configuration-Guide.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,90 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.5. Broker Configuration Guide</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Java-General-User-Guides.html" title="Chapter 1. General User Guides"><link rel="prev" href="Qpid-Troubleshooting-Guide.html" title="1.4.  Qpid Troubleshooting Guide"><link rel="next" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.5. Broker Configuration Guide </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Qpid-Troubleshooting-Guide.html">Prev</a> </td><th width="60%" align="cente
 r">Chapter 1. General User Guides</th><td width="20%" align="right"> <a accesskey="n" href="Qpid-Java-Broker-HowTos.html">Next</a></td></tr></table><hr></div><div class="section" title="1.5. Broker Configuration Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Java-Broker-Configuration-Guide"></a>1.5. Broker Configuration Guide </h2></div></div></div>
+    
+
+    <div class="section" title="1.5.1. Topic Configuration on Java Broker"><div class="titlepage"><div><div><h3 class="title"><a name="id1326840"></a>1.5.1. Topic Configuration on Java Broker</h3></div></div></div> 
+    
+
+    <p>New in 0.8 is the ability to define configuration for topics. Currently this is limited to
+        configuration for slow consumer detection. This configuration is based on the work
+        designed on the <a class="ulink" href="http://cwiki.apache.org/confluence/display/qpid/Topic+Configuration+Design" target="_top">design
+            wiki</a>.</p>
+
+    <div class="section" title="1.5.1.1. Topic Identification"><div class="titlepage"><div><div><h4 class="title"><a name="Topic%20Identification"></a>1.5.1.1. Topic Identification</h4></div></div></div>
+    	
+        <p>A configuration section has two entries that can be used to identify how the
+            configuration will be applied: 'name' and 'subscriptionName'.  
+            
+            </p><pre class="programlisting">            
+                     &lt;topic&gt;
+                         &lt;name&gt;stocks.us&lt;/name&gt;        
+                </pre><p>
+            </p><pre class="programlisting">
+                     &lt;topic&gt;
+                         &lt;subscriptionName&gt;clientid:mysubscription&lt;/subscriptionName&gt;        
+            </pre><p>
+            
+            It is also possible to combine these two identifiers to specify a unique subscription to
+            a given topic.
+            
+            </p><pre class="programlisting">
+                    &lt;topic&gt;
+                        &lt;name&gt;stocks.us&lt;/name&gt;
+                        &lt;subscriptionName&gt;clientid:mysubscription&lt;/subscriptionName&gt;
+            </pre><p>
+        </p>
+    </div>
+
+    <div class="section" title="1.5.1.2. Configuration Items"><div class="titlepage"><div><div><h4 class="title"><a name="id1326894"></a>1.5.1.2. Configuration Items</h4></div></div></div>
+        
+        <p> Currently only one element of the designed configuration is processed, that of the
+            slow consumer detection. This is setup as below using the 'slow-consumer-detection'
+            element. There are two required types of tag, first the trigger, which is one of
+            'depth', 'messageAge' or 'messageCount' and secondly the 'policy'. </p>
+        <pre class="programlisting">
+	    &lt;slow-consumer-detection&gt;
+                &lt;!-- The maximum depth before which the policy will be applied--&gt;
+                &lt;depth&gt;4235264&lt;/depth&gt;
+
+                &lt;!-- The maximum message age before which the policy will be applied--&gt;
+                &lt;messageAge&gt;600000&lt;/messageAge&gt;
+
+                &lt;!-- The maximum number of message before which the policy will be applied--&gt;
+                &lt;messageCount&gt;50&lt;/messageCount&gt;
+
+                &lt;!-- Policy Selection --&gt;
+                &lt;policy name="TopicDelete"/&gt;
+            &lt;/slow-consumer-detection&gt;
+        </pre>
+
+        <p> The trigger is used to determine when the policy should be applied. Currently we have
+            a simple policy 'topicdelete', this will disconnect consumers of topics where their
+            consumption rate falls sufficiently to hit one of the trigger values. </p>
+    </div>
+
+
+    <div class="section" title="1.5.1.3. Limitiations"><div class="titlepage"><div><div><h4 class="title"><a name="Limitiations"></a>1.5.1.3. Limitiations</h4></div></div></div>
+    	
+        <p> As of 0.8 the topic configuration is limited to straight string matching. This means
+            that given the following two topic configuring sections for 'stocks.us' and 'stocks.*' a
+            subscription for 'stocks.uk' will not match the expected 'stocks.*'. Nor will any
+            additional configuration listed in 'stocks.*' affect any 'stocks.us' subscriptions. </p>
+        <pre class="programlisting">
+            &lt;topics&gt;
+                &lt;topic&gt;
+            	    &lt;name&gt;stocks.us&lt;/name&gt;
+	                ...
+	            &lt;/topic&gt;
+    	        &lt;topic&gt;
+	               &lt;name&gt;stocks.*&lt;/name&gt;
+	               ...
+                &lt;/topic&gt;
+            &lt;/topics&gt;
+    </pre>
+        <p> A subscription for 'stocks.us' will only receive configuration settings that are
+            defined in the 'stocks.us' section. </p>
+    </div>
+
+</div>
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Troubleshooting-Guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Java-General-User-Guides.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-Broker-HowTos.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.4. 
+      Qpid Troubleshooting Guide
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. How Tos</td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Debug-Logging.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Debug-Logging.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Debug-Logging.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Debug-Logging.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,267 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.7.  Debug using log4j</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Broker-Virtualhosts-Config.html" title="2.6.  Configure the Virtual Hosts via virtualhosts.xml"><link rel="next" href="How-to-Tune-M3-Java-Broker-Performance.html" title="2.8.  How to Tune M3 Java Broker Performance"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.7. 
+      Debug using log4j
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Qpid-Java-Broker-Virtualhosts-Config.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="How-to-Tune-M3-Java-Broker-Performance.html">Next</a></td></tr></table><hr></div><div class="section" title="2.7.  Debug using log4j"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Java-Broker-Debug-Logging"></a>2.7. 
+      Debug using log4j
+    </h2></div></div></div>
+
+    <div class="section" title="2.7.1.  Debugging with log4j configurations"><div class="titlepage"><div><div><h3 class="title"><a name="Debugusinglog4j-Debuggingwithlog4jconfigurations"></a>2.7.1. 
+            Debugging
+            with log4j configurations
+          </h3></div></div></div>
+	 <p>
+            Unfortunately setting of logging in the Java Broker is not simply
+            a matter of setting one of WARN,INFO,DEBUG. At some point in the
+            future we may have more BAU logging that falls in to that
+            category but more likely is that we will have a varioius config
+            files that can be swapped in (dynamically) to understand what is
+            going on.
+          </p><p>
+            This page will be host to a variety of useful configuration
+            setups that will allow a user or developer to extract only the
+            information they are interested in logging. Each section will be
+            targeted at logging in a particular area and will include a full
+            log4j file that can be used. In addition the logging
+            <span class="emphasis"><em>category</em></span> elements will be presented and discussed so
+            that the user can create their own file.
+          </p><p>
+            Currently the configuration that is available has not been fully
+            documented and as such there are gaps in what is desired and what
+            is available. Some times this is due to the desire to reduce the
+            overhead in message processing, but sometimes it is simply an
+            oversight. Hopefully in future releases the latter will be
+            addressed but care needs to be taken when adding logging to the
+            'Message Flow' path as this will have performance implications.
+          </p>
+
+	  <div class="section" title="2.7.1.1.  Logging Connection State *Deprecated*"><div class="titlepage"><div><div><h4 class="title"><a name="Debugusinglog4j-LoggingConnectionState-5CDeprecated-5C"></a>2.7.1.1. 
+            Logging
+            Connection State *Deprecated*
+          </h4></div></div></div>
+	 <p>
+            <span class="emphasis"><em>deprecation notice</em></span> Version 0.6 of the Java broker includes
+            <a class="xref" href="">???</a> functionality which improves upon these messages and
+            as such enabling status logging would be more beneficial.
+            The configuration file has been left here for assistence with
+            broker versions prior to 0.6.
+          </p><p>
+            The goals of this configuration are to record:
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>New Connections
+            </p></li><li class="listitem"><p>New Consumers
+            </p></li><li class="listitem"><p>Identify slow consumers
+            </p></li><li class="listitem"><p>Closing of Consumers
+            </p></li><li class="listitem"><p>Closing of Connections
+            </p></li></ul></div><p>
+            An additional goal of this configuration is to minimise any
+            impact to the 'message flow' path. So it should not adversely
+            affect production systems.
+          </p>
+<pre class="programlisting">
+
+&lt;log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"&gt;
+    &lt;appender name="FileAppender" class="org.apache.log4j.FileAppender"&gt;
+        &lt;param name="File" value="${QPID_WORK}/log/${logprefix}qpid${logsuffix}.log"/&gt;
+        &lt;param name="Append" value="false"/&gt;
+
+        &lt;layout class="org.apache.log4j.PatternLayout"&gt;
+            &lt;param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/&gt;
+        &lt;/layout&gt;
+
+    &lt;/appender&gt;
+
+    &lt;appender name="STDOUT" class="org.apache.log4j.ConsoleAppender"&gt;
+
+        &lt;layout class="org.apache.log4j.PatternLayout"&gt;
+            &lt;param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/&gt;
+        &lt;/layout&gt;
+    &lt;/appender&gt;
+
+    &lt;category name="Qpid.Broker"&gt;
+
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+
+
+    &lt;!-- Provide warnings to standard output --&gt;
+    &lt;category name="org.apache.qpid"&gt;
+        &lt;priority value="warn"/&gt;
+    &lt;/category&gt;
+
+
+    &lt;!-- Connection Logging --&gt;
+
+    &lt;!-- Log details of client starting connection --&gt;
+    &lt;category name="org.apache.qpid.server.handler.ConnectionStartOkMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Log details of client closing connection --&gt;
+    &lt;category name="org.apache.qpid.server.handler.ConnectionCloseMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Log details of client responding to be asked to closing connection --&gt;
+
+    &lt;category name="org.apache.qpid.server.handler.ConnectionCloseOkMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+
+    &lt;!-- Consumer Logging --&gt;
+    &lt;!-- Provide details of Consumers connecting--&gt;
+    &lt;category name="org.apache.qpid.server.handler.BasicConsumeMethodHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- Provide details of Consumers disconnecting, if the call it--&gt;
+    &lt;category name="org.apache.qpid.server.handler.BasicCancelMethodHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Provide details of when a channel closes to attempt to match to the Consume as a Cancel is not always issued--&gt;
+    &lt;category name="org.apache.qpid.server.handler.ChannelCloseHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- Provide details of Consumers starting to consume--&gt;
+    &lt;category name="org.apache.qpid.server.handler.ChannelFlowHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Provide details of what consumers are going to be consuming--&gt;
+    &lt;category name="org.apache.qpid.server.handler.QueueBindHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- No way of determining if publish message is returned, client log should show it.--&gt;
+
+    &lt;root&gt;
+        &lt;priority value="debug"/&gt;
+        &lt;appender-ref ref="STDOUT"/&gt;      
+        &lt;appender-ref ref="FileAppender"/&gt;
+    &lt;/root&gt;
+
+&lt;/log4j:configuration&gt;
+
+</pre>
+	  </div>
+
+	  <div class="section" title="2.7.1.2.  Debugging My Application"><div class="titlepage"><div><div><h4 class="title"><a name="Debugusinglog4j-DebuggingMyApplication"></a>2.7.1.2. 
+            Debugging My
+            Application
+          </h4></div></div></div>
+	 <p>
+            This is the most often asked for set of configuration. The goals
+            of this configuration are to record:
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>New Connections
+            </p></li><li class="listitem"><p>New Consumers
+            </p></li><li class="listitem"><p>Message Publications
+            </p></li><li class="listitem"><p>Message Consumption
+            </p></li><li class="listitem"><p>Identify slow consumers
+            </p></li><li class="listitem"><p>Closing of Consumers
+            </p></li><li class="listitem"><p>Closing of Connections
+            </p></li></ul></div><p>
+            NOTE: This configuration enables message logging on the 'message
+            flow' path so should only be used were message volume is
+            low.
+            <span class="emphasis"><em>Every message that is sent to the broker will generate at
+            least four logging statements</em></span>
+          </p>
+<pre class="programlisting">
+
+&lt;log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"&gt;
+    &lt;appender name="FileAppender" class="org.apache.log4j.FileAppender"&gt;
+        &lt;param name="File" value="${QPID_WORK}/log/${logprefix}qpid${logsuffix}.log"/&gt;
+        &lt;param name="Append" value="false"/&gt;
+
+        &lt;layout class="org.apache.log4j.PatternLayout"&gt;
+            &lt;param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/&gt;
+        &lt;/layout&gt;
+
+    &lt;/appender&gt;
+
+    &lt;appender name="STDOUT" class="org.apache.log4j.ConsoleAppender"&gt;
+
+        &lt;layout class="org.apache.log4j.PatternLayout"&gt;
+            &lt;param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/&gt;
+        &lt;/layout&gt;
+    &lt;/appender&gt;
+
+    &lt;category name="Qpid.Broker"&gt;
+
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+
+
+    &lt;!-- Provide warnings to standard output --&gt;
+    &lt;category name="org.apache.qpid"&gt;
+        &lt;priority value="warn"/&gt;
+    &lt;/category&gt;
+
+
+    &lt;!-- Connection Logging --&gt;
+
+    &lt;!-- Log details of client starting connection --&gt;
+    &lt;category name="org.apache.qpid.server.handler.ConnectionStartOkMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Log details of client closing connection --&gt;
+    &lt;category name="org.apache.qpid.server.handler.ConnectionCloseMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Log details of client responding to be asked to closing connection --&gt;
+
+    &lt;category name="org.apache.qpid.server.handler.ConnectionCloseOkMethodHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- Consumer Logging --&gt;
+    &lt;!-- Provide details of Consumers connecting--&gt;
+    &lt;category name="org.apache.qpid.server.handler.BasicConsumeMethodHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- Provide details of Consumers disconnecting, if the call it--&gt;
+    &lt;category name="org.apache.qpid.server.handler.BasicCancelMethodHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Provide details of when a channel closes to attempt to match to the Consume as a Cancel is not always issued--&gt;
+    &lt;category name="org.apache.qpid.server.handler.ChannelCloseHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- Provide details of Consumers starting to consume--&gt;
+    &lt;category name="org.apache.qpid.server.handler.ChannelFlowHandler"&gt;
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+    &lt;!-- Provide details of what consumers are going to be consuming--&gt;
+    &lt;category name="org.apache.qpid.server.handler.QueueBindHandler"&gt;
+        &lt;priority value="info"/&gt;
+    &lt;/category&gt;
+
+    &lt;!-- No way of determining if publish message is returned, client log should show it.--&gt;
+
+    &lt;!-- WARNING DO NOT ENABLE THIS IN PRODUCTION --&gt;
+    &lt;!-- Will generate minimum one log statements per published message --&gt;
+    &lt;!-- Will generate will log receiving of all body frame, count will vary on size of message.--&gt;
+    &lt;!-- Empty Message = no body, Body is up to 64kb of data --&gt;
+    &lt;!-- Will generate three log statements per recevied message --&gt;
+
+    &lt;!-- Log messages flow--&gt;
+    &lt;category name="org.apache.qpid.server.AMQChannel"&gt;
+
+        &lt;priority value="debug"/&gt;
+    &lt;/category&gt;
+
+    &lt;root&gt;
+        &lt;priority value="debug"/&gt;
+        &lt;appender-ref ref="STDOUT"/&gt;      
+        &lt;appender-ref ref="FileAppender"/&gt;
+    &lt;/root&gt;
+
+&lt;/log4j:configuration&gt;
+
+</pre>
+
+</div>            
+</div>
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Broker-Virtualhosts-Config.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="How-to-Tune-M3-Java-Broker-Performance.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.6. 
+      Configure the Virtual Hosts via virtualhosts.xml
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.8. 
+      How to Tune M3 Java Broker Performance
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Slow-Consumer-Disconnect.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Slow-Consumer-Disconnect.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Slow-Consumer-Disconnect.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Broker-Slow-Consumer-Disconnect.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,255 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.11. Slow Consumer Disconnect - User Guide</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Priority-Queues.html" title="2.10.  Use Priority Queues"><link rel="next" href="Qpid-JMX-Management-Console.html" title="Chapter 3.  Qpid JMX Management Console"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.11. Slow Consumer Disconnect - User Guide</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Priority-Queues.html">Prev</a> </td><th width="60%" align
 ="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="Qpid-JMX-Management-Console.html">Next</a></td></tr></table><hr></div><div class="section" title="2.11. Slow Consumer Disconnect - User Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Java-Broker-Slow-Consumer-Disconnect"></a>2.11. Slow Consumer Disconnect - User Guide</h2></div></div></div>
+  
+
+  <div class="section" title="2.11.1. Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="id1330231"></a>2.11.1. Introduction</h3></div></div></div>
+
+   <p>Slow Consumer Disconnect (SCD) is a new feature in Qpid that provides a configurable
+        mechanism to prevent a single slow consumer from causing a back up of unconsumed messages on
+        the broker. </p>
+
+   <p>This is most relevant where Topics are in use, since a published message is not removed
+        from the broker's memory until all subscribers have acknowledged that message. </p>
+
+   <p>Cases where a consumer is 'slow' can arise due to one of the following: poor network
+        connectivity exists; a transient system issue affects a single client; a single subscriber
+        written by a client team is behaving incorrectly and not acknowledging messages; a
+        downstream resource such as a database is non-responsive. </p>
+
+   <p>SCD will enable the application owner to configure limits for a given consumer's queue and
+        the behaviour to execute when those limits are reached. </p>
+
+  </div>
+
+  <div class="section" title="2.11.2. What can it do?"><div class="titlepage"><div><div><h3 class="title"><a name="id1330260"></a>2.11.2. What can it do?</h3></div></div></div>
+
+   <p>SCD is only applicable to topics or durable subscriptions and can be configured on either
+        a topic or a subscription name. </p>
+
+   <p>On triggering of a specified threshold the offending client will be disconnected from the
+        broker with a 506 error code wrapped in a JMSException returned to the client via the
+        ExceptionListener registered on the Connection object. </p>
+
+   <p>Note that it is essential that an ExceptionListener be specified by the client on
+        creation of the connection and that exceptions coming back on that listener are handled
+        correctly. </p>
+
+  </div>
+
+  <div class="section" title="2.11.3. Frequency of SCD Checking"><div class="titlepage"><div><div><h3 class="title"><a name="id1330285"></a>2.11.3. Frequency of SCD Checking</h3></div></div></div>
+
+   <div class="section" title="2.11.3.1. Configuring Frequency"><div class="titlepage"><div><div><h4 class="title"><a name="id1330290"></a>2.11.3.1. <span class="bold"><strong>Configuring Frequency</strong></span></h4></div></div></div>
+
+    <p>You can configure the frequency with which the SCD process will check for slow consumers,
+          along with the unit of time used to specify that frequency. </p>
+
+    <p>The <span class="italic">virtualhosts.virtualhost.hostname.slow-consumer-detection</span>
+          elements <span class="italic">delay</span> and <span class="italic">timeunit</span>
+          are used to specify the frequency and timeunit respectively in the virtualhosts.xml
+          file e.g. </p>
+
+<pre class="programlisting">
+&lt;virtualhosts&gt;
+	&lt;default&gt;test&lt;/default&gt;
+	&lt;virtualhost&gt;
+		&lt;name&gt;test&lt;/name&gt;
+		&lt;test&gt;
+		   &lt;slow-consumer-detection&gt;
+			&lt;delay&gt;60&lt;delay/&gt;
+			&lt;timeunit&gt;seconds&lt;timeunit/&gt;
+		&lt;slow-consumer-detection/&gt;
+		&lt;/test&gt;
+	&lt;/virtualhost&gt;
+&lt;/virtualhosts&gt;
+</pre>
+
+   </div>
+
+   <div class="section" title="2.11.3.2. SCD Log output"><div class="titlepage"><div><div><h4 class="title"><a name="id1330338"></a>2.11.3.2. <span class="bold"><strong>SCD Log output</strong></span></h4></div></div></div>
+
+    <p>When the SCD component finds a queue with a configured threshold to check, the operational
+          logging component (if enabled) will output the following line:</p>
+
+    <pre class="programlisting">
+    SCD-1003 : Checking Status of Queue
+    </pre>
+
+   </div>
+
+  </div>
+
+  <div class="section" title="2.11.4. Client Exceptions"><div class="titlepage"><div><div><h3 class="title"><a name="id1330361"></a>2.11.4. Client Exception<span class="bold"><strong>s</strong></span></h3></div></div></div>
+
+   <p>When a Slow Consumer is disconnected, the client receives a 506 error from the broker
+        wrapped in a JMSException and the Session and Connection are closed:</p>
+
+<pre class="programlisting">
+Dispatcher-Channel-1 2010-09-01 16:23:34,206 INFO [qpid.client.AMQSession.Dispatcher]
+    Dispatcher-Channel-1 thread terminating for channel 1:org.apache.qpid.client.AMQSession_0_8@1de8aa8
+pool-2-thread-3 2010-09-01 16:23:34,238 INFO [apache.qpid.client.AMQConnection] Closing AMQConnection due to
+    :org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow. [error code 506: resource error]
+javax.jms.JMSException: 506
+at org.apache.qpid.client.AMQConnection.exceptionReceived(AMQConnection.java:1396)
+at org.apache.qpid.client.protocol.AMQProtocolHandler.exception(AMQProtocolHandler.java:329)
+at org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:536)
+at org.apache.qpid.client.protocol.AMQProtocolSession.methodFrameReceived(AMQProtocolSession.java:453)
+at org.apache.qpid.framing.AMQMethodBodyImpl.handle(AMQMethodBodyImpl.java:93)
+at org.apache.qpid.client.protocol.AMQProtocolHandler$1.run(AMQProtocolHandler.java:462)
+at org.apache.qpid.pool.Job.processAll(Job.java:110)
+at org.apache.qpid.pool.Job.run(Job.java:149)
+at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:885)
+at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:907)
+at java.lang.Thread.run(Thread.java:619)
+Caused by: org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow. [error code 506: resource error]
+at org.apache.qpid.client.handler.ChannelCloseMethodHandler.methodReceived(ChannelCloseMethodHandler.java:96)
+at org.apache.qpid.client.handler.ClientMethodDispatcherImpl.dispatchChannelClose(ClientMethodDispatcherImpl.java:163)
+at org.apache.qpid.framing.amqp_8_0.ChannelCloseBodyImpl.execute(ChannelCloseBodyImpl.java:140)
+at org.apache.qpid.client.state.AMQStateManager.methodReceived(AMQStateManager.java:112)
+at org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:511)
+... 8 more
+main 2010-09-01 16:23:34,316 INFO [apache.qpid.client.AMQSession] Closing session:
+    org.apache.qpid.client.AMQSession_0_8@ffeef1
+</pre>
+
+  </div>
+
+  <div class="section" title="2.11.5. Disconnection Thresholds"><div class="titlepage"><div><div><h3 class="title"><a name="id1330400"></a>2.11.5. Disconnection Thresholds</h3></div></div></div>
+
+   <div class="section" title="2.11.5.1. Topic Subscriptions"><div class="titlepage"><div><div><h4 class="title"><a name="id1330407"></a>2.11.5.1. Topic Subscriptions</h4></div></div></div>
+
+    <p>One key feature of SCD is the disconnection of a consuming client when a specified
+          threshold is exceeded. For a pub-sub model using topics, this means that messages will no
+          longer be delivered to the private queue which was associated with that consuming client,
+          thus reducing any associated backlog in the broker. </p>
+
+   </div>
+
+   <div class="section" title="2.11.5.2. Durable Topic Subscriptions"><div class="titlepage"><div><div><h4 class="title"><a name="id1330422"></a>2.11.5.2. Durable Topic Subscriptions</h4></div></div></div>
+
+    <p>For durable subscriptions, simply disconnecting the consuming client will not suffice
+          since the associated queue is by definition durable and messages would continue to flow to
+          it after disconnection, potentially worsening any backing up of data on the broker. </p>
+
+    <p>The solution is to configure durable subscriptions to delete the underlying queue on
+          disconnection. This means that messages will no longer be delivered to the private queue
+          associated with the subscription, thus preventing any backlog. </p>
+
+    <p>Full details of how to configure the thresholds are provided below. </p>
+
+   </div>
+
+   <div class="section" title="2.11.5.3. Message Age Threshold"><div class="titlepage"><div><div><h4 class="title"><a name="id1330444"></a>2.11.5.3. Message Age Threshold</h4></div></div></div>
+
+    <p>You can configure SCD to be triggered on a topic or subscription when the oldest message
+          in the associated private queue for the consumer ages beyond the specified value, in
+          milliseconds. </p>
+
+   </div>
+
+   <div class="section" title="2.11.5.4. Queue Depth Threshold"><div class="titlepage"><div><div><h4 class="title"><a name="id1330458"></a>2.11.5.4. Queue Depth Threshold</h4></div></div></div>
+
+    <p>You can opt to use the depth of the queue in bytes as a threshold. SCD will be triggered
+          by a queue depth greater than the threshold specified i.e. when a broker receives a
+          message that takes the queue depth over the threshold. </p>
+
+   </div>
+
+   <div class="section" title="2.11.5.5. Message Count Threshold"><div class="titlepage"><div><div><h4 class="title"><a name="id1330472"></a>2.11.5.5. Message Count Threshold</h4></div></div></div>
+
+    <p>You can use the message count for the consumer's queue as the trigger, where a count
+          higher than that specified will trigger disconnection. </p>
+
+   </div>
+
+   <div class="section" title="2.11.5.6. Delete Policy"><div class="titlepage"><div><div><h4 class="title"><a name="id1330484"></a>2.11.5.6. <span class="bold"><strong>Delete Policy</strong></span></h4></div></div></div>
+
+    <p>You can configure the policy you wish to apply in your broker configuration. There are
+          currently 2 policies available: </p>
+
+    <p>
+<span class="bold"><strong>Delete Temporary Queues Only</strong></span>
+    </p>
+
+    <p>If you do not specify a &lt;topicDelete/&gt; element in your configuration, then only temporary
+          queues associated with a topic subscription will be deleted on client disconnect. This is
+          the default behaviour. </p>
+        <p></p>
+
+    <p>
+<span class="bold"><strong>Delete Durable Subscription Queues</strong></span>
+    </p>
+
+    <p>If you add the &lt;topicDelete/&gt; element with the sub-element
+          &lt;delete-persistent/&gt; to your config, then the persistent queue which is associated
+          with durable subscriptions to a topic will also be deleted. This is an important
+          consideration since without deleting the underlying queue the client's unconsumed data
+          will grow indefinitely while they will be unable to reconnect to that queue due to the SCD
+          threshold configured, potentially having an adverse effect on the application or broker in
+          use.</p>
+        <p></p>
+
+    <p><span class="bold"><strong> Example Topic Configuration </strong></span></p>
+
+    <p></p>
+
+    <p>
+The following steps are required to configure SCD:
+    </p>
+
+<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+    <p>Enable SCD checking for your virtual host</p>
+    </li><li class="listitem">
+    <p>Specify frequency for SCD checking</p>
+    </li><li class="listitem">
+    <p>Define thresholds for the topic</p>
+    </li><li class="listitem">
+    <p>Define the policy to apply on trigger </p>
+    </li></ul></div>
+
+    <p>The example below shows a simple definition, with all three thresholds specified and a
+          simple disconnection, with deletion of any temporary queue, defined. </p>
+
+    <p>For a durable subscription to this topic, no queue deletion would be applied on disconnect
+          - which is likely to be undesirable (see section above). </p>
+
+<pre class="programlisting">
+&lt;topics&gt;
+	 &lt;topic&gt;
+	 &lt;name&gt;stocks.us.*&lt;/name&gt;
+		 &lt;slow-consumer-detection&gt;
+			 &lt;!-- The maximum depth before which --&gt;
+			 &lt;!-- the policy will be applied--&gt;
+			 &lt;depth&gt;4235264&lt;/depth&gt;
+			 &lt;!-- The maximum message age before which --&gt;
+			 &lt;!-- the policy will be applied--&gt;
+			 &lt;messageAge&gt;600000&lt;/messageAge&gt;
+			 &lt;!-- The maximum number of message before --&gt;
+			 &lt;!-- which the policy will be applied--&gt;
+			 &lt;messageCount&gt;50&lt;/messageCount&gt;
+			 &lt;!-- Policy Selection --&gt;
+			 &lt;policy name="TopicDelete"/&gt;
+		 &lt;/slow-consumer-detection&gt;
+	 &lt;/topic&gt;
+&lt;/topics&gt;
+</pre>
+
+   </div>
+
+  </div>
+
+  <div class="section" title="2.11.6. Important Points To Note"><div class="titlepage"><div><div><h3 class="title"><a name="id1330486"></a>2.11.6. Important Points To Note</h3></div></div></div>
+
+   <p> Client application developers should be educated about how to correctly handle being
+        disconnected with a 506 error code, to avoid them getting into a thrashing state where they
+        continually attempt to connect, fail to consume fast enough and are disconnected again. </p>
+
+   <p>Clients affected by slow consumer disconnect configuration should always use transactions
+        where duplicate processing of an incoming message would have adverse affects, since they may
+        receive a message more than once if disconnected before acknowledging a message in flight. </p>
+
+  </div>
+
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Priority-Queues.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-JMX-Management-Console.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.10. 
+      Use Priority Queues
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. 
+    Qpid JMX Management Console
+  </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Environment-Variables.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Environment-Variables.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Environment-Variables.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-Environment-Variables.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,68 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.3.  Java Environment Variables</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Java-General-User-Guides.html" title="Chapter 1. General User Guides"><link rel="prev" href="Qpid-Java-FAQ.html" title="1.2.  Qpid Java FAQ"><link rel="next" href="Qpid-Troubleshooting-Guide.html" title="1.4.  Qpid Troubleshooting Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.3. 
+      Java Environment Variables
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Qpid-Java-FAQ.html">Prev</a> </td><th width="60%" align="center">Chapter 1. General User Guides</th><td width="20%" align="right"> <a accesskey="n" href="Qpid-Troubleshooting-Guide.html">Next</a></td></tr></table><hr></div><div class="section" title="1.3.  Java Environment Variables"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Java-Environment-Variables"></a>1.3. 
+      Java Environment Variables
+    </h2></div></div></div>
+  
+  <div class="section" title="1.3.1.  Setting Qpid Environment Variables"><div class="titlepage"><div><div><h3 class="title"><a name="JavaEnvironmentVariables-SettingQpidEnvironmentVariables"></a>1.3.1. 
+            Setting
+            Qpid Environment Variables
+          </h3></div></div></div>
+    
+
+  <div class="section" title="1.3.1.1.  Qpid Deployment Path Variables"><div class="titlepage"><div><div><h4 class="title"><a name="JavaEnvironmentVariables-QpidDeploymentPathVariables"></a>1.3.1.1. 
+            Qpid
+            Deployment Path Variables
+          </h4></div></div></div>
+    
+  <p>
+            There are two main Qpid environment variables which are required
+            to be set for Qpid deployments, QPID_HOME and QPID_WORK.
+          </p>
+  <p>
+            QPID_HOME - This variable is used to tell the Qpid broker where
+            it's installed home is, which is in turn used to find dependency
+            JARs which Qpid uses.
+          </p>
+  <p>
+            QPID_WORK - This variable is used by Qpid when creating all
+            'writeable' directories that it uses. This includes the log
+            directory and the storage location for any BDB instances in use
+            by your deployment (if you're using persistence with BDB). If you
+            do not set this variable, then the broker will default (in the
+            qpid-server script) to use the current user's homedir as the root
+            directory for creating the writeable locations that it uses.
+          </p>
+
+    
+  </div>
+
+  <div class="section" title="1.3.1.2.  Setting Max Memory for the broker"><div class="titlepage"><div><div><h4 class="title"><a name="JavaEnvironmentVariables-SettingMaxMemoryforthebroker"></a>1.3.1.2. 
+            Setting
+            Max Memory for the broker
+          </h4></div></div></div>
+    
+  <p>
+            If you simply start the Qpid broker, it will default to use a
+            -Xmx setting of 1024M for the broker JVM. However, we would
+            recommend that you make the maximum -Xmx heap size available, if
+            possible, of 3Gb (for 32-bit platforms).
+          </p>
+  <p>
+            You can control the memory setting for your broker by setting the
+            QPID_JAVA_MEM variable before starting the broker e.g. -Xmx3668m
+            . Enclose your value within quotes if you also specify a -Xms
+            value. The value in use is echo'd by the qpid-server script on
+            startup.
+          </p>
+    
+  </div>
+
+    
+  </div>
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-FAQ.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Java-General-User-Guides.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Troubleshooting-Guide.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.2. 
+      Qpid Java FAQ
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.4. 
+      Qpid Troubleshooting Guide
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-General-User-Guides.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-General-User-Guides.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-General-User-Guides.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Java-General-User-Guides.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,83 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 1. General User Guides</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="prev" href="pr01.html" title="Introduction"><link rel="next" href="Qpid-Java-FAQ.html" title="1.2.  Qpid Java FAQ"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. General User Guides</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pr01.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="Qpid-Java-FAQ.html"
 >Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 1. General User Guides"><div class="titlepage"><div><div><h2 class="title"><a name="Java-General-User-Guides"></a>Chapter 1. General User Guides</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="Java-General-User-Guides.html#id1325140">1.1. 
+      Java Broker Feature Guide
+    </a></span></dt><dd><dl><dt><span class="section"><a href="Java-General-User-Guides.html#JavaBrokerFeatureGuide-TheQpidpureJavabrokercurrentlysupportsthefollowingfeatures-3A">1.1.1. 
+            The Qpid pure Java broker currently supports the following
+            features:
+          </a></span></dt></dl></dd><dt><span class="section"><a href="Qpid-Java-FAQ.html">1.2. 
+      Qpid Java FAQ
+    </a></span></dt><dd><dl><dt><span class="section"><a href="Qpid-Java-FAQ.html#QpidJavaFAQ-Purpose">1.2.1. Purpose</a></span></dt></dl></dd><dt><span class="section"><a href="Java-Environment-Variables.html">1.3. 
+      Java Environment Variables
+    </a></span></dt><dd><dl><dt><span class="section"><a href="Java-Environment-Variables.html#JavaEnvironmentVariables-SettingQpidEnvironmentVariables">1.3.1. 
+            Setting
+            Qpid Environment Variables
+          </a></span></dt></dl></dd><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html">1.4. 
+      Qpid Troubleshooting Guide
+    </a></span></dt><dd><dl><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html#QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F">1.4.1. 
+            I'm getting a java.lang.UnsupportedClassVersionError when I
+            try to start the broker. What does this mean ?
+          </a></span></dt><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html#QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F">1.4.2. 
+            I'm having a problem binding to the required host:port at
+            broker startup ?
+          </a></span></dt><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html#QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F">1.4.3. 
+            I'm having problems with my classpath. How can I ensure that
+            my classpath is ok ?
+          </a></span></dt><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html#QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F">1.4.4. 
+            I can't get the broker to start. How can I diagnose the
+            problem ?
+          </a></span></dt><dt><span class="section"><a href="Qpid-Troubleshooting-Guide.html#QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F">1.4.5. 
+            When I try to send messages to a queue I'm getting a error as
+            the queue does not exist. What can I do ?
+          </a></span></dt></dl></dd><dt><span class="section"><a href="Java-Broker-Configuration-Guide.html">1.5. Broker Configuration Guide </a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Configuration-Guide.html#id1326840">1.5.1. Topic Configuration on Java Broker</a></span></dt></dl></dd></dl></div>
+  
+
+        <div class="section" title="1.1.  Java Broker Feature Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1325140"></a>1.1. 
+      Java Broker Feature Guide
+    </h2></div></div></div>
+  
+  <div class="section" title="1.1.1.  The Qpid pure Java broker currently supports the following features:"><div class="titlepage"><div><div><h3 class="title"><a name="JavaBrokerFeatureGuide-TheQpidpureJavabrokercurrentlysupportsthefollowingfeatures-3A"></a>1.1.1. 
+            The Qpid pure Java broker currently supports the following
+            features:
+          </h3></div></div></div>
+    
+  <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>All features required by the Sun JMS 1.1 specification, fully
+            tested
+            </p></li><li class="listitem"><p>Transaction support
+            </p></li><li class="listitem"><p>Persistence using a pluggable layer
+            </p></li><li class="listitem"><p>Pluggable security using SASL
+            </p></li><li class="listitem"><p>Management using JMX and an Eclipse Management Console
+            application
+            </p></li><li class="listitem"><p>High performance header-based routing for messages
+            </p></li><li class="listitem"><p>Message Priorities
+            </p></li><li class="listitem"><p>Configurable logging and log archiving
+            </p></li><li class="listitem"><p>Threshold alerting
+            </p></li><li class="listitem"><p>ACLs
+            </p></li><li class="listitem"><p>Extensively tested on each release, including performance
+            &amp; reliability testing
+            </p></li><li class="listitem"><p>Automatic client failover using configurable connection
+            properties
+            </p></li><li class="listitem"><p>Durable Queues/Subscriptions
+            </p></li></ul></div>
+  <div class="section" title="1.1.1.1.  Upcoming features:"><div class="titlepage"><div><div><h4 class="title"><a name="JavaBrokerFeatureGuide-Upcomingfeatures-3A"></a>1.1.1.1. 
+            Upcoming
+            features:
+          </h4></div></div></div>
+    
+  <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Flow To Disk
+            </p></li><li class="listitem"><p>IP Whitelist
+            </p></li><li class="listitem"><p>AMQP 0-10 Support (for interoperability)
+            </p></li></ul></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="pr01.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-FAQ.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.2. 
+      Qpid Java FAQ
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Priority-Queues.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Priority-Queues.html?rev=1227030&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Priority-Queues.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-Java-Book/html/Priority-Queues.html Wed Jan  4 02:22:58 2012
@@ -0,0 +1,120 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.10.  Use Priority Queues</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Build-HowTo.html" title="2.9.  Qpid Java Build How To"><link rel="next" href="Java-Broker-Slow-Consumer-Disconnect.html" title="2.11. Slow Consumer Disconnect - User Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.10. 
+      Use Priority Queues
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="Qpid-Java-Build-HowTo.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="Java-Broker-Slow-Consumer-Disconnect.html">Next</a></td></tr></table><hr></div><div class="section" title="2.10.  Use Priority Queues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Priority-Queues"></a>2.10. 
+      Use Priority Queues
+    </h2></div></div></div>
+
+    
+    <div class="section" title="2.10.1.  General Information"><div class="titlepage"><div><div><h3 class="title"><a name="UsePriorityQueues-GeneralInformation"></a>2.10.1. 
+            General
+            Information
+          </h3></div></div></div>
+	  <p>
+            The Qpid M3 release introduces priority queues into the Java
+            Messaging Broker, supporting JMS clients who wish to make use of
+            priorities in their messaging implementation.
+          </p><p>
+            There are some key points around the use of priority queues in
+            Qpid, discussed in the sections below.
+          </p>
+</div>
+    <div class="section" title="2.10.2.  Defining Priority Queues"><div class="titlepage"><div><div><h3 class="title"><a name="UsePriorityQueues-DefiningPriorityQueues"></a>2.10.2. 
+            Defining
+            Priority Queues
+          </h3></div></div></div>
+	  <p>
+            You must define a priority queue specifically before you start to
+            use it. You cannot subsequently change a queue to/from a priority
+            queue (without deleting it and re-creating).
+          </p><p>
+            You define a queue as a priority queue in the virtualhost
+            configuration file, which the broker loads at startup. When
+            defining the queue, add a &lt;priority&gt;true&lt;/priority&gt;
+            element. This will ensure that the queue has 10 distinct
+            priorities, which is the number supported by JMS.
+          </p><p>
+            If you require fewer priorities, it is possible to specify a
+            &lt;priorities&gt;int&lt;/priorities&gt; element (where int is a
+            valid 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>
+            <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;priority&gt;true&lt;/priority&gt;
+    &lt;/test&gt;
+&lt;/queue&gt;
+</pre>
+</div>
+          
+    <div class="section" title="2.10.3.  Client configuration/messaging model for priority queues"><div class="titlepage"><div><div><h3 class="title"><a name="UsePriorityQueues-Clientconfiguration-2Fmessagingmodelforpriorityqueues"></a>2.10.3. 
+            Client configuration/messaging model for priority queues
+          </h3></div></div></div>
+	  <p>
+            There are some other configuration &amp; paradigm changes which
+            are required in order that priority queues work as expected.
+          </p>
+    <div class="section" title="2.10.3.1.  Set low pre-fetch"><div class="titlepage"><div><div><h4 class="title"><a name="UsePriorityQueues-Setlowprefetch"></a>2.10.3.1. 
+            Set low pre-fetch
+          </h4></div></div></div>
+	  <p>
+            Qpid clients receive buffered messages in batches, sized
+            according to the pre-fetch value. The current default is 5000.
+          </p><p>
+            However, if you use the default value you will probably
+            <span class="emphasis"><em>not</em></span> see desirable behaviour with messages of different
+            priority. This is because a message arriving after the pre-fetch
+            buffer has filled will not leap frog messages of lower priority.
+            It will be delivered at the front of the next batch of buffered
+            messages (if that is appropriate), but this is most likely NOT
+            what you need.
+          </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 max_prefetch on the client environment (using -D) before
+            creating your consumer.
+          </p><p>
+            Setting the Qpid pre-fetch to 1 for your client means that
+            message priority will be honoured by the Qpid broker as it
+            dispatches messages to your client. 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 'maxprefetch' value to the <a class="xref" href="">???</a>
+          </p>
+            <pre class="programlisting">
+amqp://guest:guest@client1/development?maxprefetch='1'&amp;brokerlist='tcp://localhost:5672'
+</pre>
+          <p>
+            There is a slight performance cost here if using the receive()
+            method and you could test with a slightly higher pre-fetch (up to
+            10) if the trade-off between throughput and prioritisation is
+            weighted towards the former for your application. (If you're
+            using OnMessage() then this is not a concern.)
+          </p>
+</div>
+    <div class="section" title="2.10.3.2.  Single consumer per session"><div class="titlepage"><div><div><h4 class="title"><a name="UsePriorityQueues-Singleconsumerpersession"></a>2.10.3.2. 
+            Single
+            consumer per session
+          </h4></div></div></div>
+	  <p>
+            If you are using the receive() method to consume messages then
+            you should also only use one consumer per session with priority
+            queues. If you're using OnMessage() then this is not a concern.
+          </p>
+</div>
+</div>
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Build-HowTo.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Java-Broker-Slow-Consumer-Disconnect.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.9. 
+      Qpid Java Build How To
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.11. Slow Consumer Disconnect - User Guide</td></tr></table></div></body></html>



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message