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 <ggreg...@us-l-gg05.rocketsoftware.com> Authored: Thu Aug 3 09:31:10 2017 -0700 Committer: ggregory <ggreg...@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="d...@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="d...@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>