You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2017/08/03 16:31:17 UTC
commons-dbcp git commit: [DBCP-478] Wrong parameter name in site
documentation for BasicDataSource Configuration Parameters.
Repository: commons-dbcp
Updated Branches:
refs/heads/master 5e61ba965 -> 9b8ecc1ca
[DBCP-478] Wrong parameter name in site documentation for
BasicDataSource Configuration Parameters.
Project: http://git-wip-us.apache.org/repos/asf/commons-dbcp/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-dbcp/commit/9b8ecc1c
Tree: http://git-wip-us.apache.org/repos/asf/commons-dbcp/tree/9b8ecc1c
Diff: http://git-wip-us.apache.org/repos/asf/commons-dbcp/diff/9b8ecc1c
Branch: refs/heads/master
Commit: 9b8ecc1ca8fe64fcf11dbe406c14d29a12ef0ea7
Parents: 5e61ba9
Author: ggregory <gg...@US-L-GG05.rocketsoftware.com>
Authored: Thu Aug 3 09:31:10 2017 -0700
Committer: ggregory <gg...@US-L-GG05.rocketsoftware.com>
Committed: Thu Aug 3 09:31:10 2017 -0700
----------------------------------------------------------------------
src/changes/changes.xml | 3 +
src/site/xdoc/configuration.xml | 1012 +++++++++++++++++-----------------
2 files changed, 509 insertions(+), 506 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/9b8ecc1c/src/changes/changes.xml
----------------------------------------------------------------------
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 8b1c144..d6f13c7 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -65,6 +65,9 @@ The <action> type attribute can be add,update,fix,remove.
<action dev="mattsicker" type="fix" issue="DBCP-454" due-to="Philipp Marx, Matt Sicker">
OSGi declarations contain multiple import headers for javax.transaction.
</action>
+ <action dev="ggregory" type="fix" issue="DBCP-478" due-to="nicola mele">
+ Wrong parameter name in site documentation for BasicDataSource Configuration Parameters.
+ </action>
<action dev="psteitz" type="fix" issue="DBCP-452">
Add jmxName to properties set by BasicDataSourceFactory. This
enables container-managed pools created from JNDI Resource
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/9b8ecc1c/src/site/xdoc/configuration.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/configuration.xml b/src/site/xdoc/configuration.xml
index 7d4aae2..6fe6e8f 100644
--- a/src/site/xdoc/configuration.xml
+++ b/src/site/xdoc/configuration.xml
@@ -1,506 +1,506 @@
-<?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 username 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 eligable 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 timeBetweenEvicionRunsMillis 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>
+<?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 username 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 eligable 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 timeBetweenEvicionRunsMillis 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>