src/site/xdoc/configuration.xml - commons-dbcp - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1"?>
  <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
   -->
 <document>

  <properties>
   <title>BasicDataSource Configuration</title>
   <author email="dev@commons.apache.org">Commons Documentation Team</author>
  </properties>

  <body>

 <!--
 <section name="Introduction">
 <p>TODO: add section about tomcat configuration and avoiding the resource leak when reloading tomcat webapps.</p>
 </section>
 -->

 <!--
 <section name="Dynamic Properties">
 maxTotal
 maxIdle
 minIdle
 maxWaitMillis
 testOnBorrow
 testOnReturn
 timeBetweenEvictionRunsMillis
 numTestsPerEvictionRun
 minEvictableIdleTimeMillis
 testWhileIdle

 </section>
 -->

 <section name="BasicDataSource Configuration Parameters">

 <table>
 <hr><th>Parameter</th><th>Description</th></hr>
 <tr>
    <td>username</td>
    <td>The connection user name to be passed to our JDBC driver to establish a connection.</td>
 </tr>
 <tr>
    <td>password</td>
    <td>The connection password to be passed to our JDBC driver to establish a connection.</td>
 </tr>
 <tr>
    <td>url</td>
    <td>The connection URL to be passed to our JDBC driver to establish a connection.</td>
 </tr>
 <tr>
    <td>driverClassName</td>
    <td>The fully qualified Java class name of the JDBC driver to be used.</td>
 </tr>
 <tr>
    <td>connectionProperties</td>
    <td>The connection properties that will be sent to our JDBC driver when establishing new connections.
        <br/>Format of the string must be [propertyName=property;]*
        <br/><strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly,
        so they do not need to be included here.
    </td>
 </tr>
 </table>


 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
 <tr>
    <td>defaultAutoCommit</td>
    <td>driver default</td>
    <td>The default auto-commit state of connections created by this pool.
        If not set then the setAutoCommit method will not be called.
    </td>
 </tr>
 <tr>
    <td>defaultReadOnly</td>
    <td>driver default</td>
    <td>The default read-only state of connections created by this pool.
        If not set then the setReadOnly method will not be called.
        (Some drivers don't support read only mode, ex: Informix)
    </td>
 </tr>
 <tr>
    <td>defaultTransactionIsolation</td>
    <td>driver default</td>
    <td>The default TransactionIsolation state of connections created by this pool.
        One of the following: (see
        <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary">javadoc</a>)
        <ul>
           <li>NONE</li>
           <li>READ_COMMITTED</li>
           <li>READ_UNCOMMITTED</li>
           <li>REPEATABLE_READ</li>
           <li>SERIALIZABLE</li>
        </ul>
    </td>
 </tr>
 <tr>
    <td>defaultCatalog</td>
    <td></td>
    <td>The default catalog of connections created by this pool.</td>
 </tr>
 <tr>
   <td>cacheState</td>
   <td>true</td>
   <td>If true, the pooled connection will cache the current readOnly and
       autoCommit settings when first read or written and on all subsequent
       writes. This removes the need for additional database queries for any
       further calls to the getter. If the underlying connection is accessed
       directly and the readOnly and/or autoCommit settings changed the cached
       values will not reflect the current state. In this case, caching should be
       disabled by setting this attribute to false.</td>
 </tr>
 <tr>
   <td>defaultQueryTimeout</td>
   <td>null</td>
   <td>If non-null, the value of this <code>Integer</code> property determines
       the query timeout that will be used for Statements created from
       connections managed by the pool. <code>null</code> means that the driver
       default will be used.</td>
 </tr>
 <tr>
   <td>enableAutoCommitOnReturn</td>
   <td>true</td>
   <td>If true, connections being returned to the pool will be checked and configured with
       <code>Connection.setAutoCommit(true)</code> if the auto commit setting is
       <code>false</code> when the connection is returned.</td>
 </tr>
 <tr>
   <td>rollbackOnReturn</td>
   <td>true</td>
   <td>True means a connection will be rolled back when returned to the pool if
       auto commit is not enabled and the connection is not read-only.</td>
 </tr>
 </table>


 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
 <tr>
    <td>initialSize</td>
    <td>0</td>
    <td>
       The initial number of connections that are created when the pool
       is started.
       <br/>Since: 1.2
    </td>
 </tr>
 <tr>
    <td>maxTotal</td>
    <td>8</td>
    <td>
       The maximum number of active connections that can be allocated from
       this pool at the same time, or negative for no limit.
    </td>
 </tr>
 <tr>
    <td>maxIdle</td>
    <td>8</td>
    <td>
       The maximum number of connections that can remain idle in the
       pool, without extra ones being released, or negative for no limit.
    </td>
 </tr>
 <tr>
    <td>minIdle</td>
    <td>0</td>
    <td>
       The minimum number of connections that can remain idle in the
       pool, without extra ones being created, or zero to create none.
    </td>
 </tr>
 <tr>
    <td>maxWaitMillis</td>
    <td>indefinitely</td>
    <td>
       The maximum number of milliseconds that the pool will wait (when there
       are no available connections) for a connection to be returned before
       throwing an exception, or -1 to wait indefinitely.
    </td>
 </tr>
 </table>
 <p>
 <img src="images/icon_warning_sml.gif"/>
 <strong>NOTE</strong>: If maxIdle is set too low on heavily loaded systems it is
 possible you will see connections being closed and almost immediately new
 connections being opened. This is a result of the active threads momentarily
 closing connections faster than they are opening them, causing the number of
 idle connections to rise above maxIdle. The best value for maxIdle for heavily
 loaded system will vary but the default is a good starting point.
 </p>


 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
 <tr>
    <td>validationQuery</td>
    <td></td>
    <td>
 The SQL query that will be used to validate connections from this pool
 before returning them to the caller.  If specified, this query
 <strong>MUST</strong> be an SQL SELECT statement that returns at least
 one row. If not specified, connections will be validation by calling the
 isValid() method.
    </td>
 </tr>
 <tr>
   <td>validationQueryTimeout</td>
   <td>no timeout</td>
   <td>The timeout in seconds before connection validation queries fail. If set
       to a positive value, this value is passed to the driver via the
       <code>setQueryTimeout</code> method of the <code>Statement</code>
       used to execute the validation query.</td>
 </tr>
 <tr>
    <td>testOnCreate</td>
    <td>false</td>
    <td>
       The indication of whether objects will be validated after creation. If the
       object fails to validate, the borrow attempt that triggered the object
       creation will fail.
    </td>
 </tr>
 <tr>
    <td>testOnBorrow</td>
    <td>true</td>
    <td>
       The indication of whether objects will be validated before being
       borrowed from the pool.  If the object fails to validate, it will be
       dropped from the pool, and we will attempt to borrow another.
    </td>
 </tr>
 <tr>
    <td>testOnReturn</td>
    <td>false</td>
    <td>
       The indication of whether objects will be validated before being
       returned to the pool.
    </td>
 </tr>
 <tr>
    <td>testWhileIdle</td>
    <td>false</td>
    <td>
       The indication of whether objects will be validated by the idle object
       evictor (if any).  If an object fails to validate, it will be dropped
       from the pool.
    </td>
 </tr>
 <tr>
    <td>timeBetweenEvictionRunsMillis</td>
    <td>-1</td>
    <td>
       The number of milliseconds to sleep between runs of the idle object
       evictor thread.  When non-positive, no idle object evictor thread will
       be run.
    </td>
 </tr>
 <tr>
    <td>numTestsPerEvictionRun</td>
    <td>3</td>
    <td>
       The number of objects to examine during each run of the idle object
       evictor thread (if any).
    </td>
 </tr>
 <tr>
    <td>minEvictableIdleTimeMillis</td>
    <td>1000 * 60 * 30</td>
    <td>
       The minimum amount of time an object may sit idle in the pool before it
       is eligible for eviction by the idle object evictor (if any).
    </td>
 </tr>
 <tr>
    <td>softMinEvictableIdleTimeMillis</td>
    <td>-1</td>
    <td>
       The minimum amount of time a connection may sit idle in the pool before
       it is eligible for eviction by the idle connection evictor, with
       the extra condition that at least "minIdle" connections remain in the
       pool. When minEvictableIdleTimeMillis is set to a positive value,
       minEvictableIdleTimeMillis is examined first by the idle
       connection evictor - i.e. when idle connections are visited by the
       evictor, idle time is first compared against minEvictableIdleTimeMillis
       (without considering the number of idle connections in the pool) and then
       against softMinEvictableIdleTimeMillis, including the minIdle constraint.
    </td>
 </tr>
 <tr>
    <td>maxConnLifetimeMillis</td>
    <td>-1</td>
    <td>
       The maximum lifetime in milliseconds of a connection. After this time is
       exceeded the connection will fail the next activation, passivation or
       validation test. A value of zero or less means the connection has an
       infinite lifetime.
    </td>
 </tr>
 <tr>
    <td>logExpiredConnections</td>
    <td>true</td>
    <td>
       Flag to log a message indicating that a connection is being closed by the
       pool due to maxConnLifetimeMillis exceeded. Set this property to false
       to suppress expired connection logging that is turned on by default.
    </td>
 </tr>
 <tr>
    <td>connectionInitSqls</td>
    <td>null</td>
    <td>
       A Collection of SQL statements that will be used to initialize physical
       connections when they are first created.  These statements are executed
       only once - when the configured connection factory creates the connection.
    </td>
 </tr>
 <tr>
    <td>lifo</td>
    <td>true</td>
    <td>
       True means that borrowObject returns the most recently used ("last in")
       connection in the pool (if there are idle connections available).  False
       means that the pool behaves as a FIFO queue - connections are taken from
       the idle instance pool in the order that they are returned to the pool.
    </td>
 </tr>
 </table>

 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
    <td>poolPreparedStatements</td>
    <td>false</td>
    <td>Enable prepared statement pooling for this pool.</td>
 </tr>
 <tr>
    <td>maxOpenPreparedStatements</td>
    <td>unlimited</td>
    <td>
       The maximum number of open statements that can be allocated from
       the statement pool at the same time, or negative for no limit.
    </td>
 </tr>
 </table>
 <p>
 <img src="images/icon_info_sml.gif"/>
 This component has also the ability to pool PreparedStatements.
 When enabled a statement pool will be created for each Connection
 and PreparedStatements created by one of the following methods will be pooled:
 <ul>
    <li>public PreparedStatement prepareStatement(String sql)</li>
    <li>public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)</li>
 </ul>
 </p>
 <p>
 <img src="images/icon_warning_sml.gif"/>
 <strong>NOTE</strong> - Make sure your connection has some resources left for the other statements.
 Pooling PreparedStatements may keep their cursors open in the database, causing a connection to run out of cursors,
 especially if maxOpenPreparedStatements is left at the default (unlimited) and an application opens a large number
 of different PreparedStatements per connection. To avoid this problem, maxOpenPreparedStatements should be set to a
 value less than the maximum number of cursors that can be open on a Connection.
 </p>


 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
    <td>accessToUnderlyingConnectionAllowed</td>
    <td>false</td>
    <td>Controls if the PoolGuard allows access to the underlying connection.</td>
 </tr>
 </table>
 <p>When allowed you can access the underlying connection using the following construct:</p>
 <source>
     Connection conn = ds.getConnection();
     Connection dconn = ((DelegatingConnection) conn).getInnermostDelegate();
     ...
     conn.close()
 </source>
 <p>
 <img src="images/icon_info_sml.gif"/>
 Default is false, it is a potential dangerous operation and misbehaving programs can do harmful things. (closing the underlying or continue using it when the guarded connection is already closed)
 Be careful and only use when you need direct access to driver specific extensions.
 </p>
 <p>
 <img src="images/icon_warning_sml.gif"/>
 <b>NOTE:</b> Do not close the underlying connection, only the original one.
 </p>


 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
 <tr>
    <td>removeAbandonedOnMaintenance <br/>
        removeAbandonedOnBorrow
    </td>
    <td>false</td>
    <td>
       Flags to remove abandoned connections if they exceed the
       removeAbandonedTimout.<br/>
       A connection is considered abandoned and eligible
       for removal if it has not been used for longer than removeAbandonedTimeout.<br/>
       Creating a Statement, PreparedStatement or CallableStatement or using
       one of these to execute a query (using one of the execute methods)
       resets the lastUsed property of the parent connection.<br/>
       Setting one or both of these to true can recover db connections from poorly written
       applications which fail to close connections.<br/>
       Setting removeAbandonedOnMaintenance to true removes abandoned connections on the
       maintenance cycle (when eviction ends). This property has no effect unless maintenance
       is enabled by setting timeBetweenEvictionRunsMillis to a positive value. <br/>
       If removeAbandonedOnBorrow is true, abandoned connections are removed each time
       a connection is borrowed from the pool, with the additional requirements that
       <ul><li>getNumActive() &gt; getMaxTotal() - 3; and</li>
           <li>getNumIdle() &lt; 2 </li></ul>
    </td>
 </tr>
 <tr>
    <td>removeAbandonedTimeout</td>
    <td>300</td>
    <td>Timeout in <b>seconds</b> before an abandoned connection can be removed.</td>
 </tr>
 <tr>
    <td>logAbandoned</td>
    <td>false</td>
    <td>
       Flag to log stack traces for application code which abandoned
       a Statement or Connection.<br/>
       Logging of abandoned Statements and Connections adds overhead
       for every Connection open or new Statement because a stack
       trace has to be generated.
    </td>
 </tr>
 <tr>
    <td>abandonedUsageTracking</td>
    <td>false</td>
    <td>
       If true, the connection pool records a stack trace every time a method is called on a
       pooled connection and retains the most recent stack trace to aid debugging
       of abandoned connections. There is significant overhead added by setting this
       to true.
    </td>
 </tr>
 </table>
 <p>
 <img src="images/icon_info_sml.gif"/>
 If you have enabled removeAbandonedOnMaintenance or removeAbandonedOnBorrow then it is possible that
 a connection is reclaimed by the pool because it is considered to be abandoned. This mechanism is triggered
 when (getNumIdle() &lt; 2) and (getNumActive() &gt; getMaxTotal() - 3) and removeAbandonedOnBorrow is true;
 or after eviction finishes and removeAbandonedOnMaintenance is true. For example, maxTotal=20 and 18 active
 connections and 1 idle connection would trigger removeAbandonedOnBorrow, but only the active connections
 that aren't used for more then "removeAbandonedTimeout" seconds are removed (default 300 sec). Traversing
 a resultset doesn't count as being used. Creating a Statement, PreparedStatement or CallableStatement or
 using one of these to execute a query (using one of the execute methods) resets the lastUsed property of
 the parent connection.
 </p>
 <table>
 <hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
 <tr>
    <td>fastFailValidation</td>
    <td>false</td>
    <td>
       When this property is true, validation fails fast for connections that have
       thrown "fatal" SQLExceptions. Requests to validate disconnected connections
       fail immediately, with no call to the driver's isValid method or attempt to
       execute a validation query.<br/>
       The SQL_STATE codes considered to signal fatal errors are by default the following:
       <ul>
         <li>57P01 (ADMIN SHUTDOWN)</li>
         <li>57P02 (CRASH SHUTDOWN)</li>
         <li>57P03 (CANNOT CONNECT NOW)</li>
         <li>01002 (SQL92 disconnect error)</li>
         <li>JZ0C0 (Sybase disconnect error)</li>
         <li>JZ0C1 (Sybase disconnect error)</li>
         <li>Any SQL_STATE code that starts with "08"</li>
       </ul>
       To override this default set of disconnection codes, set the
       <code>disconnectionSqlCodes</code> property.
    </td>
 </tr>
 <tr>
    <td>disconnectionSqlCodes</td>
    <td>null</td>
    <td>Comma-delimited list of SQL_STATE codes considered to signal fatal disconnection
        errors. Setting this property has no effect unless
       <code>fastFailValidation</code> is set to <code>true.</code>
    </td>
 </tr>
 </table>

 </section>

 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<document>

	<properties>
	<title>BasicDataSource Configuration</title>
	<author email="dev@commons.apache.org">Commons Documentation Team</author>
	</properties>

	<body>

	<!--
	<section name="Introduction">
	<p>TODO: add section about tomcat configuration and avoiding the resource leak when reloading tomcat webapps.</p>
	</section>
	-->

	<!--
	<section name="Dynamic Properties">
	maxTotal
	maxIdle
	minIdle
	maxWaitMillis
	testOnBorrow
	testOnReturn
	timeBetweenEvictionRunsMillis
	numTestsPerEvictionRun
	minEvictableIdleTimeMillis
	testWhileIdle

	</section>
	-->

	<section name="BasicDataSource Configuration Parameters">

	<table>
	<hr><th>Parameter</th><th>Description</th></hr>
	<tr>
	<td>username</td>
	<td>The connection user name to be passed to our JDBC driver to establish a connection.</td>
	</tr>
	<tr>
	<td>password</td>
	<td>The connection password to be passed to our JDBC driver to establish a connection.</td>
	</tr>
	<tr>
	<td>url</td>
	<td>The connection URL to be passed to our JDBC driver to establish a connection.</td>
	</tr>
	<tr>
	<td>driverClassName</td>
	<td>The fully qualified Java class name of the JDBC driver to be used.</td>
	</tr>
	<tr>
	<td>connectionProperties</td>
	<td>The connection properties that will be sent to our JDBC driver when establishing new connections.
	<br/>Format of the string must be [propertyName=property;]*
	<br/><strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly,
	so they do not need to be included here.
	</td>
	</tr>
	</table>


	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
	<tr>
	<td>defaultAutoCommit</td>
	<td>driver default</td>
	<td>The default auto-commit state of connections created by this pool.
	If not set then the setAutoCommit method will not be called.
	</td>
	</tr>
	<tr>
	<td>defaultReadOnly</td>
	<td>driver default</td>
	<td>The default read-only state of connections created by this pool.
	If not set then the setReadOnly method will not be called.
	(Some drivers don't support read only mode, ex: Informix)
	</td>
	</tr>
	<tr>
	<td>defaultTransactionIsolation</td>
	<td>driver default</td>
	<td>The default TransactionIsolation state of connections created by this pool.
	One of the following: (see
	<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary">javadoc</a>)
	<ul>
	<li>NONE</li>
	<li>READ_COMMITTED</li>
	<li>READ_UNCOMMITTED</li>
	<li>REPEATABLE_READ</li>
	<li>SERIALIZABLE</li>
	</ul>
	</td>
	</tr>
	<tr>
	<td>defaultCatalog</td>
	<td></td>
	<td>The default catalog of connections created by this pool.</td>
	</tr>
	<tr>
	<td>cacheState</td>
	<td>true</td>
	<td>If true, the pooled connection will cache the current readOnly and
	autoCommit settings when first read or written and on all subsequent
	writes. This removes the need for additional database queries for any
	further calls to the getter. If the underlying connection is accessed
	directly and the readOnly and/or autoCommit settings changed the cached
	values will not reflect the current state. In this case, caching should be
	disabled by setting this attribute to false.</td>
	</tr>
	<tr>
	<td>defaultQueryTimeout</td>
	<td>null</td>
	<td>If non-null, the value of this <code>Integer</code> property determines
	the query timeout that will be used for Statements created from
	connections managed by the pool. <code>null</code> means that the driver
	default will be used.</td>
	</tr>
	<tr>
	<td>enableAutoCommitOnReturn</td>
	<td>true</td>
	<td>If true, connections being returned to the pool will be checked and configured with
	<code>Connection.setAutoCommit(true)</code> if the auto commit setting is
	<code>false</code> when the connection is returned.</td>
	</tr>
	<tr>
	<td>rollbackOnReturn</td>
	<td>true</td>
	<td>True means a connection will be rolled back when returned to the pool if
	auto commit is not enabled and the connection is not read-only.</td>
	</tr>
	</table>


	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
	<tr>
	<td>initialSize</td>
	<td>0</td>
	<td>
	The initial number of connections that are created when the pool
	is started.
	<br/>Since: 1.2
	</td>
	</tr>
	<tr>
	<td>maxTotal</td>
	<td>8</td>
	<td>
	The maximum number of active connections that can be allocated from
	this pool at the same time, or negative for no limit.
	</td>
	</tr>
	<tr>
	<td>maxIdle</td>
	<td>8</td>
	<td>
	The maximum number of connections that can remain idle in the
	pool, without extra ones being released, or negative for no limit.
	</td>
	</tr>
	<tr>
	<td>minIdle</td>
	<td>0</td>
	<td>
	The minimum number of connections that can remain idle in the
	pool, without extra ones being created, or zero to create none.
	</td>
	</tr>
	<tr>
	<td>maxWaitMillis</td>
	<td>indefinitely</td>
	<td>
	The maximum number of milliseconds that the pool will wait (when there
	are no available connections) for a connection to be returned before
	throwing an exception, or -1 to wait indefinitely.
	</td>
	</tr>
	</table>
	<p>
	<img src="images/icon_warning_sml.gif"/>
	<strong>NOTE</strong>: If maxIdle is set too low on heavily loaded systems it is
	possible you will see connections being closed and almost immediately new
	connections being opened. This is a result of the active threads momentarily
	closing connections faster than they are opening them, causing the number of
	idle connections to rise above maxIdle. The best value for maxIdle for heavily
	loaded system will vary but the default is a good starting point.
	</p>


	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
	<tr>
	<td>validationQuery</td>
	<td></td>
	<td>
	The SQL query that will be used to validate connections from this pool
	before returning them to the caller. If specified, this query
	<strong>MUST</strong> be an SQL SELECT statement that returns at least
	one row. If not specified, connections will be validation by calling the
	isValid() method.
	</td>
	</tr>
	<tr>
	<td>validationQueryTimeout</td>
	<td>no timeout</td>
	<td>The timeout in seconds before connection validation queries fail. If set
	to a positive value, this value is passed to the driver via the
	<code>setQueryTimeout</code> method of the <code>Statement</code>
	used to execute the validation query.</td>
	</tr>
	<tr>
	<td>testOnCreate</td>
	<td>false</td>
	<td>
	The indication of whether objects will be validated after creation. If the
	object fails to validate, the borrow attempt that triggered the object
	creation will fail.
	</td>
	</tr>
	<tr>
	<td>testOnBorrow</td>
	<td>true</td>
	<td>
	The indication of whether objects will be validated before being
	borrowed from the pool. If the object fails to validate, it will be
	dropped from the pool, and we will attempt to borrow another.
	</td>
	</tr>
	<tr>
	<td>testOnReturn</td>
	<td>false</td>
	<td>
	The indication of whether objects will be validated before being
	returned to the pool.
	</td>
	</tr>
	<tr>
	<td>testWhileIdle</td>
	<td>false</td>
	<td>
	The indication of whether objects will be validated by the idle object
	evictor (if any). If an object fails to validate, it will be dropped
	from the pool.
	</td>
	</tr>
	<tr>
	<td>timeBetweenEvictionRunsMillis</td>
	<td>-1</td>
	<td>
	The number of milliseconds to sleep between runs of the idle object
	evictor thread. When non-positive, no idle object evictor thread will
	be run.
	</td>
	</tr>
	<tr>
	<td>numTestsPerEvictionRun</td>
	<td>3</td>
	<td>
	The number of objects to examine during each run of the idle object
	evictor thread (if any).
	</td>
	</tr>
	<tr>
	<td>minEvictableIdleTimeMillis</td>
	<td>1000 * 60 * 30</td>
	<td>
	The minimum amount of time an object may sit idle in the pool before it
	is eligible for eviction by the idle object evictor (if any).
	</td>
	</tr>
	<tr>
	<td>softMinEvictableIdleTimeMillis</td>
	<td>-1</td>
	<td>
	The minimum amount of time a connection may sit idle in the pool before
	it is eligible for eviction by the idle connection evictor, with
	the extra condition that at least "minIdle" connections remain in the
	pool. When minEvictableIdleTimeMillis is set to a positive value,
	minEvictableIdleTimeMillis is examined first by the idle
	connection evictor - i.e. when idle connections are visited by the
	evictor, idle time is first compared against minEvictableIdleTimeMillis
	(without considering the number of idle connections in the pool) and then
	against softMinEvictableIdleTimeMillis, including the minIdle constraint.
	</td>
	</tr>
	<tr>
	<td>maxConnLifetimeMillis</td>
	<td>-1</td>
	<td>
	The maximum lifetime in milliseconds of a connection. After this time is
	exceeded the connection will fail the next activation, passivation or
	validation test. A value of zero or less means the connection has an
	infinite lifetime.
	</td>
	</tr>
	<tr>
	<td>logExpiredConnections</td>
	<td>true</td>
	<td>
	Flag to log a message indicating that a connection is being closed by the
	pool due to maxConnLifetimeMillis exceeded. Set this property to false
	to suppress expired connection logging that is turned on by default.
	</td>
	</tr>
	<tr>
	<td>connectionInitSqls</td>
	<td>null</td>
	<td>
	A Collection of SQL statements that will be used to initialize physical
	connections when they are first created. These statements are executed
	only once - when the configured connection factory creates the connection.
	</td>
	</tr>
	<tr>
	<td>lifo</td>
	<td>true</td>
	<td>
	True means that borrowObject returns the most recently used ("last in")
	connection in the pool (if there are idle connections available). False
	means that the pool behaves as a FIFO queue - connections are taken from
	the idle instance pool in the order that they are returned to the pool.
	</td>
	</tr>
	</table>

	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
	<td>poolPreparedStatements</td>
	<td>false</td>
	<td>Enable prepared statement pooling for this pool.</td>
	</tr>
	<tr>
	<td>maxOpenPreparedStatements</td>
	<td>unlimited</td>
	<td>
	The maximum number of open statements that can be allocated from
	the statement pool at the same time, or negative for no limit.
	</td>
	</tr>
	</table>
	<p>
	<img src="images/icon_info_sml.gif"/>
	This component has also the ability to pool PreparedStatements.
	When enabled a statement pool will be created for each Connection
	and PreparedStatements created by one of the following methods will be pooled:
	<ul>
	<li>public PreparedStatement prepareStatement(String sql)</li>
	<li>public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)</li>
	</ul>
	</p>
	<p>
	<img src="images/icon_warning_sml.gif"/>
	<strong>NOTE</strong> - Make sure your connection has some resources left for the other statements.
	Pooling PreparedStatements may keep their cursors open in the database, causing a connection to run out of cursors,
	especially if maxOpenPreparedStatements is left at the default (unlimited) and an application opens a large number
	of different PreparedStatements per connection. To avoid this problem, maxOpenPreparedStatements should be set to a
	value less than the maximum number of cursors that can be open on a Connection.
	</p>


	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr>
	<td>accessToUnderlyingConnectionAllowed</td>
	<td>false</td>
	<td>Controls if the PoolGuard allows access to the underlying connection.</td>
	</tr>
	</table>
	<p>When allowed you can access the underlying connection using the following construct:</p>
	<source>
	Connection conn = ds.getConnection();
	Connection dconn = ((DelegatingConnection) conn).getInnermostDelegate();
	...
	conn.close()
	</source>
	<p>
	<img src="images/icon_info_sml.gif"/>
	Default is false, it is a potential dangerous operation and misbehaving programs can do harmful things. (closing the underlying or continue using it when the guarded connection is already closed)
	Be careful and only use when you need direct access to driver specific extensions.
	</p>
	<p>
	<img src="images/icon_warning_sml.gif"/>
	<b>NOTE:</b> Do not close the underlying connection, only the original one.
	</p>


	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
	<tr>
	<td>removeAbandonedOnMaintenance <br/>
	removeAbandonedOnBorrow
	</td>
	<td>false</td>
	<td>
	Flags to remove abandoned connections if they exceed the
	removeAbandonedTimout.<br/>
	A connection is considered abandoned and eligible
	for removal if it has not been used for longer than removeAbandonedTimeout.<br/>
	Creating a Statement, PreparedStatement or CallableStatement or using
	one of these to execute a query (using one of the execute methods)
	resets the lastUsed property of the parent connection.<br/>
	Setting one or both of these to true can recover db connections from poorly written
	applications which fail to close connections.<br/>
	Setting removeAbandonedOnMaintenance to true removes abandoned connections on the
	maintenance cycle (when eviction ends). This property has no effect unless maintenance
	is enabled by setting timeBetweenEvictionRunsMillis to a positive value. <br/>
	If removeAbandonedOnBorrow is true, abandoned connections are removed each time
	a connection is borrowed from the pool, with the additional requirements that
	<ul><li>getNumActive() > getMaxTotal() - 3; and</li>
	<li>getNumIdle() < 2 </li></ul>
	</td>
	</tr>
	<tr>
	<td>removeAbandonedTimeout</td>
	<td>300</td>
	<td>Timeout in <b>seconds</b> before an abandoned connection can be removed.</td>
	</tr>
	<tr>
	<td>logAbandoned</td>
	<td>false</td>
	<td>
	Flag to log stack traces for application code which abandoned
	a Statement or Connection.<br/>
	Logging of abandoned Statements and Connections adds overhead
	for every Connection open or new Statement because a stack
	trace has to be generated.
	</td>
	</tr>
	<tr>
	<td>abandonedUsageTracking</td>
	<td>false</td>
	<td>
	If true, the connection pool records a stack trace every time a method is called on a
	pooled connection and retains the most recent stack trace to aid debugging
	of abandoned connections. There is significant overhead added by setting this
	to true.
	</td>
	</tr>
	</table>
	<p>
	<img src="images/icon_info_sml.gif"/>
	If you have enabled removeAbandonedOnMaintenance or removeAbandonedOnBorrow then it is possible that
	a connection is reclaimed by the pool because it is considered to be abandoned. This mechanism is triggered
	when (getNumIdle() < 2) and (getNumActive() > getMaxTotal() - 3) and removeAbandonedOnBorrow is true;
	or after eviction finishes and removeAbandonedOnMaintenance is true. For example, maxTotal=20 and 18 active
	connections and 1 idle connection would trigger removeAbandonedOnBorrow, but only the active connections
	that aren't used for more then "removeAbandonedTimeout" seconds are removed (default 300 sec). Traversing
	a resultset doesn't count as being used. Creating a Statement, PreparedStatement or CallableStatement or
	using one of these to execute a query (using one of the execute methods) resets the lastUsed property of
	the parent connection.
	</p>
	<table>
	<hr><th>Parameter</th><th>Default</th><th>Description</th></hr>
	<tr>
	<td>fastFailValidation</td>
	<td>false</td>
	<td>
	When this property is true, validation fails fast for connections that have
	thrown "fatal" SQLExceptions. Requests to validate disconnected connections
	fail immediately, with no call to the driver's isValid method or attempt to
	execute a validation query.<br/>
	The SQL_STATE codes considered to signal fatal errors are by default the following:
	<ul>
	<li>57P01 (ADMIN SHUTDOWN)</li>
	<li>57P02 (CRASH SHUTDOWN)</li>
	<li>57P03 (CANNOT CONNECT NOW)</li>
	<li>01002 (SQL92 disconnect error)</li>
	<li>JZ0C0 (Sybase disconnect error)</li>
	<li>JZ0C1 (Sybase disconnect error)</li>
	<li>Any SQL_STATE code that starts with "08"</li>
	</ul>
	To override this default set of disconnection codes, set the
	<code>disconnectionSqlCodes</code> property.
	</td>
	</tr>
	<tr>
	<td>disconnectionSqlCodes</td>
	<td>null</td>
	<td>Comma-delimited list of SQL_STATE codes considered to signal fatal disconnection
	errors. Setting this property has no effect unless
	<code>fastFailValidation</code> is set to <code>true.</code>
	</td>
	</tr>
	</table>

	</section>

	</body>
	</document>