Author: orudyy
Date: Fri May 22 16:21:08 2015
New Revision: 1681159
URL: http://svn.apache.org/r1681159
Log:
QPID-6534: Add documentation for PooledConnectionFactory
Modified:
qpid/java/trunk/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
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=1681159&r1=1681158&r2=1681159&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
Fri May 22 16:21:08 2015
@@ -593,4 +593,71 @@ 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'&failover='nofailover''&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: [email protected]
For additional commands, e-mail: [email protected]
