qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rob...@apache.org
Subject svn commit: r1042462 [7/12] - in /qpid/site/docs/books/0.8: ./ AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html/ AMQP-Messaging-Broker-CPP-Book/html/images/ AMQP-Messaging-Broker-CPP-Book/html/images/jmx_console/ AMQP-Messaging-Broke...
Date Sun, 05 Dec 2010 21:59:26 GMT
Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s02.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s02.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s02.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s02.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,24 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.2.  Configure ACLs</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02.html" title="Chapter 2. How Tos"><link rel="next" href="ch02s03.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. 
+      Configure ACLs
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s03.html">Next</a></td></tr></table><hr></div><div class="section" title="2.2.  Configure ACLs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2990336"></a>2.2. 
+      Configure ACLs
+    </h2></div></div></div><div class="section" title="2.2.1.  Configure ACLs"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-ConfigureACLs"></a>2.2.1. 
+            Configure ACLs
+          </h3></div></div></div><div class="section" title="2.2.1.1.  Specification"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-Specification"></a>2.2.1.1. 
+            Specification
+          </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+              <a class="xref" href="">???</a>
+            </p></li><li class="listitem"><p>
+              <a class="xref" href="">???</a>
+            </p></li></ul></div></div><div class="section" title="2.2.1.2.  C++ Broker"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-CBroker"></a>2.2.1.2. 
+            C++ Broker
+          </h4></div></div></div><p>
+            The C++ broker supports <a class="xref" href="">???</a> of the ACLs
+          </p></div><div class="section" title="2.2.1.3.  Java Broker"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-JavaBroker"></a>2.2.1.3. 
+            Java Broker
+          </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+              <a class="xref" href="">???</a>
+            </p></li><li class="listitem"><p>Support for Version 2 specification is in progress.
+            </p></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s03.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/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s03.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s03.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s03.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s03.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,46 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.3.  Configure Java Qpid to use a SSL connection.</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s02.html" title="2.2.  Configure ACLs"><link rel="next" href="ch02s04.html" title="2.4.  Configure Log4j CompositeRolling Appender"></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.3. 
+      Configure Java Qpid to use a SSL connection.
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s02.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s04.html">Next</a></td></tr></table><hr></div><div class="section" title="2.3.  Configure Java Qpid to use a SSL connection."><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2983093"></a>2.3. 
+      Configure Java Qpid to use a SSL connection.
+    </h2></div></div></div><div class="section" title="2.3.1.  Using SSL connection with Qpid Java."><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-UsingSSLconnectionwithQpidJava."></a>2.3.1. 
+            Using SSL connection with Qpid Java.
+          </h3></div></div></div><p>
+            This section will show how to use SSL to enable secure
+            connections between a Java client and broker.
+          </p></div><div class="section" title="2.3.2.  Setup"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-Setup"></a>2.3.2. 
+            Setup
+          </h3></div></div></div><div class="section" title="2.3.2.1.  Broker Setup"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-BrokerSetup"></a>2.3.2.1. 
+            Broker
+            Setup
+          </h4></div></div></div><p>
+            The broker configuration file (config.xml) needs to be updated to
+            include the SSL keystore location details.
+          </p><pre class="programlisting">
+&lt;!-- Additions required to Connector Section --&gt;
+
+&lt;ssl&gt;
+    &lt;enabled&gt;true&lt;/enabled&gt;
+    &lt;sslOnly&gt;true&lt;/sslOnly&gt;
+    &lt;keystorePath&gt;/path/to/keystore.ks&lt;/keystorePath&gt;
+    &lt;keystorePassword&gt;keystorepass&lt;/keystorePassword&gt;
+&lt;/ssl&gt;
+</pre><p>
+            The sslOnly option is included here for completeness however this
+            will disable the unencrypted port and leave only the SSL port
+            listening for connections.
+          </p></div><div class="section" title="2.3.2.2.  Client Setup"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-ClientSetup"></a>2.3.2.2. 
+            Client
+            Setup
+          </h4></div></div></div><p>
+            The best place to start looking is class
+            <span class="emphasis"><em>SSLConfiguration</em></span> this is provided to the connection
+            during creation however there is currently no example that
+            demonstrates its use.
+          </p></div></div><div class="section" title="2.3.3.  Performing the connection."><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-Performingtheconnection."></a>2.3.3. 
+            Performing
+            the connection.
+          </h3></div></div></div><p></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.2. 
+      Configure ACLs
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.4. 
+      Configure Log4j CompositeRolling Appender
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s04.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s04.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s04.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s04.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,109 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.4.  Configure Log4j CompositeRolling Appender</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s03.html" title="2.3.  Configure Java Qpid to use a SSL connection."><link rel="next" href="ch02s05.html" title="2.5.  Configure the Broker via config.xml"></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.4. 
+      Configure Log4j CompositeRolling Appender
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr></table><hr></div><div class="section" title="2.4.  Configure Log4j CompositeRolling Appender"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3016112"></a>2.4. 
+      Configure Log4j CompositeRolling Appender
+    </h2></div></div></div><div class="section" title="2.4.1.  How to configure the CompositeRolling log4j Appender"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureLog4jCompositeRollingAppender-HowtoconfiguretheCompositeRollinglog4jAppender"></a>2.4.1. 
+            How to configure the CompositeRolling log4j Appender
+          </h3></div></div></div><p>
+            There are several sections of our default log4j file that will
+            need your attention if you wish to fully use this Appender.
+          </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Enable the Appender</p><p>
+            The default log4j.xml file uses the FileAppender, swap this for
+            the ArchivingFileAppender as follows:
+          </p><pre class="programlisting">
+    &lt;!-- Log all info events to file --&gt;
+    &lt;root&gt;
+        &lt;priority value="info"/&gt;
+
+        &lt;appender-ref ref="ArchivingFileAppender"/&gt;
+    &lt;/root&gt;
+</pre></li><li class="listitem"><p>
+            Configure the Appender
+          </p><p>
+            The Appender has a number of parameters that can be adjusted
+            depending on what you are trying to achieve. For clarity lets
+            take a quick look at the complete default appender:
+          </p><pre class="programlisting">
+  &lt;appender name="ArchivingFileAppender" class="org.apache.log4j.QpidCompositeRollingAppender"&gt;
+        &lt;!-- Ensure that logs allways have the dateFormat set--&gt;
+        &lt;param name="StaticLogFileName" value="false"/&gt;
+        &lt;param name="File" value="${QPID_WORK}/log/${logprefix}qpid${logsuffix}.log"/&gt;
+        &lt;param name="Append" value="false"/&gt;
+        &lt;!-- Change the direction so newer files have bigger numbers --&gt;
+        &lt;!-- So log.1 is written then log.2 etc This prevents a lot of file renames at log rollover --&gt;
+        &lt;param name="CountDirection" value="1"/&gt;
+        &lt;!-- Use default 10MB --&gt;
+        &lt;!--param name="MaxFileSize" value="100000"/--&gt;
+        &lt;param name="DatePattern" value="'.'yyyy-MM-dd-HH-mm"/&gt;
+        &lt;!-- Unlimited number of backups --&gt;
+        &lt;param name="MaxSizeRollBackups" value="-1"/&gt;
+        &lt;!-- Compress(gzip) the backup files--&gt;
+        &lt;param name="CompressBackupFiles" value="true"/&gt;
+        &lt;!-- Compress the backup files using a second thread --&gt;
+        &lt;param name="CompressAsync" value="true"/&gt;
+        &lt;!-- Start at zero numbered files--&gt;
+        &lt;param name="ZeroBased" value="true"/&gt;
+        &lt;!-- Backup Location --&gt;
+        &lt;param name="backupFilesToPath" value="${QPID_WORK}/backup/log"/&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;
+</pre><p>
+            The appender configuration has three groups of parameter
+            configuration.
+          </p><p>
+            The first group is for configuration of the file name. The
+            default is to write a log file to QPID_WORK/log/qpid.log
+            (Remembering you can use the logprefix and logsuffix values to
+            modify the file name, see Property Config).
+          </p><pre class="programlisting">
+        &lt;!-- Ensure that logs always have the dateFormat set--&gt;
+        &lt;param name="StaticLogFileName" value="false"/&gt;
+        &lt;param name="File" value="${QPID_WORK}/log/${logprefix}qpid${logsuffix}.log"/&gt;
+        &lt;param name="Append" value="false"/&gt;
+</pre><p>
+            The second section allows the specification of a Maximum File
+            Size and a DatePattern that will be used to move on to the next
+            file.
+          </p><p>
+            When MaxFileSize is reached a new log file will be created
+            The DataPattern is used to decide when to create a new log file,
+            so here a new file will be created for every minute and every
+            10Meg of data. So if 15MB of data is made every minute then there
+            will be two log files created each minute. One at the start of
+            the minute and a second when the file hit 10MB. When the next
+            minute arrives a new file will be made even though it only has
+            5MB of content. For a production system it would be expected to
+            be changed to something like 'yyyy-MM-dd' which would make a new
+            log file each day and keep the files to a max of 10MB.
+          </p><p>
+            The final MaxSizeRollBackups allows you to limit the amount of
+            disk you are using by only keeping the last n backups.
+          </p><pre class="programlisting">
+        &lt;!-- Change the direction so newer files have bigger numbers --&gt;
+        &lt;!-- So log.1 is written then log.2 etc This prevents a lot of file renames at log rollover --&gt;
+        &lt;param name="CountDirection" value="1"/&gt;
+        &lt;!-- Use default 10MB --&gt;
+        &lt;!--param name="MaxFileSize" value="100000"/--&gt;
+        &lt;param name="DatePattern" value="'.'yyyy-MM-dd-HH-mm"/&gt;
+        &lt;!-- Unlimited number of backups --&gt;
+        &lt;param name="MaxSizeRollBackups" value="-1"/&gt;
+</pre><p>
+            The final section allows the old log files to be compressed and
+            copied to a new location.
+          </p><pre class="programlisting">
+        &lt;!-- Compress(gzip) the backup files--&gt;
+        &lt;param name="CompressBackupFiles" value="true"/&gt;
+        &lt;!-- Compress the backup files using a second thread --&gt;
+        &lt;param name="CompressAsync" value="true"/&gt;
+        &lt;!-- Start at zero numbered files--&gt;
+        &lt;param name="ZeroBased" value="true"/&gt;
+        &lt;!-- Backup Location --&gt;
+        &lt;param name="backupFilesToPath" value="${QPID_WORK}/backup/log"/&gt;
+</pre></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.3. 
+      Configure Java Qpid to use a SSL connection.
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.5. 
+      Configure the Broker via config.xml
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s05.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s05.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s05.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s05.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,36 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.5.  Configure the Broker via config.xml</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s04.html" title="2.4.  Configure Log4j CompositeRolling Appender"><link rel="next" href="ch02s06.html" title="2.6.  Configure the Virtual Hosts via virtualhosts.xml"></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.5. 
+      Configure the Broker via config.xml
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s06.html">Next</a></td></tr></table><hr></div><div class="section" title="2.5.  Configure the Broker via config.xml"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3004467"></a>2.5. 
+      Configure the Broker via config.xml
+    </h2></div></div></div><div class="section" title="2.5.1.  Broker config.xml Overview"><div class="titlepage"><div><div><h3 class="title"><a name="ConfiguretheBrokerviaconfig.xml-Brokerconfig.xmlOverview"></a>2.5.1. 
+            Broker config.xml Overview
+          </h3></div></div></div><p>
+            The broker config.xml file which is shipped in the etc directory
+            of any Qpid binary distribution details various options and
+            configuration for the Java Qpid broker implementation.
+          </p><p>
+            In tandem with the virtualhosts.xml file, the config.xml file
+            allows you to control much of the deployment detail for your Qpid
+            broker in a flexible fashion.
+          </p><p>
+            Note that you can pass the config.xml you wish to use for your
+            broker instance to the broker using the -c command line option.
+            In turn, you can specify the paths for the broker password file
+            and virtualhosts.xml files in your config.xml for simplicity.
+          </p><p>
+            For more information about command line configuration options
+            please see <a class="xref" href="">???</a>.
+          </p></div><div class="section" title="2.5.2.  Qpid Version"><div class="titlepage"><div><div><h3 class="title"><a name="ConfiguretheBrokerviaconfig.xml-QpidVersion"></a>2.5.2. 
+            Qpid
+            Version
+          </h3></div></div></div><p>
+            The config format has changed between versions here you can find
+            the configuration details on a per version basis.
+          </p><p>
+            <a class="xref" href="">???</a>
+            <a class="xref" href="">???</a>
+          </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.4. 
+      Configure Log4j CompositeRolling Appender
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.6. 
+      Configure the Virtual Hosts via virtualhosts.xml
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s06.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s06.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s06.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s06.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,99 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.6.  Configure the Virtual Hosts via virtualhosts.xml</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s05.html" title="2.5.  Configure the Broker via config.xml"><link rel="next" href="ch02s07.html" title="2.7.  Debug using log4j"></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.6. 
+      Configure the Virtual Hosts via virtualhosts.xml
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s05.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s07.html">Next</a></td></tr></table><hr></div><div class="section" title="2.6.  Configure the Virtual Hosts via virtualhosts.xml"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3003436"></a>2.6. 
+      Configure the Virtual Hosts via virtualhosts.xml
+    </h2></div></div></div><div class="section" title="2.6.1.  virtualhosts.xml Overview"><div class="titlepage"><div><div><h3 class="title"><a name="ConfiguretheVirtualHostsviavirtualhosts.xml-virtualhosts.xmlOverview"></a>2.6.1. 
+            virtualhosts.xml Overview
+          </h3></div></div></div><p>
+            This configuration file contains details of all queues and
+            topics, and associated properties, to be created on broker
+            startup. These details are configured on a per virtual host
+            basis.
+          </p><p>
+            Note that if you do not add details of a queue or topic you
+            intend to use to this file, you must first create a consumer on a
+            queue/topic before you can publish to it using Qpid.
+          </p><p>
+            Thus most application deployments need a virtualhosts.xml file
+            with at least some minimal detail.
+          </p><div class="section" title="2.6.1.1.  XML Format with Comments"><div class="titlepage"><div><div><h4 class="title"><a name="ConfiguretheVirtualHostsviavirtualhosts.xml-XMLFormatwithComments"></a>2.6.1.1. 
+            XML Format with Comments
+          </h4></div></div></div><p>
+            The virtualhosts.xml which currently ships as part of the Qpid
+            distribution is really targeted at development use, and supports
+            various artifacts commonly used by the Qpid development team.
+          </p><p>
+            As a result, it is reasonably complex. In the example XML below,
+            I have tried to simplify one example virtual host setup which is
+            possibly more useful for new users of Qpid or development teams
+            looking to simply make use of the Qpid broker in their
+            deployment.
+          </p><p>
+            I have also added some inline comments on each section, which
+            should give some extra information on the purpose of the various
+            elements.
+          </p><pre class="programlisting">
+&lt;virtualhosts&gt;
+    &lt;!-- Sets the default virtual host for connections which do not specify a vh --&gt;
+    &lt;default&gt;localhost&lt;/default&gt;
+    &lt;!-- Define a virtual host and all it's config --&gt;
+    &lt;virtualhost&gt;
+        &lt;name&gt;localhost&lt;/name&gt;
+        &lt;localhost&gt;    
+            &lt;!-- Define the types of additional AMQP exchange available for this vh --&gt;   
+            &lt;!-- Always get amq.direct (for queues) and amq.topic (for topics) by default --&gt;     
+            &lt;exchanges&gt;
+                &lt;!-- Example of declaring an additional exchanges type for developer use only --&gt;
+                &lt;exchange&gt;
+                    &lt;type&gt;direct&lt;/type&gt;
+                    &lt;name&gt;test.direct&lt;/name&gt;
+                    &lt;durable&gt;true&lt;/durable&gt;
+                &lt;/exchange&gt;
+            &lt;/exchanges&gt;
+             
+            &lt;!-- Define the set of queues to be created at broker startup --&gt;
+            &lt;queues&gt;
+                &lt;!-- The properties configured here will be applied as defaults to all --&gt;
+                &lt;!-- queues subsequently defined unless explicitly overridden --&gt;
+                &lt;exchange&gt;amq.direct&lt;/exchange&gt;
+                &lt;!-- Set threshold values for queue monitor alerting to log --&gt; 
+                &lt;maximumQueueDepth&gt;4235264&lt;/maximumQueueDepth&gt;  &lt;!-- 4Mb --&gt;
+                &lt;maximumMessageSize&gt;2117632&lt;/maximumMessageSize&gt; &lt;!-- 2Mb --&gt;
+                &lt;maximumMessageAge&gt;600000&lt;/maximumMessageAge&gt;  &lt;!-- 10 mins --&gt;
+
+                &lt;!-- Define a queue with all default settings --&gt;   
+                &lt;queue&gt;
+                    &lt;name&gt;ping&lt;/name&gt;
+                &lt;/queue&gt;
+                &lt;!-- Example definitions of queues with overriden settings --&gt;
+                &lt;queue&gt;
+                    &lt;name&gt;test-queue&lt;/name&gt;
+                    &lt;test-queue&gt;
+                        &lt;exchange&gt;test.direct&lt;/exchange&gt;
+                        &lt;durable&gt;true&lt;/durable&gt;
+                    &lt;/test-queue&gt;
+                &lt;/queue&gt;
+                &lt;queue&gt;
+                    &lt;name&gt;test-ping&lt;/name&gt;
+                    &lt;test-ping&gt;
+                        &lt;exchange&gt;test.direct&lt;/exchange&gt;
+                    &lt;/test-ping&gt;
+                &lt;/queue&gt;
+            &lt;/queues&gt;
+        &lt;/localhost&gt;
+    &lt;/virtualhost&gt;
+&lt;/virtualhosts&gt;
+</pre></div><div class="section" title="2.6.1.2.  Using your own virtualhosts.xml"><div class="titlepage"><div><div><h4 class="title"><a name="ConfiguretheVirtualHostsviavirtualhosts.xml-Usingyourownvirtualhosts.xml"></a>2.6.1.2. 
+            Using your own virtualhosts.xml
+          </h4></div></div></div><p>
+            Note that the config.xml file shipped as an example (or developer
+            default) in the Qpid distribution contains an element which
+            defines the path to the virtualhosts.xml.
+          </p><p>
+            When using your own virtualhosts.xml you must edit this path to
+            point at the location of your file.
+          </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.5. 
+      Configure the Broker via config.xml
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.7. 
+      Debug using log4j
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s07.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s07.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s07.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s07.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,251 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.7.  Debug using log4j</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s06.html" title="2.6.  Configure the Virtual Hosts via virtualhosts.xml"><link rel="next" href="ch02s08.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="ch02s06.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s08.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="id2973019"></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="ch02s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s08.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/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s08.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s08.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s08.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s08.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,104 @@
+<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><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s07.html" title="2.7.  Debug using log4j"><link rel="next" href="ch02s09.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="ch02s07.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s09.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="id3004406"></a><p class="title"><b>Table 2.2. </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="ch02s07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s09.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/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s09.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s09.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s09.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s09.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,211 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.9.  Qpid Java Build How To</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s08.html" title="2.8.  How to Tune M3 Java Broker Performance"><link rel="next" href="ch02s10.html" title="2.10.  Use Priority Queues"></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.9. 
+      Qpid Java Build How To
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s08.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s10.html">Next</a></td></tr></table><hr></div><div class="section" title="2.9.  Qpid Java Build How To"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2970808"></a>2.9. 
+      Qpid Java Build How To
+    </h2></div></div></div><div class="section" title="2.9.1.  Build Instructions - General"><div class="titlepage"><div><div><h3 class="title"><a name="QpidJavaBuildHowTo-BuildInstructionsGeneral"></a>2.9.1. 
+            Build
+            Instructions - General
+          </h3></div></div></div><div class="section" title="2.9.1.1.  Check out the source"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-Checkoutthesource"></a>2.9.1.1. 
+            Check out the
+            source
+          </h4></div></div></div><p>
+            Firstly, check the source for Qpid out of our subversion
+            repository:
+          </p><p>
+            <a class="xref" href="">???</a>
+          </p></div><div class="section" title="2.9.1.2.  Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-Prerequisites"></a>2.9.1.2. 
+            Prerequisites
+          </h4></div></div></div><p>
+            For the broker code you need JDK 1.5.0_15 or later. You should
+            set JAVA_HOME and include the bin directory in your PATH.
+          </p><p>
+            Check it's ok by executing java -v !
+          </p><p>
+            If you are wanting to run the python tests against the broker you
+            will of course need a version of python.
+          </p></div></div><div class="section" title="2.9.2.  Build Instructions - Trunk"><div class="titlepage"><div><div><h3 class="title"><a name="QpidJavaBuildHowTo-BuildInstructionsTrunk"></a>2.9.2. 
+            Build
+            Instructions - Trunk
+          </h3></div></div></div><p>
+            Our build system has reverted to ant as of May 2008.
+          </p><p>
+            The ant target 'help' will tell you what you need to know about
+            the build system.
+          </p><div class="section" title="2.9.2.1.  Ant Build Scripts"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-AntBuildScripts"></a>2.9.2.1. 
+            Ant Build
+            Scripts
+          </h4></div></div></div><p>
+            Currently the Qpid java project builds using ant.
+          </p><p>
+            The ant build system is set up in a modular way, with a top level
+            build script and template for module builds and then a module
+            level build script which inherits from the template.
+          </p><p>
+            So, at the top level there are:
+          </p><div class="table"><a name="id2991214"></a><p class="title"><b>Table 2.3. </b></p><div class="table-contents"><table summary="" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+                  File
+                </td><td>
+                  Description
+                </td></tr><tr><td>
+                  build.xml
+                </td><td>
+                  Top level build file for the project which defines all the
+                  build targets
+                </td></tr><tr><td>
+                  common.xml
+                </td><td>
+                  Common properties used throughout the build system
+                </td></tr><tr><td>
+                  module.xml
+                </td><td>
+                  Template used by all modules which sets up properties for
+                  module builds
+                </td></tr></tbody></table></div></div><br class="table-break"><p>
+            Then, in each module subdirectory there is:
+          </p><div class="table"><a name="id3014337"></a><p class="title"><b>Table 2.4. </b></p><div class="table-contents"><table summary="" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+                  File
+                </td><td>
+                  Description
+                </td></tr><tr><td>
+                  build.xml
+                </td><td>
+                  Defines all the module values for template properties
+                </td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="2.9.2.2.  Build targets"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-Buildtargets"></a>2.9.2.2. 
+            Build targets
+          </h4></div></div></div><p>
+            The main build targets you are probably interested in are:
+          </p><div class="table"><a name="id3010121"></a><p class="title"><b>Table 2.5. </b></p><div class="table-contents"><table summary="" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+                  Target
+                </td><td>
+                  Description
+                </td></tr><tr><td>
+                  build
+                </td><td>
+                  Builds all source code for Qpid
+                </td></tr><tr><td>
+                  test
+                </td><td>
+                  Runs the testsuite for Qpid
+                </td></tr></tbody></table></div></div><br class="table-break"><p>
+            So, if you just want to compile everything you should run the
+            build target in the top level build.xml file.
+          </p><p>
+            If you want to build an installable version of Qpid, run the
+            archive task from the top level build.xml file.
+          </p><p>
+            If you want to compile an individual module, simply run the build
+            target from the appropriate module e.g. to compile the broker
+            source
+          </p></div><div class="section" title="2.9.2.3.  Configuring Eclipse"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-ConfiguringEclipse"></a>2.9.2.3. 
+            Configuring
+            Eclipse
+          </h4></div></div></div><p>
+            1. Run the ant build from the root directory of Java trunk.
+            2. New project -&gt; create from existing file system for broker,
+            common, client, junit-toolkit, perftests, systests and each
+            directory under management
+            4. Add the contents of lib/ to the build path
+            5. Setup Generated Code
+            6. Setup Dependencies
+          </p><div class="section" title="2.9.2.3.1.  Generated Code"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaBuildHowTo-GeneratedCode"></a>2.9.2.3.1. 
+            Generated Code
+          </h5></div></div></div><p>
+            The Broker and Common packages both depend on generated code.
+            After running 'ant' the build/scratch directory will contain this
+            generated code.
+            For the broker module add build/scratch/broker/src
+            For the common module add build/scratch/common/src
+          </p></div><div class="section" title="2.9.2.3.2.  Dependencies"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaBuildHowTo-Dependencies"></a>2.9.2.3.2. 
+            Dependencies
+          </h5></div></div></div><p>
+            These dependencies are correct at the time of writting however,
+            if things are not working you can check the dependencies by
+            looking in the modules build.xml file:
+          </p><pre class="programlisting">
+for i in `find . -name build.xml` ; do echo "$i:"; grep module.depends $i ; done
+</pre><p>
+            The <span class="emphasis"><em>module.depend</em></span> value will detail which other modules
+            are dependencies.
+          </p><p>
+            broker
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>management/common
+            </p></li></ul></div><p>
+            client
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Common
+            </p></li></ul></div><p>
+            systest
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>management/common
+            </p></li><li class="listitem"><p>broker
+            </p></li><li class="listitem"><p>broker/test
+            </p></li><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>junit-toolkit
+            </p></li><li class="listitem"><p>management/tools/qpid-cli
+            </p></li></ul></div><p>
+            perftests
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>systests
+            </p></li><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>broker
+            </p></li><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>junit-toolkit
+            </p></li></ul></div><p>
+            management/eclipse-plugin
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>broker
+            </p></li><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>management/common
+            </p></li></ul></div><p>
+            management/console
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>client
+            </p></li></ul></div><p>
+            management/agent
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>client
+            </p></li></ul></div><p>
+            management/tools/qpid-cli
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>management/common
+            </p></li></ul></div><p>
+            management/client
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>client
+            </p></li></ul></div><p>
+            integrationtests
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>systests
+            </p></li><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>junit-toolkit
+            </p></li></ul></div><p>
+            testkit
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>broker
+            </p></li><li class="listitem"><p>common
+            </p></li></ul></div><p>
+            tools
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>common
+            </p></li></ul></div><p>
+            client/examples
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>client
+            </p></li></ul></div><p>
+            broker-plugins
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>client
+            </p></li><li class="listitem"><p>management/common
+            </p></li><li class="listitem"><p>broker
+            </p></li><li class="listitem"><p>common
+            </p></li><li class="listitem"><p>junit-toolkit
+            </p></li></ul></div></div></div><div class="section" title="2.9.2.4.  What next ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaBuildHowTo-Whatnext-3F"></a>2.9.2.4. 
+            What next ?
+          </h4></div></div></div><p>
+            If you want to run your built Qpid package, see our <a class="xref" href="">???</a> for details of
+            how to do that.
+          </p><p>
+            If you want to run our tests, you can use the ant test or
+            testreport (produces a useful report) targets.
+          </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s08.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s10.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.8. 
+      How to Tune M3 Java Broker Performance
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.10. 
+      Use Priority Queues
+    </td></tr></table></div></body></html>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s10.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s10.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s10.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s10.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,96 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.10.  Use Priority Queues</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s09.html" title="2.9.  Qpid Java Build How To"><link rel="next" href="ch02s11.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="ch02s09.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch02s11.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="id3009495"></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="ch02s09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s11.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>

Added: qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s11.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s11.html?rev=1042462&view=auto
==============================================================================
--- qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s11.html (added)
+++ qpid/site/docs/books/0.8/AMQP-Messaging-Broker-Java-Book/html/ch02s11.html Sun Dec  5 21:59:22 2010
@@ -0,0 +1,165 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.11. Slow Consumer Disconnect - User Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title=""><link rel="up" href="ch02.html" title="Chapter 2. How Tos"><link rel="prev" href="ch02s10.html" title="2.10.  Use Priority Queues"><link rel="next" href="ch03.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="ch02s10.html">Prev</a> </td><th width="60%" align="center">Chapter 2. How Tos</th><td width="20%" align="right"> <a accesskey="n" href="ch03.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="id3012461"></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="id3015241"></a>2.11.1. Introduction</h3></div></div></div><p>
+
+   </p><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>
+
+   </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>
+
+   </p><p>Cases where a consumer is 'slow' can arise due to one of the following: poor network
+        connectivity exists; a transitory 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>
+
+   </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><p>
+
+   </p></div><div class="section" title="2.11.2. What can it do?"><div class="titlepage"><div><div><h3 class="title"><a name="id2990645"></a>2.11.2. What can it do?</h3></div></div></div><p>
+
+   </p><p>SCD is only applicable to topics and durable subscriptions and can be configured on either
+        topic or a subscription name. </p><p>
+
+   </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><p>
+
+   </p></div><div class="section" title="2.11.3. Frequency of SCD Checking"><div class="titlepage"><div><div><h3 class="title"><a name="id2987258"></a>2.11.3. Frequency of SCD Checking</h3></div></div></div><p>
+
+   </p><div class="section" title="2.11.3.1. Configuring Frequency"><div class="titlepage"><div><div><h4 class="title"><a name="id2990212"></a>2.11.3.1. <span class="bold"><strong>Configuring Frequency</strong></span></h4></div></div></div><p>
+
+    </p><p>You can configure the frequency with which the SCD process will check for slow consumers,
+          along with the unit of time you're using to specify that frequency. </p><p>
+
+    </p><p><span class="italic">virtualhosts.virtualhost.slow-consumer-detection. delay</span>
+          and <span class="italic">.timeunit</span> are the elements used to specify the
+          frequency and timeunit for that frequency on the virtualhosts.xml file e.g. </p><p> </p><p> &lt;virtualhosts&gt;</p><p>     &lt;default&gt;test&lt;/default&gt; </p><p>     &lt;virtualhost&gt; </p><p>         &lt;name&gt;test&lt;/name&gt; </p><p>         &lt;test&gt; </p><p>            &lt;slow-consumer-detection&gt; </p><p>                 &lt;delay&gt;60&lt;delay/&gt; </p><p>                 &lt;timeunit&gt;seconds&lt;timeunit/&gt; </p><p>             &lt;slow-consumer-detection/&gt; </p><p>         &lt;/test&gt; </p><p>     &lt;/virtualhost&gt; </p><p>
+&lt;/virtualhosts&gt;
+    </p><p>
+
+    </p></div><div class="section" title="2.11.3.2. SCD Log output"><div class="titlepage"><div><div><h4 class="title"><a name="id2983064"></a>2.11.3.2. <span class="bold"><strong>SCD Log output</strong></span></h4></div></div></div><p>
+
+    </p><p>
+When the SCD component finds a queue with a configured threshold to check, the operational logging component (if enabled) will log:
+    </p><p>
+SCD-1003 : Checking Status of Queue
+    </p><p>
+
+    </p></div></div><div class="section" title="2.11.4. Client Exceptions"><div class="titlepage"><div><div><h3 class="title"><a name="id2974019"></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><p> </p><p>
+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
+   </p><p>
+pool-2-thread-3 2010-09-01 16:23:34,238 INFO [apache.qpid.client.AMQConnection] Closing AMQConnection due to
+   </p><p>
+:org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow. /[error code 506: resource error/]
+   </p><p>
+javax.jms.JMSException: 506
+   </p><p>
+ at org.apache.qpid.client.AMQConnection.exceptionReceived(AMQConnection.java:1396)
+   </p><p>
+ at org.apache.qpid.client.protocol.AMQProtocolHandler.exception(AMQProtocolHandler.java:329)
+   </p><p>
+ at org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:536)
+   </p><p>
+ at org.apache.qpid.client.protocol.AMQProtocolSession.methodFrameReceived(AMQProtocolSession.java:453)
+   </p><p>
+ at org.apache.qpid.framing.AMQMethodBodyImpl.handle(AMQMethodBodyImpl.java:93)
+   </p><p>
+ at org.apache.qpid.client.protocol.AMQProtocolHandler$1.run(AMQProtocolHandler.java:462)
+   </p><p>
+ at org.apache.qpid.pool.Job.processAll(Job.java:110)
+   </p><p>
+ at org.apache.qpid.pool.Job.run(Job.java:149)
+   </p><p>
+ at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:885)
+   </p><p>
+ at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:907)
+   </p><p>
+ at java.lang.Thread.run(Thread.java:619)
+   </p><p>
+Caused by: org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow. /[error code 506: resource error/]
+   </p><p>
+ at org.apache.qpid.client.handler.ChannelCloseMethodHandler.methodReceived(ChannelCloseMethodHandler.java:96)
+   </p><p>
+ at org.apache.qpid.client.handler.ClientMethodDispatcherImpl.dispatchChannelClose(ClientMethodDispatcherImpl.java:163)
+   </p><p>
+ at org.apache.qpid.framing.amqp_8_0.ChannelCloseBodyImpl.execute(ChannelCloseBodyImpl.java:140)
+   </p><p>
+ at org.apache.qpid.client.state.AMQStateManager.methodReceived(AMQStateManager.java:112)
+   </p><p>
+ at org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:511)
+   </p><p>
+ ... 8 more
+   </p><p>
+main 2010-09-01 16:23:34,316 INFO /[apache.qpid.client.AMQSession/] Closing session: org.apache.qpid.client.AMQSession_0_8@ffeef1
+   </p><p>
+
+   </p></div><div class="section" title="2.11.5. Disconnection Thresholds"><div class="titlepage"><div><div><h3 class="title"><a name="id3017482"></a>2.11.5. Disconnection Thresholds</h3></div></div></div><p>
+
+   </p><div class="section" title="2.11.5.1. Topic Subscriptions"><div class="titlepage"><div><div><h4 class="title"><a name="id2980972"></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><p>
+
+    </p></div><div class="section" title="2.11.5.2. Durable Topic Subscriptions"><div class="titlepage"><div><div><h4 class="title"><a name="id2980981"></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><p>
+
+    </p></div><div class="section" title="2.11.5.3. Message Age Threshold"><div class="titlepage"><div><div><h4 class="title"><a name="id2974401"></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="id3013649"></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><p>
+
+    </p></div><div class="section" title="2.11.5.5. Message Count Threshold"><div class="titlepage"><div><div><h4 class="title"><a name="id2997963"></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><p>
+
+    </p></div><div class="section" title="2.11.5.6. Delete Policy"><div class="titlepage"><div><div><h4 class="title"><a name="id3010978"></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 topicDelete element in your configuration, then only temporary
+          queues associated with a topic subscription will be delete 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><p>
+- enable SCD checking for your virtual host
+    </p><p>
+- specify frequency for SCD checking
+    </p><p>
+- define thresholds for the topic
+    </p><p>
+- define the policy to apply on trigger
+    </p><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><p>&lt;topics&gt; </p><p>     &lt;topic&gt; </p><p>     &lt;name&gt;stocks.us.*&lt;/name&gt; </p><p>     &lt;slow-consumer-detection&gt; </p><p>         &lt;!-- The maximum depth before which the policy will be applied--&gt; </p><p>         &lt;depth&gt;4235264&lt;/depth&gt; </p><p>         &lt;!-- The maximum message age before which the policy will be applied--&gt; </p><p>         &lt;messageAge&gt;600000&lt;/messageAge&gt; </p><p>         &lt;!-- The maximum number of message before which the policy will be
+          applied--&gt; </p><p>         &lt;messageCount&gt;50&lt;/messageCount&gt; </p><p>         &lt;!-- Policy Selection --&gt; </p><p>         &lt;policy name="TopicDelete"/&gt; </p><p>     &lt;/slow-consumer-detection&gt; </p><p>     &lt;/topic&gt; </p><p>&lt;/topics&gt; </p></div></div><div class="section" title="2.11.6. Important Points To Note"><div class="titlepage"><div><div><h3 class="title"><a name="id3000505"></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>
+
+   </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><p>
+
+   </p><p>
+
+   </p><p>
+
+   </p><p>
+
+   </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s10.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch03.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>



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


Mime
View raw message