<?xml version="1.0" encoding="UTF-8"?>
<chapter id="deployment">
   <title>Deployment</title>

   <para>The IronJacamar distribution contains a deploy/ directory where all deployments
     should be deployed to.</para>

   <section id="packagingrequirements">
      <title>Packaging requirements</title>

      <para>A resource adapter archive is a structured Java Archive (JAR) file, which 
        bundles all Java classes in JAR files, and optionally contains metadata, resources and native
        libraries.</para>

      <para>A resource adapter archive name ends in the <code>.rar</code> extension.</para>

      <para>An example of a resource adapter archive could look like</para>

      <programlisting>
<![CDATA[
[jpederse@localhost]$ jar tf ra.rar
META-INF/ra.xml
readme.html
ra.jar
images/icon.jpg
win.dll
linux.so
 ]]>
      </programlisting>

      <para>See the Java EE Connector Architecture 1.7 specification chapter 20 for further
        requirements.</para>

   </section>

   <section id="deployingrar">
      <title>Deploying resource adapters</title>

      <para>Resource adapters (.rar) are deployed by copying the resource adapter into the 
        <code>deploy/</code> directory</para>

     <programlisting>
cp example.rar ironjacamar-1.2.0.Final/deploy
     </programlisting>

     <para>on a Un*x based system or</para>

     <programlisting>
copy example.rar ironjacamar-1.2.0.Final\deploy
     </programlisting>

     <para>on Windows.</para>

     <para>The resource adapter can be configured and activated through a <code>META-INF/ironjacamar.xml</code>
       file in the archive. The format of the XML document is defined by the <code>ironjacamar_1_0.xsd</code>,
       <code>ironjacamar_1_1.xsd</code> or <code>ironjacamar_1_2.xsd</code> schemas.</para>

     <para>A resource adapter can also be configured and activated through deployment of a <code>-ra.xml</code>
       file in the <code>deploy/</code> directory - f.ex. <code>deploy/example-ra.xml</code>. The format of the XML 
       document is defined by the <code>resource-adapters_1_0.xsd</code>, <code>resource-adapters_1_1.xsd</code> or
       <code>resource-adapters_1_2.xsd</code> schemas - f.ex</para>

     <programlisting language="xml">
<![CDATA[
<resource-adapters>
  <resource-adapter>
    <archive>example.rar</archive>
    <connection-definitions>
      <connection-definition jndi-name="java:/eis/example" class-name="com.example.ra.MCF"/>
    </connection-definitions>
  </resource-adapter>
</resource-adapters>
]]>
     </programlisting>

     <para>to bind the connection factory from <code>com.example.ra.MCF</code> under <code>java:/eis/example</code>.</para>

     <para>See the schema appendix for additional details about the format.</para>

     <para>Alternative the resource adapter deployments will be picked up by the <code>RAActivator</code>
       bean which bind a single connection factory under</para>

     <programlisting>
java:/eis/&lt;deploymentName&gt;
     </programlisting>

     <para>- f.ex. <code>java:/eis/example</code> and a single admin object under</para>

     <programlisting>
java:/eis/ao/&lt;deploymentName&gt;
     </programlisting>

     <para>- f.ex. <code>java:/eis/ao/example</code>.</para>

     <section id="deployingra_descriptor">
       <title>Resource adapter descriptor</title>

       <para>A resource adapter can be configured using two different ways

       <itemizedlist spacing="compact">
         <listitem><code>META-INF/ironjacamar.xml</code> for internal configuration</listitem>
         <listitem><code>-ra.xml</code> for external configuration</listitem>
       </itemizedlist>

       to the resource adapter archive. Both formats share the same layout to ease 
       configuration - only the top-level elements differ.</para>

       <table frame="all">
         <title>Main elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>bean-validation-groups</code></entry>
               <entry>
                 Specifies bean validation group that should be used
               </entry>
             </row>
             <row>
               <entry><code>bootstrap-context</code></entry>
               <entry>
                 Specifies the unique name of the bootstrap context that should be used
               </entry>
             </row>
             <row>
               <entry><code>config-property</code></entry>
               <entry>
                 The config-property specifies resource adapter configuration properties.
               </entry>
             </row>
             <row>
               <entry><code>transaction-support</code></entry>
               <entry>
                 Define the type of transaction supported by this resource adapter.
                 Valid values are: NoTransaction, LocalTransaction, XATransaction
               </entry>
             </row>
             <row>
               <entry><code>connection-definitions</code></entry>
               <entry>
                 Specifies the connection definitions
               </entry>
             </row>
             <row>
               <entry><code>admin-objects</code></entry>
               <entry>
                 Specifies the administration objects
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Bean validation groups elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>bean-validation-group</code></entry>
               <entry>
                 Specifies the fully qualified class name for a bean validation group that
                 should be used for validation
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Connection definition / admin object attributes</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Attribute</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>class-name</code></entry>
               <entry>
                 Specifies the the fully qualified class name of a managed connection factory
                 or admin object
               </entry>
             </row>
             <row>
               <entry><code>jndi-name</code></entry>
               <entry>
                 Specifies the JNDI name
               </entry>
             </row>
             <row>
               <entry><code>enabled</code></entry>
               <entry>
                 Should the object in question be activated
               </entry>
             </row>
             <row>
               <entry><code>use-java-context</code></entry>
               <entry>
                 Specifies if a java:/ JNDI context should be used 
               </entry>
             </row>
             <row>
               <entry><code>pool-name</code></entry>
               <entry>
                 Specifies the pool name for the object
               </entry>
             </row>
             <row>
               <entry><code>use-ccm</code></entry>
               <entry>
                 Enable the cache connection manager
               </entry>
             </row>
             <row>
               <entry><code>sharable</code></entry>
               <entry>
                 Defines the connection as sharable (lazy association) (1.1)
               </entry>
             </row>
             <row>
               <entry><code>enlistment</code></entry>
               <entry>
                 Defines if the connection should use lazy enlistment if supported (1.1)
               </entry>
             </row>
             <row>
               <entry><code>connectable</code></entry>
               <entry>
                 Allow components to obtain a connection through the <code>XAResource</code> instance (1.2)
               </entry>
             </row>
             <row>
               <entry><code>tracking</code></entry>
               <entry>
                 Track connection handles across transaction boundaries (1.2)
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Connection definition elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>config-property</code></entry>
               <entry>
                 The config-property specifies managed connection factory configuration properties.
               </entry>
             </row>
             <row>
               <entry><code>pool</code></entry>
               <entry>
                 Specifies pooling settings
               </entry>
             </row>
             <row>
               <entry><code>xa-pool</code></entry>
               <entry>
                 Specifies XA pooling settings
               </entry>
             </row>
             <row>
               <entry><code>security</code></entry>
               <entry>
                 Specifies security settings
               </entry>
             </row>
             <row>
               <entry><code>timeout</code></entry>
               <entry>
                 Specifies time out settings
               </entry>
             </row>
             <row>
               <entry><code>validation</code></entry>
               <entry>
                 Specifies validation settings
               </entry>
             </row>
             <row>
               <entry><code>recovery</code></entry>
               <entry>
                 Specifies the XA recovery settings
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Pool elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>min-pool-size</code></entry>
               <entry>
                 The min-pool-size element indicates the minimum number of connections 
                 a pool should hold. These are not created until a Subject is known from a 
                 request for a connection. This default to 0
               </entry>
             </row>
             <row>
               <entry><code>initial-pool-size</code></entry>
               <entry>
                 The initial-pool-size element indicates the initial number of connections 
                 a pool should hold. These are not created until a Subject is known from a 
                 request for a connection. This default to 0 (1.1)
               </entry>
             </row>
             <row>
               <entry><code>max-pool-size</code></entry>
               <entry>
                 The max-pool-size element indicates the maximum number of connections 
                 for a pool. No more than max-pool-size connections will be created in each sub-pool. 
                 This defaults to 20. 
               </entry>
             </row>
             <row>
               <entry><code>prefill</code></entry>
               <entry>
                 Whether to attempt to prefill the connection pool. 
                 Default is false
               </entry>
             </row>
             <row>
               <entry><code>use-strict-min</code></entry>
               <entry>
                 Specifies if the min-pool-size should be considered strictly.
                 Default false
               </entry>
             </row>
             <row>
               <entry><code>flush-strategy</code></entry>
               <entry>
                 Specifies how the pool should be flush in case of an error.
                 Valid values are: <code>FailingConnectionOnly</code> (default), <code>InvalidIdleConnections</code> (1.1),
                                   <code>IdleConnections</code>, <code>Gracefully</code> (1.1), <code>EntirePool</code>,
                                   <code>AllInvalidIdleConnections</code> (1.1), <code>AllIdleConnections</code> (1.1),
                                   <code>AllGracefully</code> (1.1), <code>AllConnections</code> (1.1)
               </entry>
             </row>
             <row>
               <entry><code>capacity</code></entry>
               <entry>
                 Specifies the capacity policies (1.1)
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>XA pool elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>min-pool-size</code></entry>
               <entry>
                 The min-pool-size element indicates the minimum number of connections 
                 a pool should hold. These are not created until a Subject is known from a 
                 request for a connection. This default to 0
               </entry>
             </row>
             <row>
               <entry><code>initial-pool-size</code></entry>
               <entry>
                 The initial-pool-size element indicates the initial number of connections 
                 a pool should hold. These are not created until a Subject is known from a 
                 request for a connection. This default to 0 (1.1)
               </entry>
             </row>
             <row>
               <entry><code>max-pool-size</code></entry>
               <entry>
                 The max-pool-size element indicates the maximum number of connections 
                 for a pool. No more than max-pool-size connections will be created in each sub-pool. 
                 This defaults to 20. 
               </entry>
             </row>
             <row>
               <entry><code>prefill</code></entry>
               <entry>
                 Whether to attempt to prefill the connection pool. 
                 Default is false
               </entry>
             </row>
             <row>
               <entry><code>use-strict-min</code></entry>
               <entry>
                 Specifies if the min-pool-size should be considered strictly.
                 Default false
               </entry>
             </row>
             <row>
               <entry><code>flush-strategy</code></entry>
               <entry>
                 Specifies how the pool should be flush in case of an error.
                 Valid values are: <code>FailingConnectionOnly</code> (default), <code>InvalidIdleConnections</code> (1.1),
                                   <code>IdleConnections</code>, <code>Gracefully</code> (1.1), <code>EntirePool</code>,
                                   <code>AllInvalidIdleConnections</code> (1.1), <code>AllIdleConnections</code> (1.1),
                                   <code>AllGracefully</code> (1.1), <code>AllConnections</code> (1.1)
               </entry>
             </row>
             <row>
               <entry><code>capacity</code></entry>
               <entry>
                 Specifies the capacity policies (1.1)
               </entry>
             </row>
             <row>
               <entry><code>is-same-rm-override</code></entry>
               <entry>
                 The is-same-rm-override element allows one to unconditionally 
                 set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns 
                 true or false
               </entry>
             </row>
             <row>
               <entry><code>interleaving</code></entry>
               <entry>
                 An element to enable interleaving for XA connection factories 
               </entry>
             </row>
             <row>
               <entry><code>no-tx-separate-pools</code></entry>
               <entry>
                 Oracle does not like XA connections getting used both inside and outside a JTA transaction. 
                 To workaround the problem you can create separate sub-pools for the different contexts
               </entry>
             </row>
             <row>
               <entry><code>pad-xid</code></entry>
               <entry>
                 Should the Xid be padded
               </entry>
             </row>
             <row>
               <entry><code>wrap-xa-resource</code></entry>
               <entry>
                 Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper
                 instance
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Security elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>application</code></entry>
               <entry>
                 Indicates that application supplied parameters (such as from getConnection(user, pw))
                 are used to distinguish connections in the pool.
               </entry>
             </row>
             <row>
               <entry><code>security-domain</code></entry>
               <entry>
                 Indicates Subject (from security domain) are used to distinguish connections in the pool. 
                 The content of the security-domain is the name of the JAAS security manager that will handle
                 authentication. This name correlates to the JAAS login-config.xml descriptor
                 application-policy/name attribute.
               </entry>
             </row>
             <row>
               <entry><code>security-domain-and-application</code></entry>
               <entry>
                 Indicates that either application supplied parameters (such as from
                 getConnection(user, pw)) or Subject (from security domain) are used to
                 distinguish connections in the pool. The content of the
                 security-domain is the name of the JAAS security manager that will handle
                 authentication. This name correlates to the JAAS login-config.xml descriptor
                 application-policy/name attribute.
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Time out elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>blocking-timeout-millis</code></entry>
               <entry>
                 The blocking-timeout-millis element indicates the maximum time in 
                 milliseconds to block while waiting for a connection before throwing an exception. 
                 Note that this blocks only while waiting for a permit for a connection, and 
                 will never throw an exception if creating a new connection takes an inordinately 
                 long time. The default is 30000 (30 seconds).  
               </entry>
             </row>
             <row>
               <entry><code>idle-timeout-minutes</code></entry>
               <entry>
                 The idle-timeout-minutes elements indicates the maximum time in minutes 
                 a connection may be idle before being closed. The actual maximum time depends 
                 also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes 
                 of any pool. 
               </entry>
             </row>
             <row>
               <entry><code>allocation-retry</code></entry>
               <entry>
                 The allocation retry element indicates the number of times that allocating 
                 a connection should be tried before throwing an exception. The default is 
                 0.  
               </entry>
             </row>
             <row>
               <entry><code>allocation-retry-wait-millis</code></entry>
               <entry>
                 The allocation retry wait millis element indicates the time in milliseconds 
                 to wait between retrying to allocate a connection. The default is 5000 (5 seconds). 
               </entry>
             </row>
             <row>
               <entry><code>xa-resource-timeout</code></entry>
               <entry>
                 Passed to XAResource.setTransactionTimeout(). Default is zero which does not invoke the setter.              
                 Specified in seconds
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Validation elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
              <row>
                <entry><code>validate-on-match</code></entry>
                <entry>
                  The validate-on-match element indicates whether or not connection 
                  level validation should be done when a connection factory attempts to match 
                  a managed connection for a given set. This is typically exclusive to the 
                  use of background validation (1.2)
                </entry>
              </row>
             <row>
               <entry><code>background-validation</code></entry>
               <entry>
                 An element to specify that connections should be validated on a background 
                 thread versus being validated prior to use 
               </entry>
             </row>
             <row>
               <entry><code>background-validation-millis</code></entry>
               <entry>
                 The background-validation-millis element specifies the amount of 
                 time, in milliseconds, that background validation will run. 
               </entry>
             </row>
             <row>
               <entry><code>use-fast-fail</code></entry>
               <entry>
                 Whether fail a connection allocation on the first connection if it 
                 is invalid (true) or keep trying until the pool is exhausted of all potential 
                 connections (false). Default is false
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Admin object elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>config-property</code></entry>
               <entry>
                 Specifies an administration object configuration property.
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <table frame="all">
         <title>Recovery elements</title>
         <tgroup cols="2" align="left" colsep="1" rowsep="1">
           <colspec colname="c1" colwidth="2*"/>
           <colspec colname="c2" colwidth="3*"/>
           <thead>
             <row>
               <entry align="left">Element</entry>
               <entry align="left">Desciption</entry>
             </row>
           </thead>
           <tbody>
             <row>
               <entry><code>recover-credential</code></entry>
               <entry>
                 Specifies the user name / password pair or security domain that
                 should be used for recovery.
               </entry>
             </row>
             <row>
               <entry><code>recover-plugin</code></entry>
               <entry>
                 Specifies an implementation of the org.jboss.jca.core.spi.recovery.RecoveryPlugin
                 class.
               </entry>
             </row>
           </tbody>
         </tgroup>
       </table>

       <para>The deployment schemas are defined in <code>doc/ironjacamar_1_0.xsd</code>, <code>doc/ironjacamar_1_1.xsd</code>,
          <code>doc/resource-adapters_1_0.xsd</code> and <code>doc/resource-adapters_1_1.xsd</code>.</para>
        
     </section>

      <section id="deployingra_extensions">
        <title>Resource adapter extensions</title>

        <para>
          A resource adapter can make use of a couple of Java EE Connector Architecture extensions in 
          the IronJacamar container in order to improve the integration.
        </para>

        <para>
          The extensions include

          <itemizedlist>
            <listitem>
              <code>org.jboss.jca.core.spi.recovery.RecoveryPlugin</code>: Plugin to provide feedback
              to the recovery module inside IronJacamar.
            </listitem>
            <listitem>
              <code>org.jboss.jca.core.spi.statistics.Statistics</code>: Plugin to identify a resource
              adapter component (<code>ResourceAdapter</code>, <code>ManagedConnectionFactory</code> and
              admin object) that provides statistics.
            </listitem>
          </itemizedlist>

        </para>

        <para>
          The following sections will describe these extensions points.
        </para>

        <section id="deployingra_extensions_recovery">
          <title>Recovery extension</title>
          
          <para>
            The IronJacamar recovery extension allows the resource adapter deployment to give feedback
            to the container if a <code>ManagedConnection</code> can be used for recovery. This extension
            is used as part of XA recovery in the environment, and should therefore be implemented by all
            resource adapters capable of working in an <code>XATransaction</code> semantics.
          </para>

          <para>
            The interface <code>org.jboss.core.spi.recovery.RecoveryPlugin</code> located in the 
            <code>ironjacamar-core-api</code> artifact makes up the SPI for the extension.
          </para>

          <para>
            The interface contains two methods that should be implemented in a resource adapter specific
            manner.
          </para>

          <para>
            The method

            <programlisting>
public boolean isValid(Object c) throws ResourceException;
            </programlisting>

            will return <code>true</code> if the connection can be used for recovery.
          </para>

          <para>
            The method

            <programlisting>
public void close(Object c) throws ResourceException;
            </programlisting>

            will close a connection that was used for recovery.
          </para>

          <para>
            The recovery extension is activated by adding a recovery element to the deployment

            <programlisting>
&lt;recovery&gt;
   &lt;recovery-plugin&gt;com.mycompany.myproject.RecoveryPluginImpl&lt;/recovery-plugin&gt;
&lt;/recovery&gt;
            </programlisting>

          </para>

          <para>
            The following recovery plugins are provided by IronJacamar
          </para>

          <itemizedlist>
            <listitem>
              <code>org.jboss.jca.core.recovery.DefaultRecoveryPlugin</code>: Default recovery plugin
              that tries to call a <code>close()</code> method on the underlying object
            </listitem>
            <listitem>
              <code>org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin</code>: A recovery plugin
              where the results of the <code>isValid</code> and <code>close</code> can be specified
            </listitem>
            <listitem>
              <code>org.jboss.jca.core.recovery.ValidatingManagedConnectionFactoryRecoveryPlugin</code>:
              A recovery plugin that uses the <code>javax.resource.spi.ValidatingManagedConnectionFactory</code>
              interface to verify the connection
            </listitem>
          </itemizedlist>

          <note>
            The IronJacamar container will use a default implementation of the recovery SPI if an
            implementation isn't specified by the deployment.
          </note>
          
        </section>

        <section id="deployingra_extensions_statistics">
          <title>Statistics extension</title>
          
          <para>
            The IronJacamar statistics extension allows a resource adapter to expose statistics to
            the container and hence to the environment where IronJacamar is running. Statistics can
            be enabled for <code>ResourceAdapter</code>, <code>ManagedConnectionFactory</code> and
            admin object instances.
          </para>

          <para>
            The extension include two interfaces <code>org.jboss.core.spi.statistics.Statistics</code>
            and <code>org.jboss.core.spi.statistics.StatisticsPlugin</code>. Both these interfaces are
            located in the <code>ironjacamar-core-api</code> artifact.
          </para>

          <para>
            The <code>Statistics</code> interface will mark a resource adapter component as statistics capable
            and return the statistics plugin implementation instance.
          </para>

          <para>
            The <code>StatisticsPlugin</code> interface contains methods to expose and describe each statistic
            that the plugin makes available. This information will then be made available to the environment
            where the IronJacamar container is running using the environment's prefered mechanism.
          </para>

          <note>
            The IronJacamar container will only expose core statistics for a deployment if no implementation
            of this extension is available.
          </note>

        </section>

      </section>

      <section id="deployingra_statistics">
        <title>Resource adapter statistics</title>
        
        <para>
          Resource adapter deployments has the following core statistics values
          
          <table frame="all">
            <title>Core statistics</title>
            <tgroup cols="2" align="left" colsep="1" rowsep="1">
              <colspec colname="c1" colwidth="2*"/>
              <colspec colname="c2" colwidth="3*"/>
              <thead>
                <row>
                  <entry align="left">Name</entry>
                  <entry align="left">Desciption</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><code>ActiveCount</code></entry>
                  <entry>
                    The number of active connections. Each of the connections
                    is either in use by an application or available in the pool
                  </entry>
                </row>
                <row>
                  <entry><code>AvailableCount</code></entry>
                  <entry>
                    The number of available connections in the pool
                  </entry>
                </row>
                <row>
                  <entry><code>AverageBlockingTime</code></entry>
                  <entry>
                    The average time spent blocking on obtaining an exclusive lock
                    on the pool. The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>AverageCreationTime</code></entry>
                  <entry>
                    The average time spent creating a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>AverageGetTime</code></entry>
                  <entry>
                    The average time spent obtaining a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>BlockingFailureCount</code></entry>
                  <entry>
                    The number of times where there was a time out getting
                    an exclusive lock on the pool
                  </entry>
                </row>
                <row>
                  <entry><code>CreatedCount</code></entry>
                  <entry>
                    The number of connections created
                  </entry>
                </row>
                <row>
                  <entry><code>DestroyedCount</code></entry>
                  <entry>
                    The number of connections destroyed
                  </entry>
                </row>
                <row>
                  <entry><code>IdleCount</code></entry>
                  <entry>
                    The number of connections currently idle
                  </entry>
                </row>
                <row>
                  <entry><code>InUseCount</code></entry>
                  <entry>
                    The number of connections currently in use
                  </entry>
                </row>
                <row>
                  <entry><code>MaxCreationTime</code></entry>
                  <entry>
                    The maximum time it took to create a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>MaxGetTime</code></entry>
                  <entry>
                    The maximum time it took to obtain a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>MaxUsedCount</code></entry>
                  <entry>
                    The maximum number of connections used
                  </entry>
                </row>
                <row>
                  <entry><code>MaxWaitCount</code></entry>
                  <entry>
                    The maximum number of requests waiting for a connection
                    at the same time
                  </entry>
                </row>
                <row>
                  <entry><code>MaxWaitTime</code></entry>
                  <entry>
                    The maximum time spent waiting for an exclusive lock
                    on the pool
                  </entry>
                </row>
                <row>
                  <entry><code>TimedOut</code></entry>
                  <entry>
                    The number of timed out connections
                  </entry>
                </row>
                <row>
                  <entry><code>TotalBlockingTime</code></entry>
                  <entry>
                    The total time spent waiting for an exclusive lock
                    on the pool. The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>TotalCreationTime</code></entry>
                  <entry>
                    The total time spent creating connections.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>TotalGetTime</code></entry>
                  <entry>
                    The total time spent obtaining connections.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>WaitCount</code></entry>
                  <entry>
                    The number of requests that had to wait for a connection
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </para>
        
      </section>

   </section>

   <!-- Datasources -->
   <section id="deployingds">
      <title>Deploying datasources</title>

      <para>Datasources (-ds.xml) are deployed by copying the definition into the 
        <code>deploy/</code> directory</para>
        
      <programlisting>
cp postgres-xa-ds.xml ironjacamar-1.2.0.Final/deploy
      </programlisting>

      <para>on a Un*x based system or</para>

      <programlisting>
copy postgres-xa-ds.xml ironjacamar-1.2.0.Final\deploy
      </programlisting>

      <para>on Windows.</para>

      <para>You will need to install the database JDBC driver into the <code>lib/</code> directory.</para>
      
      <para>You can find examples of datasource definitions in the <code>doc/datasources</code> directory
      and the schemas: <code>doc/datasources_1_0.xsd</code>, <code>doc/datasources_1_1.xsd</code>,
      <code>doc/datasources_1_2.xsd</code> and <code>doc/datasources_1_3.xsd</code>.</para>

      <section id="deployingds_descriptor">
        <title>Datasource descriptor</title>

        <para>Datasource descriptors are divided into

        <itemizedlist spacing="compact">
          <listitem><code>&lt;datasource&gt;</code> for a standard datasource</listitem>
          <listitem><code>&lt;xa-datasource&gt;</code> for an XA capable datasource</listitem>
        </itemizedlist>

        definitions.</para>

        <para>A datasource descriptor supports the following parameters.</para>

        <table frame="all">
          <title>Common datasource attributes</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Attribute</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>jndi-name</code></entry>
                <entry>
                  Specifies the JNDI name for the datasource
                </entry>
              </row>
              <row>
                <entry><code>pool-name</code></entry>
                <entry>
                  Specifies the pool name for the datasource used for management
                </entry>
              </row>
              <row>
                <entry><code>enabled</code></entry>
                <entry>
                  Specifies if the datasource should be enabled
                </entry>
              </row>
              <row>
                <entry><code>use-java-context</code></entry>
                <entry>
                  Setting this to false will bind the DataSource into global JNDI
                </entry>
              </row>
              <row>
                <entry><code>spy</code></entry>
                <entry>
                  Enable spy functionality on the JDBC layer - e.g. log all JDBC traffic to the datasource.
                  The logging category <code>jboss.jdbc.spy</code> must be enabled too.
                </entry>
              </row>
              <row>
                <entry><code>use-ccm</code></entry>
                <entry>
                  Enable the cached connection manager
                </entry>
              </row>
              <row>
                <entry><code>jta</code></entry>
                <entry>
                  Enable JTA integration (only <code>&lt;datasource&gt;</code>)
                </entry>
              </row>
             <row>
               <entry><code>connectable</code></entry>
               <entry>
                 Allow components to obtain a connection through the <code>XAResource</code> instance (1.3)
               </entry>
             </row>
             <row>
               <entry><code>tracking</code></entry>
               <entry>
                 Track connection handles across transaction boundaries (1.3)
               </entry>
             </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title><code>datasource</code> elements</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>connection-url</code></entry>
                <entry>
                  The JDBC driver connection URL
                </entry>
              </row>
              <row>
                <entry><code>driver-class</code></entry>
                <entry>
                  The fully qualifed name of the JDBC driver class
                </entry>
              </row>
              <row>
                <entry><code>datasource-class</code></entry>
                <entry>
                  The fully qualifed name of the JDBC datasource class
                </entry>
              </row>
              <row>
                <entry><code>driver</code></entry>
                <entry>
                  <para>An unique name for the JDBC driver specified in the drivers section.
                  Or the name of the .jar file if deployed as standalone deployment</para>
                  <para>This element is mandatory when deploying in WildFly</para>
                </entry>
              </row>
              <row>
                <entry><code>connection-property</code></entry>
                <entry>
                  The connection-property element allows you to pass in arbitrary connection 
                  properties to the Driver.connect(url, props) method. Each connection-property 
                  specifies a string name/value pair with the property name coming from the 
                  name attribute and the value coming from the element content
                </entry>
              </row>
              <row>
                <entry><code>new-connection-sql</code></entry>
                <entry>
                  Specify an SQL statement to execute whenever a connection is added 
                  to the connection pool
                </entry>
              </row>
              <row>
                <entry><code>transaction-isolation</code></entry>
                <entry>
                  Set java.sql.Connection transaction isolation level to use. The constants 
                  defined by transaction-isolation-values are the possible transaction isolation 
                  levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED 
                  TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
                </entry>
              </row>
              <row>
                <entry><code>url-delimiter</code></entry>
                <entry>
                  Specifies the delimeter for URLs in connection-url for HA datasources
                </entry>
              </row>
              <row>
                <entry><code>url-selector-strategy-class-name</code></entry>
                <entry>
                  A class that implements org.jboss.jca.adapters.jdbc.spi.URLSelectorStrategy
                </entry>
              </row>
              <row>
                <entry><code>pool</code></entry>
                <entry>
                  Specifies the pooling settings
                </entry>
              </row>
              <row>
                <entry><code>security</code></entry>
                <entry>
                  Specifies the security settings
                </entry>
              </row>
              <row>
                <entry><code>validation</code></entry>
                <entry>
                  Specifies the validation settings
                </entry>
              </row>
              <row>
                <entry><code>timeout</code></entry>
                <entry>
                  Specifies the time out settings
                </entry>
              </row>
              <row>
                <entry><code>statement</code></entry>
                <entry>
                  Specifies the statement settings
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title><code>xa-datasource</code> elements</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>xa-datasource-property</code></entry>
                <entry>
                  Specifies a property to assign to the XADataSource implementation class. 
                  Each property is identified by the name attribute and the property value 
                  is given by the xa-datasource-property element content. The property is mapped 
                  onto the XADataSource implementation by looking for a JavaBeans style getter 
                  method for the property name. If found, the value of the property is set 
                  using the JavaBeans setter with the element text translated to the true property 
                  type using the java.beans.PropertyEditor for the type
                </entry>
              </row>
              <row>
                <entry><code>xa-datasource-class</code></entry>
                <entry>
                  The fully qualifed name of the javax.sql.XADataSource implementation 
                  class
                </entry>
              </row>
              <row>
                <entry><code>driver</code></entry>
                <entry>
                  <para>An unique name for the JDBC driver specified in the drivers section.
                  Or the name of the .jar file if deployed as standalone deployment.</para>
                  <para>This element is mandatory when deploying in WildFly</para>
                </entry>
              </row>
              <row>
                <entry><code>url-delimiter</code></entry>
                <entry>
                  Specifies the delimeter for URLs in the connection url for HA datasources
                </entry>
              </row>
              <row>
                <entry><code>url-property</code></entry>
                <entry>
                  Specifies the property for the URL property in the xa-datasource-property values (1.2)
                </entry>
              </row>
              <row>
                <entry><code>url-selector-strategy-class-name</code></entry>
                <entry>
                  A class that implements org.jboss.jca.adapters.jdbc.spi.URLXASelectorStrategy
                </entry>
              </row>
              <row>
                <entry><code>new-connection-sql</code></entry>
                <entry>
                  Specifies an SQL statement to execute whenever a connection is added 
                  to the connection pool
                </entry>
              </row>
              <row>
                <entry><code>transaction-isolation</code></entry>
                <entry>
                  Set java.sql.Connection transaction isolation level to use. The constants 
                  defined by transaction-isolation-values are the possible transaction isolation 
                  levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED 
                  TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
                </entry>
              </row>
              <row>
                <entry><code>xa-pool</code></entry>
                <entry>
                  Specifies the pooling settings
                </entry>
              </row>
              <row>
                <entry><code>security</code></entry>
                <entry>
                  Specifies the security settings
                </entry>
              </row>
              <row>
                <entry><code>validation</code></entry>
                <entry>
                  Specifies the validation settings
                </entry>
              </row>
              <row>
                <entry><code>timeout</code></entry>
                <entry>
                  Specifies the time out settings
                </entry>
              </row>
              <row>
                <entry><code>statement</code></entry>
                <entry>
                  Specifies the statement settings
                </entry>
              </row>
              <row>
                <entry><code>recovery</code></entry>
                <entry>
                  Specifies the recovery settings
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Pool settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>min-pool-size</code></entry>
                <entry>
                  The min-pool-size element indicates the minimum number of connections 
                  a pool should hold. These are not created until a Subject is known from a 
                  request for a connection. This default to 0
                </entry>
              </row>
              <row>
                <entry><code>initial-pool-size</code></entry>
                <entry>
                  The initial-pool-size element indicates the initial number of connections 
                  a pool should hold. These are not created until a Subject is known from a 
                  request for a connection. This default to 0 (1.2)
                </entry>
              </row>
              <row>
                <entry><code>max-pool-size</code></entry>
                <entry>
                  The max-pool-size element indicates the maximum number of connections 
                  for a pool. No more connections will be created in each sub-pool. 
                  This defaults to 20
                </entry>
              </row>
              <row>
                <entry><code>prefill</code></entry>
                <entry>
                  Whether to attempt to prefill the connection pool. Empty element denotes 
                  a true value. Default is false
                </entry>
              </row>
              <row>
                <entry><code>use-strict-min</code></entry>
                <entry>
                  Define if the min-pool-size should be considered a strictly.
                  Default false
                </entry>
              </row>
              <row>
                <entry><code>flush-strategy</code></entry>
                <entry>
                  Specifies how the pool should be flush in case of an error.
                  Valid values are: <code>FailingConnectionOnly</code> (default), <code>InvalidIdleConnections</code> (1.2),
                                    <code>IdleConnections</code>, <code>Gracefully</code> (1.2), <code>EntirePool</code>,
                                    <code>AllInvalidIdleConnections</code> (1.2), <code>AllIdleConnections</code> (1.2),
                                    <code>AllGracefully</code> (1.2), <code>AllConnections</code> (1.2)
                </entry>
              </row>
              <row>
                <entry><code>allow-multiple-users</code></entry>
                <entry>
                  Specifies if multiple users will access the datasource through the getConnection(user, password)
                  method and hence if the internal pool type should account for that (1.1)
                </entry>
              </row>
              <row>
                <entry><code>capacity</code></entry>
                <entry>
                  Specifies the capacity policies (1.2)
                </entry>
              </row>
              <row>
                <entry><code>connection-listener</code></entry>
                <entry>
                  An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides 
                  a possible to listen for connection activation and passivation in order to
                  perform actions before the connection is returned to the application or returned
                  to the pool (1.2)
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>XA pool settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>min-pool-size</code></entry>
                <entry>
                  The min-pool-size element indicates the minimum number of connections 
                  a pool should hold. These are not created until a Subject is known from a 
                  request for a connection. This default to 0
                </entry>
              </row>
              <row>
                <entry><code>initial-pool-size</code></entry>
                <entry>
                  The initial-pool-size element indicates the initial number of connections 
                  a pool should hold. These are not created until a Subject is known from a 
                  request for a connection. This default to 0 (1.2)
                </entry>
              </row>
              <row>
                <entry><code>max-pool-size</code></entry>
                <entry>
                  The max-pool-size element indicates the maximum number of connections 
                  for a pool. No more connections will be created in each sub-pool. 
                  This defaults to 20
                </entry>
              </row>
              <row>
                <entry><code>prefill</code></entry>
                <entry>
                  Whether to attempt to prefill the connection pool. Empty element denotes 
                  a true value. Default is false
                </entry>
              </row>
              <row>
                <entry><code>use-strict-min</code></entry>
                <entry>
                  Define if the min-pool-size should be considered a strictly.
                  Default false
                </entry>
              </row>
              <row>
                <entry><code>flush-strategy</code></entry>
                <entry>
                  Specifies how the pool should be flush in case of an error.
                  Valid values are: <code>FailingConnectionOnly</code> (default), <code>InvalidIdleConnections</code> (1.2),
                                    <code>IdleConnections</code>, <code>Gracefully</code> (1.2), <code>EntirePool</code>, 
                                    <code>AllInvalidIdleConnections</code> (1.2), <code>AllIdleConnections</code> (1.2),
                                    <code>AllGracefully</code> (1.2), <code>AllConnections</code> (1.2)
                </entry>
              </row>
              <row>
                <entry><code>allow-multiple-users</code></entry>
                <entry>
                  Specifies if multiple users will access the datasource through the getConnection(user, password)
                  method and hence if the internal pool type should account for that (1.1)
                </entry>
              </row>
              <row>
                <entry><code>capacity</code></entry>
                <entry>
                  Specifies the capacity policies (1.2)
                </entry>
              </row>
              <row>
                <entry><code>connection-listener</code></entry>
                <entry>
                  An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides 
                  a possible to listen for connection activation and passivation in order to
                  perform actions before the connection is returned to the application or returned
                  to the pool (1.2)
                </entry>
              </row>
              <row>
                <entry><code>is-same-rm-override</code></entry>
                <entry>
                  The is-same-rm-override element allows one to unconditionally 
                  set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns 
                  true or false
                </entry>
              </row>
              <row>
                <entry><code>interleaving</code></entry>
                <entry>
                  An element to enable interleaving for XA connection factories 
                </entry>
              </row>
              <row>
                <entry><code>no-tx-separate-pools</code></entry>
                <entry>
                  Oracle does not like XA connections getting used both inside and outside a JTA transaction. 
                  To workaround the problem you can create separate sub-pools for the different contexts
                </entry>
              </row>
              <row>
                <entry><code>pad-xid</code></entry>
                <entry>
                  Should the Xid be padded
                </entry>
              </row>
              <row>
                <entry><code>wrap-xa-resource</code></entry>
                <entry>
                  Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper
                  instance
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Security settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>user-name</code></entry>
                <entry>
                  Specify the username used when creating a new connection. 
                </entry>
              </row>
              <row>
                <entry><code>password</code></entry>
                <entry>
                  Specify the password used when creating a new connection. 
                </entry>
              </row>
              <row>
                <entry><code>security-domain</code></entry>
                <entry>
                  Indicates Subject (from security domain) are used to distinguish connections in the pool. 
                  The content of the security-domain is the name of the JAAS security manager that will handle
                  authentication. This name correlates to the JAAS login-config.xml descriptor
                  application-policy/name attribute.
                </entry>
              </row>
              <row>
                <entry><code>reauth-plugin</code></entry>
                <entry>
                  Defines a reauthentication plugin that can be used for reauthentication of physical connections.
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Validation settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>valid-connection-checker</code></entry>
                <entry>
                  An org.jboss.jca.adapters.jdbc.spi.ValidConnectionChecker that provides 
                  a SQLException isValidConnection(Connection e) method to validate is a connection 
                  is valid. An exception means the connection is destroyed. This overrides 
                  the check-valid-connection-sql when present
                </entry>
              </row>
              <row>
                <entry><code>check-valid-connection-sql</code></entry>
                <entry>
                  Specify an SQL statement to check validity of a pool connection. This 
                  may be called when managed connection is taken from pool for use. 
                </entry>
              </row>
              <row>
                <entry><code>validate-on-match</code></entry>
                <entry>
                  The validate-on-match element indicates whether or not connection 
                  level validation should be done when a connection factory attempts to match 
                  a managed connection for a given set. This is typically exclusive to the 
                  use of background validation 
                </entry>
              </row>
              <row>
                <entry><code>background-validation</code></entry>
                <entry>
                  An element to specify that connections should be validated on a background 
                  thread versus being validated prior to use 
                </entry>
              </row>
              <row>
                <entry><code>background-validation-millis</code></entry>
                <entry>
                  The background-validation-millis element specifies the amount of 
                  time, in milliseconds, that background validation will run
                </entry>
              </row>
              <row>
                <entry><code>use-fast-fail</code></entry>
                <entry>
                  Whether fail a connection allocation on the first connection if it 
                  is invalid (true) or keep trying until the pool is exhausted of all potential 
                  connections (false) default false
                </entry>
              </row>
              <row>
                <entry><code>stale-connection-checker</code></entry>
                <entry>
                  An org.jboss.jca.adapters.jdbc.spi.StaleConnectionChecker that provides 
                  a boolean isStaleConnection(SQLException e) method which if it it returns 
                  true will wrap the exception in an org.jboss.jca.adapters.jdbc.StaleConnectionException 
                  which is a subclass of SQLException
                </entry>
              </row>
              <row>
                <entry><code>exception-sorter</code></entry>
                <entry>
                  An org.jboss.jca.adapters.jdbc.spi.ExceptionSorter that provides a 
                  boolean isExceptionFatal(SQLException e) method to validate is an exception 
                  should be broadcast to all javax.resource.spi.ConnectionEventListener as 
                  a connectionErrorOccurred message
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Time out settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>blocking-timeout-millis</code></entry>
                <entry>
                  The blocking-timeout-millis element indicates the maximum time in 
                  milliseconds to block while waiting for a connection before throwing an exception. 
                  Note that this blocks only while waiting for a permit for a connection, and 
                  will never throw an exception if creating a new connection takes an inordinately 
                  long time. The default is 30000 (30 seconds).  
                </entry>
              </row>
              <row>
                <entry><code>idle-timeout-minutes</code></entry>
                <entry>
                  The idle-timeout-minutes elements indicates the maximum time in minutes 
                  a connection may be idle before being closed. The actual maximum time depends 
                  also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes 
                  of any pool. 
                </entry>
              </row>
              <row>
                <entry><code>set-tx-query-timeout</code></entry>
                <entry>
                  Whether to set the query timeout based on the time remaining until 
                  transaction timeout, any configured query timeout will be used if there is 
                  no transaction. The default is false
                </entry>
              </row>
              <row>
                <entry><code>query-timeout</code></entry>
                <entry>
                  Any configured query timeout in seconds The default is no timeout 
                </entry>
              </row>
              <row>
                <entry><code>use-try-lock</code></entry>
                <entry>
                  Any configured timeout for internal locks on the resource adapter 
                  objects in seconds The default is a 60 second timeout
                </entry>
              </row>
              <row>
                <entry><code>allocation-retry</code></entry>
                <entry>
                  The allocation retry element indicates the number of times that allocating 
                  a connection should be tried before throwing an exception. The default is 0.  
                </entry>
              </row>
              <row>
                <entry><code>allocation-retry-wait-millis</code></entry>
                <entry>
                  The allocation retry wait millis element indicates the time in milliseconds 
                  to wait between retrying to allocate a connection. The default is 5000 (5 seconds). 
                </entry>
              </row>
              <row>
                <entry><code>xa-resource-timeout</code></entry>
                <entry>
                  Passed to XAResource.setTransactionTimeout() Default is zero which 
                  does not invoke the setter. In seconds
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Statement settings</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>track-statements</code></entry>
                <entry>
                  Whether to check for unclosed statements when a connection is returned 
                  to the pool and result sets are closed when a statement is closed/return 
                  to the prepared statement cache. valid values are: <code>false</code> - do not track statements 
                  and results; <code>true</code> - track statements and result sets and warn when they are 
                  not closed; <code>nowarn</code> - track statements but do no warn about them being unclosed 
                  (the default)
                </entry>
              </row>
              <row>
                <entry><code>prepared-statement-cache-size</code></entry>
                <entry>
                  The number of prepared statements per connection in an LRU cache
                </entry>
              </row>
              <row>
                <entry><code>share-prepared-statements</code></entry>
                <entry>
                  Whether to share prepare statements, i.e. whether asking for same 
                  statement twice without closing uses the same underlying prepared statement. 
                  The default is false
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
        <table frame="all">
          <title>Recovery elements</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>recover-credential</code></entry>
                <entry>
                  Specifies the user name / password pair or security domain that
                  should be used for recovery.
                </entry>
              </row>
              <row>
                <entry><code>recover-plugin</code></entry>
                <entry>
                  Specifies an implementation of the org.jboss.jca.core.spi.recovery.RecoveryPlugin
                  class.
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Driver attributes</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Attribute</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>name</code></entry>
                <entry>
                  An unique name for the JDBC driver
                </entry>
              </row>
              <row>
                <entry><code>module</code></entry>
                <entry>
                  <para>The module definition for the JDBC driver. The format of a module inside
                  WildFly 8+ is <code>com.h2database.h2</code> which will
                  map to the H2 installation under <code>modules/com/h2database/h2/main</code>. A ':'
                  can be used to identify the slot - f.ex <code>com.h2database.h2:1.3.159</code>.</para>

                  <para>The format for IronJacamar Standalone/Embedded is the name of the .jar file</para>
                </entry>
              </row>
              <row>
                <entry><code>major-version</code></entry>
                <entry>
                  The major version of the driver
                </entry>
              </row>
              <row>
                <entry><code>minor-version</code></entry>
                <entry>
                  The minor version of the driver
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all">
          <title>Driver elements</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Element</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>driver-class</code></entry>
                <entry>
                  The fully qualified class name of the driver class
                </entry>
              </row>
              <row>
                <entry><code>datasource-class</code></entry>
                <entry>
                  The fully qualified class name of the datasource class
                </entry>
              </row>
              <row>
                <entry><code>xa-datasource-class</code></entry>
                <entry>
                  The fully qualified class name of the XA datasource class
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </section>

      <section id="deployingds_extensions">
        <title>Datasource extensions</title>

        <para>
          The datasource deployments can make use of a couple of extensions in the JDBC resource adapter
          to improve the connection validation and checking if an exception should reestablish
          the connection in question.
        </para>

        <para>
          The extensions include

          <itemizedlist>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.spi.ExceptionSorter</code>: Plugin to check if a 
              <code>SQLException</code> is fatal for the connection on which it was thrown.
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.spi.StaleConnection</code>: Plugin to wrap stale 
              <code>SQLException</code>'s in a <code>org.jboss.jca.adapters.jdbc.StaleConnectionException</code>.
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.spi.ValidConnection</code>: Plugin to Check if a connection is
              valid for use by the application.
            </listitem>
          </itemizedlist>

        </para>

        <para>
          Configuration of the extensions are done by using

          <itemizedlist>
            <listitem>
              The <code>&lt;exception-sorter&gt;</code> tag for an <code>ExceptionSorter</code>
            </listitem>
            <listitem>
              The <code>&lt;stale-connection-checker&gt;</code> tag for a <code>StaleConnection</code>
            </listitem>
            <listitem>
              The <code>&lt;valid-connection-checker&gt;</code> tag for a <code>ValidConnection</code> 
            </listitem>
          </itemizedlist>

        </para>

        <para>
          IronJacamar features implementations of these extensions for a couple of popular databases.
          Contributions in this area are most welcome either generic solutions or for a specific database.
        </para>

        <para>
          Informix:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          Microsoft SQLServer:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          PostgreSQL:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          MySQL:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          IBM DB2:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          Generic:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.AlwaysExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.AlwaysStaleConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.GoodForSecondsValidConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.ListExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.ListStaleConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.novendor.SQLExceptionValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          Sybase:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

        <para>
          Oracle:

          <itemizedlist spacing="compact">
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker</code>
            </listitem>
            <listitem>
              <code>org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker</code>
            </listitem>
          </itemizedlist>
        </para>

      </section>

      <section id="deployingds_statistics">
        <title>Datasource statistics</title>
        
        <para>
          Datasources has the following core statistics values
        
          <table frame="all">
            <title>Core statistics</title>
            <tgroup cols="2" align="left" colsep="1" rowsep="1">
              <colspec colname="c1" colwidth="2*"/>
              <colspec colname="c2" colwidth="3*"/>
              <thead>
                <row>
                  <entry align="left">Name</entry>
                  <entry align="left">Desciption</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><code>ActiveCount</code></entry>
                  <entry>
                    The number of active connections. Each of the connections
                    is either in use by an application or available in the pool
                  </entry>
                </row>
                <row>
                  <entry><code>AvailableCount</code></entry>
                  <entry>
                    The number of available connections in the pool
                  </entry>
                </row>
                <row>
                  <entry><code>AverageBlockingTime</code></entry>
                  <entry>
                    The average time spent blocking on obtaining an exclusive lock
                    on the pool. The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>AverageCreationTime</code></entry>
                  <entry>
                    The average time spent creating a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>AverageGetTime</code></entry>
                  <entry>
                    The average time spent obtaining a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>BlockingFailureCount</code></entry>
                  <entry>
                    The number of times where there was a time out getting
                    an exclusive lock on the pool
                  </entry>
                </row>
                <row>
                  <entry><code>CreatedCount</code></entry>
                  <entry>
                    The number of connections created
                  </entry>
                </row>
                <row>
                  <entry><code>DestroyedCount</code></entry>
                  <entry>
                    The number of connections destroyed
                  </entry>
                </row>
                <row>
                  <entry><code>IdleCount</code></entry>
                  <entry>
                    The number of connections currently idle
                  </entry>
                </row>
                <row>
                  <entry><code>InUseCount</code></entry>
                  <entry>
                    The number of connections currently in use
                  </entry>
                </row>
                <row>
                  <entry><code>MaxCreationTime</code></entry>
                  <entry>
                    The maximum time it took to create a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>MaxGetTime</code></entry>
                  <entry>
                    The maximum time it took to obtain a connection.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>MaxUsedCount</code></entry>
                  <entry>
                    The maximum number of connections used
                  </entry>
                </row>
                <row>
                  <entry><code>MaxWaitCount</code></entry>
                  <entry>
                    The maximum number of requests waiting for a connection
                    at the same time
                  </entry>
                </row>
                <row>
                  <entry><code>MaxWaitTime</code></entry>
                  <entry>
                    The maximum time spent waiting for an exclusive lock
                    on the pool
                  </entry>
                </row>
                <row>
                  <entry><code>TimedOut</code></entry>
                  <entry>
                    The number of timed out connections
                  </entry>
                </row>
                <row>
                  <entry><code>TotalBlockingTime</code></entry>
                  <entry>
                    The total time spent waiting for an exclusive lock
                    on the pool. The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>TotalCreationTime</code></entry>
                  <entry>
                    The total time spent creating connections.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>TotalGetTime</code></entry>
                  <entry>
                    The total time spent obtaining connections.
                    The value is in milliseconds
                  </entry>
                </row>
                <row>
                  <entry><code>WaitCount</code></entry>
                  <entry>
                    The number of requests that had to wait for a connection
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </para>

        <para>
          Datasources has the following JDBC statistics values
        
          <table frame="all">
            <title>JDBC statistics</title>
            <tgroup cols="2" align="left" colsep="1" rowsep="1">
              <colspec colname="c1" colwidth="2*"/>
              <colspec colname="c2" colwidth="3*"/>
              <thead>
                <row>
                  <entry align="left">Name</entry>
                  <entry align="left">Desciption</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><code>PreparedStatementCacheAccessCount</code></entry>
                  <entry>
                    The number of times that the statement cache was accessed
                  </entry>
                </row>
                <row>
                  <entry><code>PreparedStatementCacheAddCount</code></entry>
                  <entry>
                    The number of statements added to the statement cache
                  </entry>
                </row>
                <row>
                  <entry><code>PreparedStatementCacheCurrentSize</code></entry>
                  <entry>
                    The number of prepared and callable statements currently cached in the statement cache
                  </entry>
                </row>
                <row>
                  <entry><code>PreparedStatementCacheDeleteCount</code></entry>
                  <entry>
                    The number of statements discarded from the cache
                  </entry>
                </row>
                <row>
                  <entry><code>PreparedStatementCacheHitCount</code></entry>
                  <entry>
                    The number of times that statements from the cache were used
                  </entry>
                </row>
                <row>
                  <entry><code>PreparedStatementCacheMissCount</code></entry>
                  <entry>
                    The number of times that a statement request could not be satisfied with a statement from the cache
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </para>

      </section>

   </section>

   <section id="deploying_general">
      <title>General deployment settings</title>

      <para>
        This section will provide an overview of general deployment settings that are shared between resource adapter
        activations, and datasource deployments.
      </para>

      <section id="deploying_flush_strategies">
        <title>Flush strategies</title>

        <para>
          The flush strategy option for the connection pool defines how the pool should be flushed in case there
          is an error on a connection belonging to the pool.
        </para>

        <para>
          In all cases the connection with the error is destroyed, and the pool is scheduled for prefill if supported.
        </para>

        <table frame="all">
          <title>Flush strategies</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="3*"/>
            <thead>
              <row>
                <entry align="left">Name</entry>
                <entry align="left">Desciption</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>FailingConnectionOnly</code></entry>
                <entry>
                  Only the connection with the error is destroyed. This is the default strategy.
                </entry>
              </row>
              <row>
                <entry><code>InvalidIdleConnections</code></entry>
                <entry>
                  All idle connections are checked if they are invalid, based on the
                  <code>javax.resource.spi.ValidatingManagedConnectionFactory</code>
                  return value.
                </entry>
              </row>
              <row>
                <entry><code>IdleConnections</code></entry>
                <entry>
                  All idle connections are destroyed.
                </entry>
              </row>
              <row>
                <entry><code>Gracefully</code></entry>
                <entry>
                  All idle connections are destroyed, and all active connections
                  will be destroyed upon return to the pool.
                </entry>
              </row>
              <row>
                <entry><code>EntirePool</code></entry>
                <entry>
                  All connections are destroyed, including current active connections.
                </entry>
              </row>
              <row>
                <entry><code>AllInvalidIdleConnections</code></entry>
                <entry>
                  Like <code>InvalidIdleConnections</code>, but across
                  all credentials for the pool if supported.
                </entry>
              </row>
              <row>
                <entry><code>AllIdleConnections</code></entry>
                <entry>
                  Like <code>IdleConnections</code>, but across
                  all credentials for the pool if supported.
                </entry>
              </row>
              <row>
                <entry><code>AllGracefully</code></entry>
                <entry>
                  Like <code>Gracefully</code>, but across
                  all credentials for the pool if supported.
                </entry>
              </row>
              <row>
                <entry><code>AllConnections</code></entry>
                <entry>
                  Like <code>EntirePool</code>, but across
                  all credentials for the pool if supported.
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </section>

      <section id="deploying_capacity_policies">
        <title>Capacity policies</title>

        <para>
          The policy for creating and destroying physical connections for a pool can be controlled by specifying
          which policy that should be used.
        </para>
        
        <para>
          The default policies are only to create one connection per request, and to destroy all connections timed
          out when the idle timeout is scheduled.
        </para>

        <note>
          IronJacamar will by default make use of First In First Out (FIFO) and First In Last Out (FILO) pooling
          policies based on the decrementer policy selected. Note, that not all pool implementations will support
          these pooling policies.
        </note>
        
        <section id="deploying_capacity_increment">
          <title>Increment policies</title>

          <para>
            The following increment policies are supported.
          </para>
          
          <section id="deploying_capacity_increment_maxpool">
            <title>MaxPoolSize policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.MaxPoolSizeIncrementer</code> policy
              will fill the pool to its max size for each request.
            </para>
            
            <para>
              This policy is useful when you want to keep the maximum number of connections available all the time.
            </para>
          </section>

          <section id="deploying_capacity_increment_size">
            <title>Size policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer</code> policy
              will fill the pool by the specified number of connections for each request.
            </para>
            
            <table frame="all">
              <title>Size policy properties</title>
              <tgroup cols="2" align="left" colsep="1" rowsep="1">
                <colspec colname="c1" colwidth="2*"/>
                <colspec colname="c2" colwidth="3*"/>
                <thead>
                  <row>
                    <entry align="left">Name</entry>
                    <entry align="left">Desciption</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry><code>Size</code></entry>
                    <entry>
                      The number of connections that should be created
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <para>
              This policy is useful when you want to increment with an additional number of connections per
              request in anticipation that the next request will also need a connection.
            </para>

            <para>
              This is the default increment policy with a value of 1.
            </para>

          </section>

          <section id="deploying_capacity_increment_watermark">
            <title>Watermark policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer</code> policy
              will fill the pool to the specified number of connections for each request.
            </para>
            
            <table frame="all">
              <title>Watermark policy properties</title>
              <tgroup cols="2" align="left" colsep="1" rowsep="1">
                <colspec colname="c1" colwidth="2*"/>
                <colspec colname="c2" colwidth="3*"/>
                <thead>
                  <row>
                    <entry align="left">Name</entry>
                    <entry align="left">Desciption</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry><code>Watermark</code></entry>
                    <entry>
                      The watermark level for the number of connections
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <para>
              This policy is useful when you want to keep a specified number of connections in the pool
              at all time.
            </para>
          </section>

        </section>

        <!-- Decrement policies -->
        <section id="deploying_capacity_decrement">
          <title>Decrement policies</title>

          <para>
            The following decrement policies are supported.
          </para>
          
          <section id="deploying_capacity_decrement_minpool">
            <title>MinPoolSize policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer</code> policy
              will decrement the pool to its min size for each request.
            </para>
            
            <para>
              This policy is useful when you want to limit the number of connections after each idle timeout request.
            </para>

            <para>
              The pool will operate in a First In First Out (FIFO) manner.
            </para>
          </section>

          <section id="deploying_capacity_decrement_size">
            <title>Size policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer</code> policy
              will decrement the pool by the specified number of connections for each idle timeout request.
            </para>
            
            <table frame="all">
              <title>Size policy properties</title>
              <tgroup cols="2" align="left" colsep="1" rowsep="1">
                <colspec colname="c1" colwidth="2*"/>
                <colspec colname="c2" colwidth="3*"/>
                <thead>
                  <row>
                    <entry align="left">Name</entry>
                    <entry align="left">Desciption</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry><code>Size</code></entry>
                    <entry>
                      The number of connections that should be destroyed
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <para>
              This policy is useful when you want to decrement an additional number of connections per
              idle timeout request in anticipation that the pool usage will lower over time.
            </para>

            <para>
              The pool will operate in a First In First Out (FIFO) manner.
            </para>
          </section>

          <section id="deploying_capacity_decrement_timedout">
            <title>TimedOut policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer</code> policy
              will removed all connections that have timed out from the pool for each idle timeout request.
            </para>

            <para>
              This policy is the default decrement policy.
            </para>

            <para>
              The pool will operate in a First In Last Out (FILO) manner.
            </para>
          </section>

          <section id="deploying_capacity_decrement_timedout_fifo">
            <title>TimedOut/FIFO policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutFIFODecrementer</code> policy
              will removed all connections that have timed out from the pool for each idle timeout request.
            </para>

            <para>
              The pool will operate in a First In First Out (FIFO) manner.
            </para>
          </section>

          <section id="deploying_capacity_decrement_watermark">
            <title>Watermark policy</title>
            
            <para>
              The <code>org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer</code> policy
              will decrement the pool to the specified number of connections for each idle timeout request.
            </para>
            
            <table frame="all">
              <title>Watermark policy properties</title>
              <tgroup cols="2" align="left" colsep="1" rowsep="1">
                <colspec colname="c1" colwidth="2*"/>
                <colspec colname="c2" colwidth="3*"/>
                <thead>
                  <row>
                    <entry align="left">Name</entry>
                    <entry align="left">Desciption</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry><code>Watermark</code></entry>
                    <entry>
                      The watermark level for the number of connections
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <para>
              This policy is useful when you want to keep a specified number of connections in the pool
              at all time.
            </para>

            <para>
              The pool will operate in a First In First Out (FIFO) manner.
            </para>
          </section>

        </section>

      </section>

   </section>


</chapter>
