<?xml version="1.0"?>
<!--

 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Appendix-PooledConnecytionFactory">
  <title>PooledConnectionFactory</title>
  <para>Qpid client provides <literal>PooledConnectionFactory</literal> which is a special
    implementation of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ConnectionFactory.html">ConnectionFactory</link> supporting <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/Connection.html">Connection</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ConnectionFactory.html">ConnectionFactory</link> 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">
&lt;bean id="pooledConnectionFactory" class="org.apache.qpid.client.PooledConnectionFactory"&gt;
  &lt;!-- set maximum number of pool connections to 20--&gt;
  &lt;property name="maxPoolSize" value="20"&gt;&lt;/property&gt;
  &lt;!-- set the timeout for connection to remain open in pool without being used --&gt;
  &lt;property name="connectionTimeout" value="60000"&gt;&lt;/property&gt;
  &lt;!-- set connection URL as String --&gt;
  &lt;property name="connectionURLString" value="amqp://guest:guest@clientid/default?brokerlist='tcp://localhost:5672?retries='300'&amp;failover='nofailover''&amp;maxprefetch='0'"&gt;&lt;/property&gt;
&lt;/bean&gt;</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">
&lt;bean id="jmsProducerTemplate" class="org.springframework.jms.core.JmsTemplate"&gt;
    &lt;!-- set reference to pooledConnectionFactory bean --&gt;
    &lt;property name="connectionFactory" ref="pooledConnectionFactory"&gt;&lt;/property&gt;
    &lt;property name="defaultDestination" ref="destination" /&gt;
&lt;/bean&gt;

&lt;bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"&gt;
    &lt;!-- set reference to pooledConnectionFactory bean --&gt;
    &lt;property name="connectionFactory" ref="pooledConnectionFactory"/&gt;
    &lt;property name="destination" ref="destination"/&gt;
    &lt;property name="messageListener" ref="messageListener" /&gt;
&lt;/bean&gt;</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>