Return-Path: 
 <commits-return-29599-apmail-qpid-commits-archive=qpid.apache.org@qpid.apache.org>
X-Original-To: apmail-qpid-commits-archive@www.apache.org
Delivered-To: apmail-qpid-commits-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 6ADA918EDB
	for <apmail-qpid-commits-archive@www.apache.org>;
 Mon, 25 May 2015 09:50:38 +0000 (UTC)
Received: (qmail 56577 invoked by uid 500); 25 May 2015 09:50:35 -0000
Delivered-To: apmail-qpid-commits-archive@qpid.apache.org
Received: (qmail 56552 invoked by uid 500); 25 May 2015 09:50:35 -0000
Mailing-List: contact commits-help@qpid.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@qpid.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@qpid.apache.org>
List-Post: <mailto:commits@qpid.apache.org>
List-Id: <commits.qpid.apache.org>
Reply-To: dev@qpid.apache.org
Delivered-To: mailing list commits@qpid.apache.org
Received: (qmail 56543 invoked by uid 99); 25 May 2015 09:50:35 -0000
Received: from eris.apache.org (HELO hades.apache.org) (140.211.11.105)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 25 May 2015 09:50:35 +0000
Received: from hades.apache.org (localhost [127.0.0.1])
	by hades.apache.org (ASF Mail Server at hades.apache.org) with ESMTP id
 34AB5AC055A
	for <commits@qpid.apache.org>; Mon, 25 May 2015 09:50:35 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1681574 - in
 /qpid/java/trunk/doc/book/src/jms-client-0-8:
 JMS-Client-Appendix-PooledConnectionFactory.xml JMS-Client-Book.xml
 JMS-Client-Understanding.xml
Date: Mon, 25 May 2015 09:50:35 -0000
To: commits@qpid.apache.org
From: kwall@apache.org
X-Mailer: svnmailer-1.0.9
Message-Id: <20150525095035.34AB5AC055A@hades.apache.org>

Author: kwall
Date: Mon May 25 09:50:34 2015
New Revision: 1681574

URL: http://svn.apache.org/r1681574
Log:
QPID-6534: [Java Broker Documentation] Move pool docs into separate annex and correct a couple of typos and improve formatting

Added:
    qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Appendix-PooledConnectionFactory.xml
Modified:
    qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
    qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml

Added: qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Appendix-PooledConnectionFactory.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Appendix-PooledConnectionFactory.xml?rev=1681574&view=auto
==============================================================================
--- qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Appendix-PooledConnectionFactory.xml (added)
+++ qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Appendix-PooledConnectionFactory.xml Mon May 25 09:50:34 2015
@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<appendix id="JMS-Client-0-8-Appendix-PooledConnecytionFactory">
+  <title>PooledConnectionFactory</title>
+  <para>Qpid client provides <literal>PooledConnectionFactory</literal> which is a special
+    implementation of <ulink url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html"
+      >ConnectionFactory</ulink> supporting <ulink url="&oracleJeeDocUrl;javax/jms/Connection.html"
+      >Connection</ulink> pooling. </para>
+  <para> The <literal>PooledConnectionFactory</literal> caches a predefined number of connections
+    thus saving an application which connects frequently time. The <literal>Connection</literal>
+    instance is taken from the pool whenever method
+      <literal>PooledConnectionFactory#createConnection()</literal> is invoked and returned into the
+    pool when method <literal>Connection#close()</literal> is called.</para>
+  <para>A user can configure a maximum allowed number of connections to remain in pool (10 by
+    default) by calling <literal>PooledConnectionFactory#setMaxPoolSize(int)</literal>. When number
+    of connections exceeds the value set for maximum pool size,
+      <literal>PooledConnectionFactory</literal> starts to work as a normal <ulink
+      url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink> and creates
+    a new connection every time method <literal>PooledConnectionFactory#createConnection()</literal>
+    is invoked.</para>
+  <para>The <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link> is set by invoking
+    method <literal>PooledConnectionFactory#setConnectionURLString(String)</literal>.</para>
+  <para>A user can specify the maximum time a connection may remain idle in pool by calling
+      <literal>PooledConnectionFactory#setConnectionTimeout(long)</literal> passing a value in
+    milliseconds. If connection is not used within the specified interval it is closed
+    automatically. </para>
+  <para>This implementation can be useful in <emphasis>Spring JMS</emphasis> based applications. An
+    example below demonstrates how to configure <literal>PooledConnectionFactory</literal> in the
+    Spring xml configuration. <example>
+      <title>Example of configuring <emphasis>PooledConnectionFactory</emphasis> in spring xml
+        configuration.</title>
+      <programlisting language="xml"><![CDATA[
+<bean id="pooledConnectionFactory" class="org.apache.qpid.client.PooledConnectionFactory">
+  <!-- set maximum number of pool connections to 20-->
+  <property name="maxPoolSize" value="20"></property>
+  <!-- set the timeout for connection to remain open in pool without being used -->
+  <property name="connectionTimeout" value="60000"></property>
+  <!-- set connection URL as String -->
+  <property name="connectionURLString" value="amqp://guest:guest@clientid/default?brokerlist='tcp://localhost:5672?retries='300'&amp;failover='nofailover''&amp;maxprefetch='0'"></property>
+</bean>]]></programlisting>
+    </example>
+  </para>
+  <para>
+    <emphasis>PooledConnectionFactory</emphasis> spring bean can be configured with such
+      <emphasis>spring-jms</emphasis> beans like
+      <emphasis>DefaultMessageListenerContainer</emphasis> and <emphasis>JmsTemplate</emphasis>. The
+    example below demonstrates how to do that <example>
+      <title>Examples of configuring <emphasis>PooledConnectionFactory</emphasis> with
+          <emphasis>DefaultMessageListenerContainer</emphasis> and
+        <emphasis>JmsTemplate</emphasis>.</title>
+      <programlisting language="xml"><![CDATA[
+<bean id="jmsProducerTemplate" class="org.springframework.jms.core.JmsTemplate">
+    <!-- set reference to pooledConnectionFactory bean -->
+    <property name="connectionFactory" ref="pooledConnectionFactory"></property>
+    <property name="defaultDestination" ref="destination" />
+</bean>
+
+<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
+    <!-- set reference to pooledConnectionFactory bean -->
+    <property name="connectionFactory" ref="pooledConnectionFactory"/>
+    <property name="destination" ref="destination"/>
+    <property name="messageListener" ref="messageListener" />
+</bean>]]></programlisting>
+    </example>
+  </para>
+  <note>
+    <para>If using <literal>DefaultMessageListenerContainer</literal> with
+        <literal>cacheLevel</literal> set to <literal>NONE</literal> it is important that
+        <literal>maxConcurrentConsumer</literal> does not exceed the value of maximum pool size set
+      on <literal>PooledConnectionFactory</literal> bean. If this is not the case, once the number
+      of in-use connections reaches the the <emphasis>PooledConnectionFactory#maxPoolSize</emphasis>
+      a new connection will be opened for each and every message receipt i.e. a connection per
+      message anti-pattern.</para>
+  </note>
+</appendix>

Modified: qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Book.xml?rev=1681574&r1=1681573&r2=1681574&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Book.xml (original)
+++ qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Book.xml Mon May 25 09:50:34 2015
@@ -40,7 +40,8 @@
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Exceptions.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Maven.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/>
-  
+   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-PooledConnectionFactory.xml"/>
+ 
  
 
 </book>

Modified: qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml?rev=1681574&r1=1681573&r2=1681574&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml (original)
+++ qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml Mon May 25 09:50:34 2015
@@ -65,7 +65,9 @@
     <para>The examples in the previous chapter illustrated the Java code required to <link
         linkend="JMS-Client-0-8-Examples-PTP">create the InitialContext</link> and an <link
         linkend="JMS-Client-0-8-Examples-PTP-PropertiesFile">example properties file</link>.</para>
-    <para>Note that the Qpid Broker does not present a JNDI interface to the application.</para>
+    <para>The Qpid JMS client also provides an alternate connection factory implementation providing a
+      connection pool. This can be useful when utilsing frameworks such as Spring. 
+      <xref linkend="JMS-Client-0-8-Appendix-PooledConnecytionFactory"/>.</para>
     <figure>
       <title>JNDI overview</title>
       <mediaobject>
@@ -74,6 +76,7 @@
         </imageobject>
       </mediaobject>
     </figure>
+    <para>Note that the Qpid Broker does not present a JNDI interface to the application.</para>
   </section>
   <section id="JMS-Client-0-8-Client-Understanding-Connection">
     <title>Connection</title>
@@ -593,71 +596,4 @@ amqp://guest:guest@clientid/?brokerlist=
         <literal>queue.</literal> and <literal>topic.</literal> prefix to create Queues and Topics
       objects respectively. </para>
   </section>
-  <section id="JMS-Client-0-8-Client-Understanding-PooledConnectionFactory">
-    <title>PooledConnectionFactory</title>
-    <para>Qpid client provides <emphasis>PooledCollectionFactory</emphasis> which is a special
-      implementation of <ulink url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink>
-      allowing <ulink url="&oracleJeeDocUrl;javax/jms/Connection.html" >Connection</ulink> pooling.
-    </para>
-    <para>
-      The <emphasis>PooledCollectionFactory</emphasis> can cache a predefined number of connections
-      saving the application time required to establish the connectivity. The <emphasis>Connection</emphasis>
-      instance is taken from a pool when method <emphasis>PooledCollectionFactory#createConnection()</emphasis>
-      is invoked and returned into a pool when method <emphasis>Connection#close()</emphasis> is called.
-      A user can configure a maximum allowed number of connections to retain in pool by calling
-      <emphasis>PooledCollectionFactory#setMaxPoolSize(int)</emphasis>. When number of connections exceeds the value
-      set for maximum pool size (10 by default), <emphasis>PooledCollectionFactory</emphasis> starts working
-      as ordinary <ulink url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink> and
-      creates a new connection every time when method <emphasis>PooledCollectionFactory#createConnection()</emphasis>
-      is invoked. The <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link> can be set by invoking method
-      <emphasis>PooledCollectionFactory#setConnectionURLString(String)</emphasis>. A user can set a connection time
-      to remain open in pool (in milliseconds) by calling <emphasis>PooledCollectionFactory#setConnectionTimeout(long)</emphasis>.
-      If pooled <emphasis>Connection</emphasis> is not used during specified interval it is get closed automatically.
-    </para>
-    <para>This implementation can be handy in <emphasis>spring-jms</emphasis> based applications. An example below
-      demonstrates how to configure <emphasis>PooledCollectionFactory</emphasis> in spring xml configuration.
-      <example>
-        <title>Example of configuring  <emphasis>PooledCollectionFactory</emphasis> in spring xml configuration.</title>
-        <programlisting language="xml"><![CDATA[
-<bean id="pooledConnectionFactory" class="org.apache.qpid.client.PooledConnectionFactory">
-  <!-- set maximum pool size to 20-->
-  <property name="maxPoolSize" value="20"></property>
-  <!-- set the timeout for connection to remain open in pool without being used -->
-  <property name="connectionTimeout" value="60000"></property>
-  <!-- set connection URL as String -->
-  <property name="connectionURLString" value="amqp://guest:guest@clientid/default?brokerlist='tcp://localhost:5672?retries='300'&amp;failover='nofailover''&amp;maxprefetch='0'"></property>
-</bean>]]></programlisting>
-      </example>
-    </para>
-    <para>
-      <emphasis>PooledCollectionFactory</emphasis> spring bean can be configured with such
-      <emphasis>spring-jms</emphasis> beans like  <emphasis>DefaultMessageListenerContainer</emphasis> and
-      <emphasis>JmsTemplate</emphasis>. An example below demonstrates how to do that
-      <example>
-        <title>Examples of configuring  <emphasis>PooledCollectionFactory</emphasis> with
-          <emphasis>DefaultMessageListenerContainer</emphasis> and <emphasis>JmsTemplate</emphasis>.</title>
-        <programlisting language="xml"><![CDATA[
-<bean id="jmsProducerTemplate" class="org.springframework.jms.core.JmsTemplate">
-    <!-- set reference to pooledConnectionFactory bean -->
-    <property name="connectionFactory" ref="pooledConnectionFactory"></property>
-    <property name="defaultDestination" ref="destination" />
-</bean>
-
-<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
-    <!-- set reference to pooledConnectionFactory bean -->
-    <property name="connectionFactory" ref="pooledConnectionFactory"/>
-    <property name="destination" ref="destination"/>
-    <property name="messageListener" ref="messageListener" />
-</bean>]]></programlisting>
-      </example>
-    </para>
-    <note>
-      <para>Please note, that with  <emphasis>DefaultMessageListenerContainer</emphasis> having <emphasis>cachLevel</emphasis>
-        set to <emphasis>NONE</emphasis> the value set for <emphasis>maxConcurrentConsumer</emphasis> should not exceed
-        a value for maximum pool size set on  <emphasis>PooledCollectionFactory</emphasis> bean, otherwise, after reaching
-        a number of connections above <emphasis>PooledCollectionFactory#maxPoolSize</emphasis> a new connection will
-        be opened on each message receipt.
-      </para>
-    </note>
-  </section>
 </chapter>



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