QPID-6434: [Java Client] Update existing JMS client documentation for AMQP 0.8/0.9.x to cover the effect of setting maxprefetch to 0

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1664592 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 27 insertions, 0 deletions

diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
index b750c8e19c..fdef79c22c 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
@@ -326,6 +326,33 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
             <emphasis>Session#SESSION_TRANSACTED</emphasis> ) or received messages are acknowledged
           (for <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis>).</para>
       </note>
+      <para>
+          Settings maxprefetch to 0 ( either globally via JVM system property
+          <link linkend="JMS-Client-0-8-System-Properties-Maxprefetch" ><literal>max_prefetch</literal></link>
+          or on a connection level as a connection option
+          <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"><literal>maxprefetch</literal></link> )
+          switches off the pre-fetching functionality. With maxprefetch=0 messages are fetched one by one without caching on the client.
+      </para>
+      <note>
+          <para>
+              Setting maxprefetch to 0 is recommended in sping-jms-based applications when
+              <emphasis>DefaultMassgeListenerContainer</emphasis> is configured with <emphasis>CachingConnectionFactory</emphasis>
+              and has <emphasis>cacheLevel</emphasis> set to either <emphasis>CACHE_CONSUMER</emphasis> or <emphasis>CACHE_SESSION</emphasis>
+              and dynamic consumer  scaling (concurrentConsumers!=maxConcurrentConsumers). With such configuration
+              <emphasis>DefaultMassgeListenerContainer</emphasis> can create new <emphasis>MessageConsumer</emphasis>
+              invokers and delete existing <emphasis>MessageConsumer</emphasis> invokers dynamically. On deletion of
+              <emphasis>MessageConsumer</emphasis> invoker, its JMS <emphasis>Session</emphasis> and <emphasis>MessageConsumer</emphasis>
+              are closed. However, with <emphasis>CachingConnectionFactory</emphasis> JMS <emphasis>Session</emphasis>
+              proxy objects are used and when method <emphasis>close</emphasis> of session proxy is invoked, the real Qpid
+              JMS <emphasis>Session</emphasis> object is not get closed. It can be returned into the session cache in active state.
+              If maxprefetch is not 0, the cached Qpid <emphasis>Session</emphasis> might have prefetched messages and
+              it even might continue prefetching of the messages until its prefetch limit is reached. As result,
+              because of prefetched messages being stack in not used cached <emphasis>Session</emphasis>,
+              the message flow between client and broker can stop making an impression as if message consumption is hang.
+              Setting maxprefetch to 0 prevents this problem from occurring.
+              <emphasis>SingleConnectionFactory</emphasis> should be used with maxprefetch>0.
+          </para>
+      </note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">
       <title>TemporaryQueues</title>