You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by rj...@apache.org on 2012/12/05 21:21:01 UTC
svn commit: r1417624 [25/38] - in /tomcat/site/trunk/docs/tomcat-8.0-doc: ./
api/ appdev/ appdev/sample/ appdev/sample/docs/ appdev/sample/src/
appdev/sample/src/mypackage/ appdev/sample/web/ appdev/sample/web/WEB-INF/
appdev/sample/web/images/ archite...
Added: tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html?rev=1417624&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html (added)
+++ tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html Wed Dec 5 20:20:35 2012
@@ -0,0 +1,791 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 8 (8.0.0-dev) - The Tomcat JDBC Connection Pool</title><meta name="author" content="Filip Hanik"><style type="text/css" media="print">
+ .noPrint {display: none;}
+ td#mainBody {width: 100%;}
+ </style><style type="text/css">
+ code {background-color:rgb(224,255,255);padding:0 0.1em;}
+ code.attributeName, code.propertyName {background-color:transparent;}
+ </style><style type="text/css">
+ .wrapped-source code { display: block; background-color: transparent; }
+ .wrapped-source div { margin: 0 0 0 1.25em; }
+ .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
+ </style><style type="text/css">
+ p.notice {
+ border: 1px solid rgb(255, 0, 0);
+ background-color: rgb(238, 238, 238);
+ color: rgb(0, 51, 102);
+ padding: 0.5em;
+ margin: 1em 2em 1em 1em;
+ }
+ </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
+ The Apache Tomcat Servlet/JSP Container
+ " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 8</font></h1><font face="arial,helvetica,sanserif">Version 8.0.0-dev, Dec 5 2012</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="
manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li
><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/i
ndex.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/index.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Tomcat JDBC Connection Pool</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
+<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#How_to_use">How to use</a><ol><li><a href="#Additional_features">Additional features</a></li><li><a href="#Inside_the_Apache_Tomcat_Container">Inside the Apache Tomcat Container</a></li><li><a href="#Standalone">Standalone</a></li><li><a href="#JMX">JMX</a></li></ol></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#JNDI_Factory_and_Type">JNDI Factory and Type</a></li><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Tomcat_JDBC_Enhanced_Attributes">Tomcat JDBC Enhanced Attributes</a></li></ol></li><li><a href="#Advanced_usage">Advanced usage</a><ol><li><a href="#JDBC_interceptors">JDBC interceptors</a></li><li><a href="#Configuring_JDBC_interceptors">Configuring JDBC interceptors</a></li><li><a href="#org.apache.tomcat.jdbc.pool.JdbcInterceptor">org.apache.tomcat.jdbc.pool.JdbcInterceptor</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.ConnectionState">org.apa
che.tomcat.jdbc.pool.interceptor.ConnectionState</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer">org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor">org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor">org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport">org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx">org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx</a></li><li><a href="#org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer">org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer</a></li></ol></li><li><a href="#Code_Example">Code Example</a><ol>
<li><a href="#Plain_Ol'_Java">Plain Ol' Java</a></li><li><a href="#As_a_Resource">As a Resource</a></li><li><a href="#Asynchronous_Connection_Retrieval">Asynchronous Connection Retrieval</a></li><li><a href="#Interceptors">Interceptors</a></li><li><a href="#Getting_the_actual_JDBC_connection">Getting the actual JDBC connection</a></li></ol></li><li><a href="#Building">Building</a><ol><li><a href="#Building_from_source">Building from source</a></li></ol></li></ul>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>JDBC Connection Pool <code>org.apache.tomcat.jdbc.pool</code></strong>
+ is a replacement or an alternative to the <a href="http://commons.apache.org/dbcp/">commons-dbcp</a>
+ connection pool.</p>
+
+ <p>So why do we need a new connection pool?</p>
+
+ <p>Here are a few of the reasons:
+ <ol>
+ <li>commons-dbcp is single threaded, in order to be thread safe commons-dbcp locks the entire pool, even during query validation.</li>
+ <li>commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency
+ Even with the enormous optimizations of the <code>synchronized</code> statement in Java 6, commons-dbcp still suffers in speed and concurrency.</li>
+ <li>commons-dbcp is complex, over 60 classes. tomcat-jdbc-pool, core is 8 classes, hence modifications for future requirement will require
+ much less changes. This is all you need to run the connection pool itself, the rest is gravy.</li>
+ <li>commons-dbcp uses static interfaces. This means you can't compile it with JDK 1.6, or if you run on JDK 1.6/1.7 you will get
+ <code>NoSuchMethodException</code> for all the methods not implemented, even if the driver supports it. </li>
+ <li>The commons-dbcp has become fairly stagnant. Sparse updates, releases, and new feature support.</li>
+ <li>It's not worth rewriting over 60 classes, when something as a connection pool can be accomplished with as a much simpler implementation.</li>
+ <li>Tomcat jdbc pool implements a fairness option not available in commons-dbcp and still performs faster than commons-dbcp</li>
+ <li>Tomcat jdbc pool implements the ability retrieve a connection asynchronously, without adding additional threads to the library itself</li>
+ <li>Tomcat jdbc pool is a Tomcat module, it depends on Tomcat JULI, a simplified logging framework used in Tomcat.</li>
+ <li>Retrieve the underlying connection using the <code>javax.sql.PooledConnection</code> interface.</li>
+ <li>Starvation proof. If a pool is empty, and threads are waiting for a connection, when a connection is returned,
+ the pool will awake the correct thread waiting. Most pools will simply starve.</li>
+ </ol>
+ </p>
+
+ <p>Features added over other connection pool implementations
+ <ol>
+ <li>Support for highly concurrent environments and multi core/cpu systems.</li>
+ <li>Dynamic implementation of interface, will support <code>java.sql</code> and <code>javax.sql</code> interfaces for
+ your runtime environment (as long as your JDBC driver does the same), even when compiled with a lower version of the JDK.</li>
+ <li>Validation intervals - we don't have to validate every single time we use the connection, we can do this
+ when we borrow or return the connection, just not more frequent than an interval we can configure.</li>
+ <li>Run-Once query, a configurable query that will be run only once, when the connection to the database is established.
+ Very useful to setup session settings, that you want to exist during the entire time the connection is established.</li>
+ <li>Ability to configure custom interceptors.
+ This allows you to write custom interceptors to enhance the functionality. You can use interceptors to gather query stats,
+ cache session states, reconnect the connection upon failures, retry queries, cache query results, and so on.
+ Your options are endless and the interceptors are dynamic, not tied to a JDK version of a
+ <code>java.sql</code>/<code>javax.sql</code> interface.</li>
+ <li>High performance - we will show some differences in performance later on</li>
+ <li>Extremely simple, due to the very simplified implementation, the line count and source file count are very low, compare with c3p0
+ that has over 200 source files(last time we checked), Tomcat jdbc has a core of 8 files, the connection pool itself is about half
+ that. As bugs may occur, they will be faster to track down, and easier to fix. Complexity reduction has been a focus from inception.</li>
+ <li>Asynchronous connection retrieval - you can queue your request for a connection and receive a <code>Future<Connection></code> back.</li>
+ <li>Better idle connection handling. Instead of closing connections directly, it can still pool connections and sizes the idle pool with a smarter algorithm.</li>
+ <li>You can decide at what moment connections are considered abandoned, is it when the pool is full, or directly at a timeout
+ by specifying a pool usage threshold.
+ </li>
+ <li>The abandon connection timer will reset upon a statement/query activity. Allowing a connections that is in use for a long time to not timeout.
+ This is achieved using the <code>ResetAbandonedTimer</code>
+ </li>
+ <li>Close connections after they have been connected for a certain time. Age based close upon return to the pool.
+ </li>
+ <li>Get JMX notifications and log entries when connections are suspected for being abandoned. This is similar to
+ the <code>removeAbandonedTimeout</code> but it doesn't take any action, only reports the information.
+ This is achieved using the <code>suspectTimeout</code> attribute.</li>
+ <li>Connections can be retrieved from a <code>java.sql.Driver</code>, <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code>
+ This is achieved using the <code>dataSource</code> and <code>dataSourceJNDI</code> attributes.</li>
+ <li>XA connection support</li>
+ </ol>
+ </p>
+
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="How to use"><!--()--></a><a name="How_to_use"><strong>How to use</strong></a></font></td></tr><tr><td><blockquote>
+ <p>
+ Usage of the Tomcat connection pool has been made to be as simple as possible, for those of you that are familiar with commons-dbcp, the
+ transition will be very simple. Moving from other connection pools is also fairly straight forward.
+ </p>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Additional features"><!--()--></a><a name="Additional_features"><strong>Additional features</strong></a></font></td></tr><tr><td><blockquote>
+ <p>The Tomcat connection pool offers a few additional features over what most other pools let you do:</p>
+ <ul>
+ <li><code>initSQL</code> - the ability to run a SQL statement exactly once, when the connection is created</li>
+ <li><code>validationInterval</code> - in addition to running validations on connections, avoid running them too frequently.</li>
+ <li><code>jdbcInterceptors</code> - flexible and pluggable interceptors to create any customizations around the pool,
+ the query execution and the result set handling. More on this in the advanced section.</li>
+ <li><code>fairQueue</code> - Set the fair flag to true to achieve thread fairness or to use asynchronous connection retrieval</li>
+ </ul>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Inside the Apache Tomcat Container"><!--()--></a><a name="Inside_the_Apache_Tomcat_Container"><strong>Inside the Apache Tomcat Container</strong></a></font></td></tr><tr><td><blockquote>
+ <p>
+ The Tomcat Connection pool is configured as a resource described in <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">The Tomcat JDBC documentation</a>
+ With the only difference being that you have to specify the <code>factory</code> attribute and set the value to
+ <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code>
+ </p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standalone"><strong>Standalone</strong></a></font></td></tr><tr><td><blockquote>
+ <p>
+ The connection pool only has another dependency, and that is on tomcat-juli.jar.
+ To configure the pool in a stand alone project using bean instantiation, the bean to instantiate is
+ <code>org.apache.tomcat.jdbc.pool.DataSource</code>. The same attributes (documented below) as you use to configure a connection
+ pool as a JNDI resource, are used to configure a data source as a bean.
+ </p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JMX"><strong>JMX</strong></a></font></td></tr><tr><td><blockquote>
+ <p>
+ The connection pool object exposes an MBean that can be registered.
+ In order for the connection pool object to create the MBean, the flag <code>jmxEnabled</code> has to be set to true.
+ This doesn't imply that the pool will be registered with an MBean server, merely that the MBean is created.
+ In a container like Tomcat, Tomcat itself registers the DataSource with the MBean server, the
+ <code>org.apache.tomcat.jdbc.pool.DataSource</code> object will then register the actual
+ connection pool MBean.
+ If you're running outside of a container, you can register the DataSource yourself under any object name you specify,
+ and it propagates the registration to the underlying pool. To do this you would call <code>mBeanServer.registerMBean(dataSource.getPool().getJmxPool(),objectname)</code>.
+ Prior to this call, ensure that the pool has been created by calling <code>dataSource.createPool()</code>.
+ </p>
+ </blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+ <p>To provide a very simple switch to and from commons-dbcp and tomcat-jdbc-pool,
+ Most attributes are the same and have the same meaning.</p>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JNDI Factory and Type"><!--()--></a><a name="JNDI_Factory_and_Type"><strong>JNDI Factory and Type</strong></a></font></td></tr><tr><td><blockquote>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">factory</code></strong></td><td align="left" valign="center">
+ <p>factory is required, and the value should be <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code></p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
+ <p>Type should always be <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code></p>
+ <p>Depending on the type a <code>org.apache.tomcat.jdbc.pool.DataSource</code> or a <code>org.apache.tomcat.jdbc.pool.XADataSource</code> will be created.</p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
+ <p>These attributes are shared between commons-dbcp and tomcat-jdbc-pool, in some cases default values are different.</p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">defaultAutoCommit</code></td><td align="left" valign="center">
+ <p>(boolean) The default auto-commit state of connections created by this pool. If not set, default is JDBC driver default (If not set then the <code>setAutoCommit</code> method will not be called.)</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultReadOnly</code></td><td align="left" valign="center">
+ <p>(boolean) The default read-only state of connections created by this pool. If not set then the <code>setReadOnly</code> method will not be called. (Some drivers don't support read only mode, ex: Informix)</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultTransactionIsolation</code></td><td align="left" valign="center">
+ <p>(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )
+ <ul>
+ <li><code>NONE</code></li>
+ <li><code>READ_COMMITTED</code></li>
+ <li><code>READ_UNCOMMITTED</code></li>
+ <li><code>REPEATABLE_READ</code></li>
+ <li><code>SERIALIZABLE</code></li>
+ </ul>
+ If not set, the method will not be called and it defaults to the JDBC driver.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultCatalog</code></td><td align="left" valign="center">
+ <p>(String) The default catalog of connections created by this pool.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverClassName</code></strong></td><td align="left" valign="center">
+ <p>(String) The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible
+ from the same classloader as tomcat-jdbc.jar
+ </p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">username</code></strong></td><td align="left" valign="center">
+ <p>(String) The connection username to be passed to our JDBC driver to establish a connection.
+ Note that method <code>DataSource.getConnection(username,password)</code>
+ by default will not use credentials passed into the method,
+ but will use the ones configured here. See <code>alternateUsernameAllowed</code>
+ property for more details.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">password</code></strong></td><td align="left" valign="center">
+ <p>(String) The connection password to be passed to our JDBC driver to establish a connection.
+ Note that method <code>DataSource.getConnection(username,password)</code>
+ by default will not use credentials passed into the method,
+ but will use the ones configured here. See <code>alternateUsernameAllowed</code>
+ property for more details.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxActive</code></td><td align="left" valign="center">
+ <p>(int) The maximum number of active connections that can be allocated from this pool at the same time.
+ The default value is <code>100</code></p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxIdle</code></td><td align="left" valign="center">
+ <p>(int) The maximum number of connections that should be kept in the pool at all times.
+ Default value is <code>maxActive</code>:<code>100</code>
+ Idle connections are checked periodically (if enabled) and
+ connections that been idle for longer than <code>minEvictableIdleTimeMillis</code>
+ will be released. (also see <code>testWhileIdle</code>)</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">minIdle</code></td><td align="left" valign="center">
+ <p>
+ (int) The minimum number of established connections that should be kept in the pool at all times.
+ The connection pool can shrink below this number if validation queries fail.
+ Default value is derived from <code>initialSize</code>:<code>10</code> (also see <code>testWhileIdle</code>)
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">initialSize</code></td><td align="left" valign="center">
+ <p>(int)The initial number of connections that are created when the pool is started.
+ Default value is <code>10</code></p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxWait</code></td><td align="left" valign="center">
+ <p>(int) 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.
+ Default value is <code>30000</code> (30 seconds)</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">testOnBorrow</code></td><td align="left" valign="center">
+ <p>(boolean) 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.
+ NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
+ In order to have a more efficient validation, see <code>validationInterval</code>.
+ Default value is <code>false</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">testOnReturn</code></td><td align="left" valign="center">
+ <p>(boolean) The indication of whether objects will be validated before being returned to the pool.
+ NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
+ The default value is <code>false</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">testWhileIdle</code></td><td align="left" valign="center">
+ <p>(boolean) 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.
+ NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
+ The default value is <code>false</code> and this property has to be set in order for the
+ pool cleaner/test thread is to run (also see <code>timeBetweenEvictionRunsMillis</code>)
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">validationQuery</code></td><td align="left" valign="center">
+ <p>(String) The SQL query that will be used to validate connections from this pool before returning them to the caller.
+ If specified, this query does not have to return any data, it just can't throw a <code>SQLException</code>.
+ The default value is <code>null</code>.
+ Example values are <code>SELECT 1</code>(mysql), <code>select 1 from dual</code>(oracle), <code>SELECT 1</code>(MS Sql Server)
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">validatorClassName</code></td><td align="left" valign="center">
+ <p>(String) The name of a class which implements the
+ <code>org.apache.tomcat.jdbc.pool.Validator</code> interface and
+ provides a no-arg constructor (may be implicit). If specified, the
+ class will be used to create a Validator instance which is then used
+ instead of any validation query to validate connections. The default
+ value is <code>null</code>. An example value is
+ <code>com.mycompany.project.SimpleValidator</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeBetweenEvictionRunsMillis</code></td><td align="left" valign="center">
+ <p>(int) The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread.
+ This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often
+ we validate idle connections.
+ The default value is <code>5000</code> (5 seconds). <br>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">numTestsPerEvictionRun</code></td><td align="left" valign="center">
+ <p>(int) Property not used in tomcat-jdbc-pool.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">minEvictableIdleTimeMillis</code></td><td align="left" valign="center">
+ <p>(int) The minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
+ The default value is <code>60000</code> (60 seconds).</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">accessToUnderlyingConnectionAllowed</code></td><td align="left" valign="center">
+ <p>(boolean) Property not used. Access can be achieved by calling <code>unwrap</code> on the pooled connection.
+ see <code>javax.sql.DataSource</code> interface, or call <code>getConnection</code> through reflection or
+ or cast the object as <code>javax.sql.PooledConnection</code></p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">removeAbandoned</code></td><td align="left" valign="center">
+ <p>(boolean) Flag to remove abandoned connections if they exceed the <code>removeAbandonedTimout</code>.
+ If set to true a connection is considered abandoned and eligible for removal if it has been in use
+ longer than the <code>removeAbandonedTimeout</code> Setting this to <code>true</code> can recover db connections from
+ applications that fail to close a connection. See also <code>logAbandoned</code>
+ The default value is <code>false</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">removeAbandonedTimeout</code></td><td align="left" valign="center">
+ <p>(int) Timeout in seconds before an abandoned(in use) connection can be removed.
+ The default value is <code>60</code> (60 seconds). The value should be set to the longest running query your applications
+ might have.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">logAbandoned</code></td><td align="left" valign="center">
+ <p>(boolean) Flag to log stack traces for application code which abandoned a Connection.
+ Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
+ The default value is <code>false</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionProperties</code></td><td align="left" valign="center">
+ <p>(String) The connection properties that will be sent to our JDBC driver when establishing new connections.
+ Format of the string must be [propertyName=property;]*
+ NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
+ The default value is <code>null</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">poolPreparedStatements</code></td><td align="left" valign="center">
+ <p>(boolean) Property not used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxOpenPreparedStatements</code></td><td align="left" valign="center">
+ <p>(int) Property not used.</p>
+ </td></tr></table>
+
+ </blockquote></td></tr></table>
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat JDBC Enhanced Attributes"><!--()--></a><a name="Tomcat_JDBC_Enhanced_Attributes"><strong>Tomcat JDBC Enhanced Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">initSQL</code></td><td align="left" valign="center">
+ <p>(String) A custom query to be run when a connection is first created.
+ The default value is <code>null</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">jdbcInterceptors</code></td><td align="left" valign="center">
+ <p>(String) A semicolon separated list of classnames extending
+ <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class.
+ See <a href="#Configuring_JDBC_interceptors">Configuring JDBC interceptors</a>
+ below for more detailed description of syntaz and examples.
+ </p>
+ <p>
+ These interceptors will be inserted as an interceptor into the chain
+ of operations on a <code>java.sql.Connection</code> object.
+ The default value is <code>null</code>.
+ </p>
+ <p>
+ Predefined interceptors:<br>
+ <code>org.apache.tomcat.jdbc.pool.interceptor.<br>ConnectionState</code>
+ - keeps track of auto commit, read only, catalog and transaction isolation level.<br>
+ <code>org.apache.tomcat.jdbc.pool.interceptor.<br>StatementFinalizer</code>
+ - keeps track of opened statements, and closes them when the connection is returned to the pool.
+ </p>
+ <p>
+ More predefined interceptors are described in detail in the
+ <a href="#JDBC_interceptors">JDBC Interceptors section</a>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">validationInterval</code></td><td align="left" valign="center">
+ <p>(long) avoid excess validation, only run validation at most at this frequency - time in milliseconds.
+ If a connection is due for validation, but has been validated previously within this interval, it will not be validated again.
+ The default value is <code>30000</code> (30 seconds).</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">jmxEnabled</code></td><td align="left" valign="center">
+ <p>(boolean) Register the pool with JMX or not.
+ The default value is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">fairQueue</code></td><td align="left" valign="center">
+ <p>(boolean) Set to true if you wish that calls to getConnection should be treated
+ fairly in a true FIFO fashion. This uses the <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue</code>
+ implementation for the list of the idle connections. The default value is <code>true</code>.
+ This flag is required when you want to use asynchronous connection retrieval.<br>
+ Setting this flag ensures that threads receive connections in the order they arrive.<br>
+ During performance tests, there is a very large difference in how locks
+ and lock waiting is implemented. When <code>fairQueue=true</code>
+ there is a decision making process based on what operating system the system is running.
+ If the system is running on Linux (property <code>os.name=Linux</code>.
+ To disable this Linux specific behavior and still use the fair queue, simply add the property
+ <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true</code> to your system properties
+ before the connection pool classes are loaded.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">abandonWhenPercentageFull</code></td><td align="left" valign="center">
+ <p>(int) Connections that have been abandoned (timed out) wont get closed and reported up unless
+ the number of connections in use are above the percentage defined by <code>abandonWhenPercentageFull</code>.
+ The value should be between 0-100.
+ The default value is <code>0</code>, which implies that connections are eligible for closure as soon
+ as <code>removeAbandonedTimeout</code> has been reached.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxAge</code></td><td align="left" valign="center">
+ <p>(long) Time in milliseconds to keep this connection. When a connection is returned to the pool,
+ the pool will check to see if the <code>now - time-when-connected > maxAge</code> has been reached,
+ and if so, it closes the connection rather than returning it to the pool.
+ The default value is <code>0</code>, which implies that connections will be left open and no age check
+ will be done upon returning the connection to the pool.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useEquals</code></td><td align="left" valign="center">
+ <p>(boolean) Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> and set to <code>false</code>
+ when you wish to use <code>==</code> when comparing method names. This property does not apply to added interceptors as those are configured individually.
+ The default value is <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">suspectTimeout</code></td><td align="left" valign="center">
+ <p>(int) Timeout value in seconds. Default value is <code>0</code>.<br>
+ Similar to to the <code>removeAbandonedTimeout</code> value but instead of treating the connection
+ as abandoned, and potentially closing the connection, this simply logs the warning if
+ <code>logAbandoned</code> is set to true. If this value is equal or less than 0, no suspect
+ checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
+ the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
+ logged and a JMX notification gets sent once.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">rollbackOnReturn</code></td><td align="left" valign="center">
+ <p>(boolean) If <code>autoCommit==false</code> then the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool
+ Default value is <code>false</code>.<br>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">commitOnReturn</code></td><td align="left" valign="center">
+ <p>(boolean) If <code>autoCommit==false</code> then the pool can complete the transaction by calling commit on the connection as it is returned to the pool
+ If <code>rollbackOnReturn==true</code> then this attribute is ignored.
+ Default value is <code>false</code>.<br>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateUsernameAllowed</code></td><td align="left" valign="center">
+ <p>(boolean) By default, the jdbc-pool will ignore the
+ <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)"><code>DataSource.getConnection(username,password)</code></a>
+ call, and simply return a previously pooled connection under the globally configured properties <code>username</code> and <code>password</code>, for performance reasons.
+ </p>
+ <p>
+ The pool can however be configured to allow use of different credentials
+ each time a connection is requested. To enable the functionality described in the
+ <a href="http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)"><code>DataSource.getConnection(username,password)</code></a>
+ call, simply set the property <code>alternateUsernameAllowed</code>
+ to <code>true</code>.<br>
+ Should you request a connection with the credentials user1/password1 and the connection
+ was previously connected using different user2/password2, the connection will be closed,
+ and reopened with the requested credentials. This way, the pool size is still managed
+ on a global level, and not on a per schema level. <br>
+ The default value is <code>false</code>.<br>
+ This property was added as an enhancement to <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=50025">bug 50025</a>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">dataSource</code></td><td align="left" valign="center">
+ <p>(javax.sql.DataSource) Inject a data source to the connection pool, and the pool will use the data source to retrieve connections instead of establishing them using the <code>java.sql.Driver</code> interface.
+ This is useful when you wish to pool XA connections or connections established using a data source instead of a connection string. Default value is <code>null</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">dataSourceJNDI</code></td><td align="left" valign="center">
+ <p>(String) The JNDI name for a data source to be looked up in JNDI and then used to establish connections to the database. See the <code>dataSource</code> attribute. Default value is <code>null</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDisposableConnectionFacade</code></td><td align="left" valign="center">
+ <p>(boolean) Set this to true if you wish to put a facade on your connection so that it cannot be reused after it has been closed. This prevents a thread holding on to a
+ reference of a connection it has already called closed on, to execute queries on it. Default value is <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">logValidationErrors</code></td><td align="left" valign="center">
+ <p>(boolean) Set this to true to log errors during the validation phase to the log file. If set to true, errors will be logged as SEVERE. Default value is <code>false</code> for backwards compatibility.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">propagateInterruptState</code></td><td align="left" valign="center">
+ <p>(boolean) Set this to true to propagate the interrupt state for a thread that has been interrupted (not clearing the interrupt state). Default value is <code>false</code> for backwards compatibility.
+ </p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Advanced usage"><!--()--></a><a name="Advanced_usage"><strong>Advanced usage</strong></a></font></td></tr><tr><td><blockquote>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JDBC interceptors"><!--()--></a><a name="JDBC_interceptors"><strong>JDBC interceptors</strong></a></font></td></tr><tr><td><blockquote>
+ <p>To see an example of how to use an interceptor, take a look at
+ <code>org.apache.tomcat.jdbc.pool.interceptor.ConnectionState</code>.
+ This simple interceptor is a cache of three attributes, transaction isolation level, auto commit and read only state,
+ in order for the system to avoid not needed roundtrips to the database.
+ </p>
+ <p>Further interceptors will be added to the core of the pool as the need arises. Contributions are always welcome!</p>
+ <p>Interceptors are of course not limited to just <code>java.sql.Connection</code> but can be used to wrap any
+ of the results from a method invokation as well. You could build query performance analyzer that provides JMX notifications when a
+ query is running longer than the expected time.</p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuring JDBC interceptors"><!--()--></a><a name="Configuring_JDBC_interceptors"><strong>Configuring JDBC interceptors</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Configuring JDBC interceptors is done using the <b>jdbcInterceptors</b> property.
+ The property contains a list of semicolon separated class names. If the
+ classname is not fully qualified it will be prefixed with the
+ <code>org.apache.tomcat.jdbc.pool.interceptor.</code> prefix.
+ </p>
+ <p>Example:<br>
+ <code>
+ jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
+ org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
+ </code>
+ <br>
+ is the same as
+ <br>
+ <code> jdbcInterceptors="ConnectionState;StatementFinalizer"</code>
+ </p>
+ <p>
+ Interceptors can have properties as well. Properties for an interceptor
+ are specified within parentheses after the class name. Several properties
+ are separated by commas.
+ </p>
+ <p>Example:<br>
+ <code>
+ jdbcInterceptors="ConnectionState;StatementFinalizer(useEquals=true)"
+ </code>
+ </p>
+ <p>
+ Extra whitespace characters around class names, property names and values
+ are ignored.
+ </p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.JdbcInterceptor"><strong>org.apache.tomcat.jdbc.pool.JdbcInterceptor</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Abstract base class for all interceptors, can not be instantiated.</p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">useEquals</code></td><td align="left" valign="center">
+ <p>(boolean) Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> and set to <code>false</code>
+ when you wish to use <code>==</code> when comparing method names.
+ The default value is <code>true</code>.
+ </p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState"><strong>org.apache.tomcat.jdbc.pool.interceptor.ConnectionState</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Caches the connection for the following attributes <code>autoCommit</code>, <code>readOnly</code>,
+ <code>transactionIsolation</code> and <code>catalog</code>.
+ It is a performance enhancement to avoid roundtrip to the database when getters are called or setters are called with an already set value.
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"><strong>org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Keeps track of all statements created using <code>createStatement</code>, <code>prepareStatement</code> or <code>prepareCall</code>
+ and closes these statements when the connection is returned to the pool.
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor"><strong>org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor</strong></a></font></td></tr><tr><td><blockquote>
+ <p>See <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=48392">48392</a>. Interceptor to wrap statements and result sets in order to prevent access to the actual connection
+ using the methods <code>ResultSet.getStatement().getConnection()</code> and <code>Statement.getConnection()</code>
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor"><strong>org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Automatically calls <code>java.sql.Statement.setQueryTimeout(seconds)</code> when a new statement is created.
+ The pool itself doesn't timeout the query, it is still up to the JDBC driver to enforce query timeouts.
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">queryTimeout</code></strong></td><td align="left" valign="center">
+ <p>(int as String) The number of seconds to set for the query timeout
+ The default value is <code>1000</code> milliseconds.
+ </p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport"><strong>org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Keeps track of query performance and issues log entries when queries exceed a time threshold of fail.
+ The log level used is <code>WARN</code>
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">threshold</code></td><td align="left" valign="center">
+ <p>(int as String) The number of milliseconds a query has to exceed before issuing a log alert.
+ The default value is <code>1000</code> milliseconds.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxQueries</code></td><td align="left" valign="center">
+ <p>(int as String) The maximum number of queries to keep track of in order to preserve memory space
+ The default value is <code>1000</code>.
+ </p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx"><strong>org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Extends the <code>SlowQueryReport</code> and in addition to log entries it issues JMX notification
+ for monitoring tools to react to. Inherits all the attributes from its parent class.
+ This class uses Tomcat's JMX engine so it wont work outside of the Tomcat container.
+ By default, JMX notifications are sent through the ConnectionPool mbean if it is enabled.
+ The <code>SlowQueryReportJmx</code> can also register an MBean if <code>notifyPool=false</code>
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">notifyPool</code></td><td align="left" valign="center">
+ <p>(boolean as String) Set to false if you want JMX notifications to go to the <code>SlowQueryReportJmx</code> MBean
+ The default value is <code>true</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">objectName</code></td><td align="left" valign="center">
+ <p>(String) Define a valid <code>javax.management.ObjectName</code> string that will be used to register this object with the platform mbean server
+ The default value is <code>null</code> and the object will be registered using
+ tomcat.jdbc:type=org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx,name=the-name-of-the-pool
+ </p>
+ </td></tr></table>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer"><strong>org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer</strong></a></font></td></tr><tr><td><blockquote>
+ <p>
+ The abandoned timer starts when a connection is checked out from the pool.
+ This means if you have a 30second timeout and run 10x10second queries using the connection
+ it will be marked abandoned and potentially reclaimed depending on the <code>abandonWhenPercentageFull</code>
+ attribute.
+ Using this interceptor it will reset the checkout timer every time you perform an operation on the connection or execute a
+ query successfully.
+ </p>
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr></table>
+ </blockquote></td></tr></table>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Code Example"><!--()--></a><a name="Code_Example"><strong>Code Example</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Plain Ol' Java"><!--()--></a><a name="Plain_Ol'_Java"><strong>Plain Ol' Java</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Here is a simple example of how to create and use a data source.</p>
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ import java.sql.Connection;
+ import java.sql.ResultSet;
+ import java.sql.Statement;
+
+ import org.apache.tomcat.jdbc.pool.DataSource;
+ import org.apache.tomcat.jdbc.pool.PoolProperties;
+
+ public class SimplePOJOExample {
+
+ public static void main(String[] args) throws Exception {
+ PoolProperties p = new PoolProperties();
+ p.setUrl("jdbc:mysql://localhost:3306/mysql");
+ p.setDriverClassName("com.mysql.jdbc.Driver");
+ p.setUsername("root");
+ p.setPassword("password");
+ p.setJmxEnabled(true);
+ p.setTestWhileIdle(false);
+ p.setTestOnBorrow(true);
+ p.setValidationQuery("SELECT 1");
+ p.setTestOnReturn(false);
+ p.setValidationInterval(30000);
+ p.setTimeBetweenEvictionRunsMillis(30000);
+ p.setMaxActive(100);
+ p.setInitialSize(10);
+ p.setMaxWait(10000);
+ p.setRemoveAbandonedTimeout(60);
+ p.setMinEvictableIdleTimeMillis(30000);
+ p.setMinIdle(10);
+ p.setLogAbandoned(true);
+ p.setRemoveAbandoned(true);
+ p.setJdbcInterceptors(
+ "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+
+ "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer");
+ DataSource datasource = new DataSource();
+ datasource.setPoolProperties(p);
+
+ Connection con = null;
+ try {
+ con = datasource.getConnection();
+ Statement st = con.createStatement();
+ ResultSet rs = st.executeQuery("select * from user");
+ int cnt = 1;
+ while (rs.next()) {
+ System.out.println((cnt++)+". Host:" +rs.getString("Host")+
+ " User:"+rs.getString("User")+" Password:"+rs.getString("Password"));
+ }
+ rs.close();
+ st.close();
+ } finally {
+ if (con!=null) try {con.close();}catch (Exception ignore) {}
+ }
+ }
+
+ }
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="As a Resource"><!--()--></a><a name="As_a_Resource"><strong>As a Resource</strong></a></font></td></tr><tr><td><blockquote>
+ <p>And here is an example on how to configure a resource for JNDI lookups</p>
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+<Resource name="jdbc/TestDB"
+ auth="Container"
+ type="javax.sql.DataSource"
+ factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
+ testWhileIdle="true"
+ testOnBorrow="true"
+ testOnReturn="false"
+ validationQuery="SELECT 1"
+ validationInterval="30000"
+ timeBetweenEvictionRunsMillis="30000"
+ maxActive="100"
+ minIdle="10"
+ maxWait="10000"
+ initialSize="10"
+ removeAbandonedTimeout="60"
+ removeAbandoned="true"
+ logAbandoned="true"
+ minEvictableIdleTimeMillis="30000"
+ jmxEnabled="true"
+ jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
+ org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
+ username="root"
+ password="password"
+ driverClassName="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://localhost:3306/mysql"/>
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Asynchronous Connection Retrieval"><!--()--></a><a name="Asynchronous_Connection_Retrieval"><strong>Asynchronous Connection Retrieval</strong></a></font></td></tr><tr><td><blockquote>
+ <p> The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the
+ pool library. It does this by adding a method to the data source called <code>Future<Connection> getConnectionAsync()</code>.
+ In order to use the async retrieval, two conditions must be met:
+ <ol>
+ <li>You must configure the <code>fairQueue</code> property to be <code>true</code>.</li>
+ <li>You will have to cast the data source to <code>org.apache.tomcat.jdbc.pool.DataSource</code></li>
+ </ol>
+ An example of using the async feature is show below.
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ Connection con = null;
+ try {
+ Future<Connection> future = datasource.getConnectionAsync();
+ while (!future.isDone()) {
+ System.out.println("Connection is not yet available. Do some background work");
+ try {
+ Thread.sleep(100); //simulate work
+ }catch (InterruptedException x) {
+ Thread.currentThread().interrupt();
+ }
+ }
+ con = future.get(); //should return instantly
+ Statement st = con.createStatement();
+ ResultSet rs = st.executeQuery("select * from user");
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Interceptors"><strong>Interceptors</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components.
+ There are many different use cases for when interceptors are useful. By default, and for performance reasons, the connection pool is stateless.
+ The only state the pool itself inserts are <code>defaultAutoCommit</code>, <code>defaultReadOnly</code>, <code>defaultTransactionIsolation</code>, <code>defaultCatalog</code> if
+ these are set. These 4 properties are only set upon connection creation. Should these properties be modified during the usage of the connection,
+ the pool itself will not reset them.</p>
+ <p>An interceptor has to extend the <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class. This class is fairly simple,
+ You will need to have a no arg constructor</p>
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ public JdbcInterceptor() {
+ }
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ <p>
+ When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ public abstract void reset(ConnectionPool parent, PooledConnection con);
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ method. This method gets called with two parameters, a reference to the connection pool itself <code>ConnectionPool parent</code>
+ and a reference to the underlying connection <code>PooledConnection con</code>.
+ </p>
+ <p>
+ When a method on the <code>java.sql.Connection</code> object is invoked, it will cause the
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ method to get invoked. The <code>Method method</code> is the actual method invoked, and <code>Object[] args</code> are the arguments.
+ To look at a very simple example, where we demonstrate how to make the invokation to <code>java.sql.Connection.close()</code> a noop
+ if the connection has been closed
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ if (CLOSE_VAL==method.getName()) {
+ if (isClosed()) return null; //noop for already closed.
+ }
+ return super.invoke(proxy,method,args);
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ There is an observation being made. It is the comparison of the method name. One way to do this would be to do
+ <code>"close".equals(method.getName())</code>.
+ Above we see a direct reference comparison between the method name and <code>static final String</code> reference.
+ According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work.
+ One could of course do this as well:
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ if (compare(CLOSE_VAL,method)) {
+ if (isClosed()) return null; //noop for already closed.
+ }
+ return super.invoke(proxy,method,args);
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ The <code>compare(String,Method)</code> will use the <code>useEquals</code> flag on an interceptor and do either reference comparison or
+ a string value comparison when the <code>useEquals=true</code> flag is set.
+ </p>
+ <p>Pool start/stop<br>
+ When the connection pool is started or closed, you can be notifed. You will only be notified once per interceptor class
+ even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool.
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ public void poolStarted(ConnectionPool pool) {
+ }
+
+ public void poolClosed(ConnectionPool pool) {
+ }
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ When overriding these methods, don't forget to call super if you are extending a class other than <code>JdbcInterceptor</code>
+ </p>
+ <p>Configuring interceptors<br>
+ Interceptors are configured using the <code>jdbcInterceptors</code> property or the <code>setJdbcInterceptors</code> method.
+ An interceptor can have properties, and would be configured like this
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ String jdbcInterceptors=
+ "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)"
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </p>
+ <p>Interceptor properties<br>
+ Since interceptors can have properties, you need to be able to read the values of these properties within your
+ interceptor. Taking an example like the one above, you can override the <code>setProperties</code> method.
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ public void setProperties(Map<String, InterceptorProperty> properties) {
+ super.setProperties(properties);
+ final String myprop = "myprop";
+ InterceptorProperty p1 = properties.get(myprop);
+ if (p1!=null) {
+ setMyprop(Long.parseLong(p1.getValue()));
+ }
+ }
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </p>
+ </blockquote></td></tr></table>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Getting the actual JDBC connection"><!--()--></a><a name="Getting_the_actual_JDBC_connection"><strong>Getting the actual JDBC connection</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Connection pools create wrappers around the actual connection in order to properly pool them.
+ We also create interceptors in these wrappers to be able to perform certain functions.
+ If there is a need to retrieve the actual connection, one can do so using the <code>javax.sql.PooledConnection</code>
+ interface.
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ Connection con = datasource.getConnection();
+ Connection actual = ((javax.sql.PooledConnection)con).getConnection();
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </p>
+ </blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building"><strong>Building</strong></a></font></td></tr><tr><td><blockquote>
+ <p>We build the JDBC pool code with 1.6, but it is backwards compatible down to 1.5 for runtime environment. For unit test, we use 1.6 and higher</p>
+ <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p>
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building from source"><!--()--></a><a name="Building_from_source"><strong>Building from source</strong></a></font></td></tr><tr><td><blockquote>
+ <p>Building is pretty simple. The pool has a dependency on <code>tomcat-juli.jar</code> and in case you want the <code>SlowQueryReportJmx</code></p>
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ javac -classpath tomcat-juli.jar \
+ -d . \
+ org/apache/tomcat/jdbc/pool/*.java \
+ org/apache/tomcat/jdbc/pool/interceptor/*.java \
+ org/apache/tomcat/jdbc/pool/jmx/*.java
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ <p>
+ A build file can be found in the Tomcat <a href="http://svn.apache.org/viewvc/tomcat/trunk/modules/jdbc-pool/">source repository</a>.
+ </p>
+ <p>
+ As a convenience, a build file is also included where a simple build command will generate all files needed.
+<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
+ ant download (downloads dependencies)
+ ant build (compiles and generates .jar files)
+ ant dist (creates a release package)
+ ant test (runs tests, expects a test database to be setup)
+</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
+ </p>
+ <p>
+ The system is structured for a Maven build, but does generate release artifacts. Just the library itself.
+ </p>
+ </blockquote></td></tr></table>
+</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This is not a Q&A section.
+ The Apache Comments System is explained
+ <a href="/tomcat-8.0-doc/comments.html">here</a>.
+ Comments should be pointed towards suggestions on improving the documentation
+ or server, and may be removed again by our moderators if they are either
+ implemented or considered invalid/off-topic.
+ Questions on how to manage Apache Tomcat should be directed
+ to our <a href="http://tomcat.apache.org/lists.html">mailing lists</a>.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
+ var comments_shortname = 'tomcat';
+ var comments_identifier = 'http://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.html';
+ (function(w, d) {
+ if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
+ d.write('<div id="comments_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.</strong><\/div>');
+ }
+ })(window, document);
+ //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/jdbc-pool.html
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org