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() &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="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() &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>

Reply via email to