Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / jdbc-pool.html
blob: 1f11e1adf2d1c7e102d2c12d9a5a5a6770357f1a [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - The Tomcat JDBC Connection Pool</title><meta name="author" content="Filip Hanik"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </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="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</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/index.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/introduction.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>
22<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.apache.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.StatementCache">org.apache.tomcat.jdbc.pool.interceptor.StatementCache</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>
23</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>
24
25 <p>The <strong>JDBC Connection Pool <code>org.apache.tomcat.jdbc.pool</code></strong>
26 is a replacement or an alternative to the <a href="http://commons.apache.org/dbcp/">commons-dbcp</a>
27 connection pool.</p>
28
29 <p>So why do we need a new connection pool?</p>
30
31 <p>Here are a few of the reasons:
32 <ol>
33 <li>commons-dbcp is single threaded, in order to be thread safe commons-dbcp locks the entire pool, even during query validation.</li>
34 <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
35 Even with the enormous optimizations of the <code>synchronized</code> statement in Java 6, commons-dbcp still suffers in speed and concurrency.</li>
36 <li>commons-dbcp is complex, over 60 classes. tomcat-jdbc-pool, core is 8 classes, hence modifications for future requirement will require
37 much less changes. This is all you need to run the connection pool itself, the rest is gravy.</li>
38 <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
39 <code>NoSuchMethodException</code> for all the methods not implemented, even if the driver supports it. </li>
40 <li>The commons-dbcp has become fairly stagnant. Sparse updates, releases, and new feature support.</li>
41 <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>
42 <li>Tomcat jdbc pool implements a fairness option not available in commons-dbcp and still performs faster than commons-dbcp</li>
43 <li>Tomcat jdbc pool implements the ability retrieve a connection asynchronously, without adding additional threads to the library itself</li>
44 <li>Tomcat jdbc pool is a Tomcat module, it depends on Tomcat JULI, a simplified logging framework used in Tomcat.</li>
45 <li>Retrieve the underlying connection using the <code>javax.sql.PooledConnection</code> interface.</li>
46 <li>Starvation proof. If a pool is empty, and threads are waiting for a connection, when a connection is returned,
47 the pool will awake the correct thread waiting. Most pools will simply starve.</li>
48 </ol>
49 </p>
50
51 <p>Features added over other connection pool implementations
52 <ol>
53 <li>Support for highly concurrent environments and multi core/cpu systems.</li>
54 <li>Dynamic implementation of interface, will support <code>java.sql</code> and <code>javax.sql</code> interfaces for
55 your runtime environment (as long as your JDBC driver does the same), even when compiled with a lower version of the JDK.</li>
56 <li>Validation intervals - we don't have to validate every single time we use the connection, we can do this
57 when we borrow or return the connection, just not more frequent than an interval we can configure.</li>
58 <li>Run-Once query, a configurable query that will be run only once, when the connection to the database is established.
59 Very useful to setup session settings, that you want to exist during the entire time the connection is established.</li>
60 <li>Ability to configure custom interceptors.
61 This allows you to write custom interceptors to enhance the functionality. You can use interceptors to gather query stats,
62 cache session states, reconnect the connection upon failures, retry queries, cache query results, and so on.
63 Your options are endless and the interceptors are dynamic, not tied to a JDK version of a
64 <code>java.sql</code>/<code>javax.sql</code> interface.</li>
65 <li>High performance - we will show some differences in performance later on</li>
66 <li>Extremely simple, due to the very simplified implementation, the line count and source file count are very low, compare with c3p0
67 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
68 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>
69 <li>Asynchronous connection retrieval - you can queue your request for a connection and receive a <code>Future&lt;Connection&gt;</code> back.</li>
70 <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>
71 <li>You can decide at what moment connections are considered abandoned, is it when the pool is full, or directly at a timeout
72 by specifying a pool usage threshold.
73 </li>
74 <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.
75 This is achieved using the <code>ResetAbandonedTimer</code>
76 </li>
77 <li>Close connections after they have been connected for a certain time. Age based close upon return to the pool.
78 </li>
79 <li>Get JMX notifications and log entries when connections are suspected for being abandoned. This is similar to
80 the <code>removeAbandonedTimeout</code> but it doesn't take any action, only reports the information.
81 This is achieved using the <code>suspectTimeout</code> attribute.</li>
82 <li>Connections can be retrieved from a <code>java.sql.Driver</code>, <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code>
83 This is achieved using the <code>dataSource</code> and <code>dataSourceJNDI</code> attributes.</li>
84 <li>XA connection support</li>
85 </ol>
86 </p>
87
88
89</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>
90 <p>
91 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
92 transition will be very simple. Moving from other connection pools is also fairly straight forward.
93 </p>
94 <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>
95 <p>The Tomcat connection pool offers a few additional features over what most other pools let you do:</p>
96 <ul>
97 <li><code>initSQL</code> - the ability to run a SQL statement exactly once, when the connection is created</li>
98 <li><code>validationInterval</code> - in addition to running validations on connections, avoid running them too frequently.</li>
99 <li><code>jdbcInterceptors</code> - flexible and pluggable interceptors to create any customizations around the pool,
100 the query execution and the result set handling. More on this in the advanced section.</li>
101 <li><code>fairQueue</code> - Set the fair flag to true to achieve thread fairness or to use asynchronous connection retrieval</li>
102 </ul>
103 </blockquote></td></tr></table>
104 <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>
105 <p>
106 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>
107 With the only difference being that you have to specify the <code>factory</code> attribute and set the value to
108 <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code>
109 </p>
110 </blockquote></td></tr></table>
111 <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>
112 <p>
113 The connection pool only has another dependency, and that is on tomcat-juli.jar.
114 To configure the pool in a stand alone project using bean instantiation, the bean to instantiate is
115 <code>org.apache.tomcat.jdbc.pool.DataSource</code>. The same attributes (documented below) as you use to configure a connection
116 pool as a JNDI resource, are used to configure a data source as a bean.
117 </p>
118 </blockquote></td></tr></table>
119 <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>
120 <p>
121 The connection pool object exposes an MBean that can be registered.
122 In order for the connection pool object to create the MBean, the flag <code>jmxEnabled</code> has to be set to true.
123 This doesn't imply that the pool will be registered with an MBean server, merely that the MBean is created.
124 In a container like Tomcat, Tomcat itself registers the DataSource with the MBean server, the
125 <code>org.apache.tomcat.jdbc.pool.DataSource</code> object will then register the actual
126 connection pool MBean.
127 If you're running outside of a container, you can register the DataSource yourself under any object name you specify,
128 and it propagates the registration to the underlying pool. To do this you would call <code>mBeanServer.registerMBean(dataSource.getPool().getJmxPool(),objectname)</code>.
129 Prior to this call, ensure that the pool has been created by calling <code>dataSource.createPool()</code>.
130 </p>
131 </blockquote></td></tr></table>
132
133</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>
134 <p>To provide a very simple switch to and from commons-dbcp and tomcat-jdbc-pool,
135 Most attributes are the same and have the same meaning.</p>
136 <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>
137 <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">
138 <p>factory is required, and the value should be <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code></p>
139 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">type</code></strong></td><td align="left" valign="center">
140 <p>Type should always be <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code></p>
141 <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>
142 </td></tr></table>
143 </blockquote></td></tr></table>
144
145 <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>
146 <p>These attributes are shared between commons-dbcp and tomcat-jdbc-pool, in some cases default values are different.</p>
147 <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">
148 <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>
149 </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultReadOnly</code></td><td align="left" valign="center">
150 <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>
151 </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultTransactionIsolation</code></td><td align="left" valign="center">
152 <p>(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )
153 <ul>
154 <li><code>NONE</code></li>
155 <li><code>READ_COMMITTED</code></li>
156 <li><code>READ_UNCOMMITTED</code></li>
157 <li><code>REPEATABLE_READ</code></li>
158 <li><code>SERIALIZABLE</code></li>
159 </ul>
160 If not set, the method will not be called and it defaults to the JDBC driver.
161 </p>
162 </td></tr><tr><td align="left" valign="center"><code class="attributeName">defaultCatalog</code></td><td align="left" valign="center">
163 <p>(String) The default catalog of connections created by this pool.</p>
164 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverClassName</code></strong></td><td align="left" valign="center">
165 <p>(String) The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible
166 from the same classloader as tomcat-jdbc.jar
167 </p>
168 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">username</code></strong></td><td align="left" valign="center">
169 <p>(String) The connection username to be passed to our JDBC driver to establish a connection.
170 Note that method <code>DataSource.getConnection(username,password)</code>
171 by default will not use credentials passed into the method,
172 but will use the ones configured here. See <code>alternateUsernameAllowed</code>
173 property for more details.
174 </p>
175 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">password</code></strong></td><td align="left" valign="center">
176 <p>(String) The connection password to be passed to our JDBC driver to establish a connection.
177 Note that method <code>DataSource.getConnection(username,password)</code>
178 by default will not use credentials passed into the method,
179 but will use the ones configured here. See <code>alternateUsernameAllowed</code>
180 property for more details.
181 </p>
182 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxActive</code></td><td align="left" valign="center">
183 <p>(int) The maximum number of active connections that can be allocated from this pool at the same time.
184 The default value is <code>100</code></p>
185 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxIdle</code></td><td align="left" valign="center">
186 <p>(int) The maximum number of connections that should be kept in the pool at all times.
187 Default value is <code>maxActive</code>:<code>100</code>
188 Idle connections are checked periodically (if enabled) and
189 connections that been idle for longer than <code>minEvictableIdleTimeMillis</code>
190 will be released. (also see <code>testWhileIdle</code>)</p>
191 </td></tr><tr><td align="left" valign="center"><code class="attributeName">minIdle</code></td><td align="left" valign="center">
192 <p>
193 (int) The minimum number of established connections that should be kept in the pool at all times.
194 The connection pool can shrink below this number if validation queries fail.
195 Default value is derived from <code>initialSize</code>:<code>10</code> (also see <code>testWhileIdle</code>)
196 </p>
197 </td></tr><tr><td align="left" valign="center"><code class="attributeName">initialSize</code></td><td align="left" valign="center">
198 <p>(int)The initial number of connections that are created when the pool is started.
199 Default value is <code>10</code></p>
200 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxWait</code></td><td align="left" valign="center">
201 <p>(int) The maximum number of milliseconds that the pool will wait (when there are no available connections)
202 for a connection to be returned before throwing an exception.
203 Default value is <code>30000</code> (30 seconds)</p>
204 </td></tr><tr><td align="left" valign="center"><code class="attributeName">testOnBorrow</code></td><td align="left" valign="center">
205 <p>(boolean) The indication of whether objects will be validated before being borrowed from the pool.
206 If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
207 NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
208 In order to have a more efficient validation, see <code>validationInterval</code>.
209 Default value is <code>false</code>
210 </p>
211 </td></tr><tr><td align="left" valign="center"><code class="attributeName">testOnReturn</code></td><td align="left" valign="center">
212 <p>(boolean) The indication of whether objects will be validated before being returned to the pool.
213 NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
214 The default value is <code>false</code>.
215 </p>
216 </td></tr><tr><td align="left" valign="center"><code class="attributeName">testWhileIdle</code></td><td align="left" valign="center">
217 <p>(boolean) The indication of whether objects will be validated by the idle object evictor (if any).
218 If an object fails to validate, it will be dropped from the pool.
219 NOTE - for a true value to have any effect, the <code>validationQuery</code> parameter must be set to a non-null string.
220 The default value is <code>false</code> and this property has to be set in order for the
221 pool cleaner/test thread is to run (also see <code>timeBetweenEvictionRunsMillis</code>)
222 </p>
223 </td></tr><tr><td align="left" valign="center"><code class="attributeName">validationQuery</code></td><td align="left" valign="center">
224 <p>(String) The SQL query that will be used to validate connections from this pool before returning them to the caller.
225 If specified, this query does not have to return any data, it just can't throw a <code>SQLException</code>.
226 The default value is <code>null</code>.
227 Example values are <code>SELECT 1</code>(mysql), <code>select 1 from dual</code>(oracle), <code>SELECT 1</code>(MS Sql Server)
228 </p>
229 </td></tr><tr><td align="left" valign="center"><code class="attributeName">validatorClassName</code></td><td align="left" valign="center">
230 <p>(String) The name of a class which implements the
231 <code>org.apache.tomcat.jdbc.pool.Validator</code> interface and
232 provides a no-arg constructor (may be implicit). If specified, the
233 class will be used to create a Validator instance which is then used
234 instead of any validation query to validate connections. The default
235 value is <code>null</code>. An example value is
236 <code>com.mycompany.project.SimpleValidator</code>.
237 </p>
238 </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeBetweenEvictionRunsMillis</code></td><td align="left" valign="center">
239 <p>(int) The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread.
240 This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often
241 we validate idle connections.
242 The default value is <code>5000</code> (5 seconds). <br>
243 </p>
244 </td></tr><tr><td align="left" valign="center"><code class="attributeName">numTestsPerEvictionRun</code></td><td align="left" valign="center">
245 <p>(int) Property not used in tomcat-jdbc-pool.</p>
246 </td></tr><tr><td align="left" valign="center"><code class="attributeName">minEvictableIdleTimeMillis</code></td><td align="left" valign="center">
247 <p>(int) The minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
248 The default value is <code>60000</code> (60 seconds).</p>
249 </td></tr><tr><td align="left" valign="center"><code class="attributeName">accessToUnderlyingConnectionAllowed</code></td><td align="left" valign="center">
250 <p>(boolean) Property not used. Access can be achieved by calling <code>unwrap</code> on the pooled connection.
251 see <code>javax.sql.DataSource</code> interface, or call <code>getConnection</code> through reflection or
252 cast the object as <code>javax.sql.PooledConnection</code></p>
253 </td></tr><tr><td align="left" valign="center"><code class="attributeName">removeAbandoned</code></td><td align="left" valign="center">
254 <p>(boolean) Flag to remove abandoned connections if they exceed the <code>removeAbandonedTimeout</code>.
255 If set to true a connection is considered abandoned and eligible for removal if it has been in use
256 longer than the <code>removeAbandonedTimeout</code> Setting this to <code>true</code> can recover db connections from
257 applications that fail to close a connection. See also <code>logAbandoned</code>
258 The default value is <code>false</code>.</p>
259 </td></tr><tr><td align="left" valign="center"><code class="attributeName">removeAbandonedTimeout</code></td><td align="left" valign="center">
260 <p>(int) Timeout in seconds before an abandoned(in use) connection can be removed.
261 The default value is <code>60</code> (60 seconds). The value should be set to the longest running query your applications
262 might have.</p>
263 </td></tr><tr><td align="left" valign="center"><code class="attributeName">logAbandoned</code></td><td align="left" valign="center">
264 <p>(boolean) Flag to log stack traces for application code which abandoned a Connection.
265 Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
266 The default value is <code>false</code>.</p>
267 </td></tr><tr><td align="left" valign="center"><code class="attributeName">connectionProperties</code></td><td align="left" valign="center">
268 <p>(String) The connection properties that will be sent to our JDBC driver when establishing new connections.
269 Format of the string must be [propertyName=property;]*
270 NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
271 The default value is <code>null</code>.</p>
272 </td></tr><tr><td align="left" valign="center"><code class="attributeName">poolPreparedStatements</code></td><td align="left" valign="center">
273 <p>(boolean) Property not used.</p>
274 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxOpenPreparedStatements</code></td><td align="left" valign="center">
275 <p>(int) Property not used.</p>
276 </td></tr></table>
277
278 </blockquote></td></tr></table>
279
280 <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>
281
282 <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">
283 <p>(String) A custom query to be run when a connection is first created.
284 The default value is <code>null</code>.</p>
285 </td></tr><tr><td align="left" valign="center"><code class="attributeName">jdbcInterceptors</code></td><td align="left" valign="center">
286 <p>(String) A semicolon separated list of classnames extending
287 <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class.
288 See <a href="#Configuring_JDBC_interceptors">Configuring JDBC interceptors</a>
289 below for more detailed description of syntaz and examples.
290 </p>
291 <p>
292 These interceptors will be inserted as an interceptor into the chain
293 of operations on a <code>java.sql.Connection</code> object.
294 The default value is <code>null</code>.
295 </p>
296 <p>
297 Predefined interceptors:<br>
298 <code>org.apache.tomcat.jdbc.pool.interceptor.<br>ConnectionState</code>
299 - keeps track of auto commit, read only, catalog and transaction isolation level.<br>
300 <code>org.apache.tomcat.jdbc.pool.interceptor.<br>StatementFinalizer</code>
301 - keeps track of opened statements, and closes them when the connection is returned to the pool.
302 </p>
303 <p>
304 More predefined interceptors are described in detail in the
305 <a href="#JDBC_interceptors">JDBC Interceptors section</a>.
306 </p>
307 </td></tr><tr><td align="left" valign="center"><code class="attributeName">validationInterval</code></td><td align="left" valign="center">
308 <p>(long) avoid excess validation, only run validation at most at this frequency - time in milliseconds.
309 If a connection is due for validation, but has been validated previously within this interval, it will not be validated again.
310 The default value is <code>30000</code> (30 seconds).</p>
311 </td></tr><tr><td align="left" valign="center"><code class="attributeName">jmxEnabled</code></td><td align="left" valign="center">
312 <p>(boolean) Register the pool with JMX or not.
313 The default value is <code>true</code>.</p>
314 </td></tr><tr><td align="left" valign="center"><code class="attributeName">fairQueue</code></td><td align="left" valign="center">
315 <p>(boolean) Set to true if you wish that calls to getConnection should be treated
316 fairly in a true FIFO fashion. This uses the <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue</code>
317 implementation for the list of the idle connections. The default value is <code>true</code>.
318 This flag is required when you want to use asynchronous connection retrieval.<br>
319 Setting this flag ensures that threads receive connections in the order they arrive.<br>
320 During performance tests, there is a very large difference in how locks
321 and lock waiting is implemented. When <code>fairQueue=true</code>
322 there is a decision making process based on what operating system the system is running.
323 If the system is running on Linux (property <code>os.name=Linux</code>.
324 To disable this Linux specific behavior and still use the fair queue, simply add the property
325 <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true</code> to your system properties
326 before the connection pool classes are loaded.
327 </p>
328 </td></tr><tr><td align="left" valign="center"><code class="attributeName">abandonWhenPercentageFull</code></td><td align="left" valign="center">
329 <p>(int) Connections that have been abandoned (timed out) wont get closed and reported up unless
330 the number of connections in use are above the percentage defined by <code>abandonWhenPercentageFull</code>.
331 The value should be between 0-100.
332 The default value is <code>0</code>, which implies that connections are eligible for closure as soon
333 as <code>removeAbandonedTimeout</code> has been reached.</p>
334 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxAge</code></td><td align="left" valign="center">
335 <p>(long) Time in milliseconds to keep this connection. When a connection is returned to the pool,
336 the pool will check to see if the <code>now - time-when-connected &gt; maxAge</code> has been reached,
337 and if so, it closes the connection rather than returning it to the pool.
338 The default value is <code>0</code>, which implies that connections will be left open and no age check
339 will be done upon returning the connection to the pool.</p>
340 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useEquals</code></td><td align="left" valign="center">
341 <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>
342 when you wish to use <code>==</code> when comparing method names. This property does not apply to added interceptors as those are configured individually.
343 The default value is <code>true</code>.
344 </p>
345 </td></tr><tr><td align="left" valign="center"><code class="attributeName">suspectTimeout</code></td><td align="left" valign="center">
346 <p>(int) Timeout value in seconds. Default value is <code>0</code>.<br>
347 Similar to to the <code>removeAbandonedTimeout</code> value but instead of treating the connection
348 as abandoned, and potentially closing the connection, this simply logs the warning if
349 <code>logAbandoned</code> is set to true. If this value is equal or less than 0, no suspect
350 checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
351 the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
352 logged and a JMX notification gets sent once.
353 </p>
354 </td></tr><tr><td align="left" valign="center"><code class="attributeName">rollbackOnReturn</code></td><td align="left" valign="center">
355 <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
356 Default value is <code>false</code>.<br>
357 </p>
358 </td></tr><tr><td align="left" valign="center"><code class="attributeName">commitOnReturn</code></td><td align="left" valign="center">
359 <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
360 If <code>rollbackOnReturn==true</code> then this attribute is ignored.
361 Default value is <code>false</code>.<br>
362 </p>
363 </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateUsernameAllowed</code></td><td align="left" valign="center">
364 <p>(boolean) By default, the jdbc-pool will ignore the
365 <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>
366 call, and simply return a previously pooled connection under the globally configured properties <code>username</code> and <code>password</code>, for performance reasons.
367 </p>
368 <p>
369 The pool can however be configured to allow use of different credentials
370 each time a connection is requested. To enable the functionality described in the
371 <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>
372 call, simply set the property <code>alternateUsernameAllowed</code>
373 to <code>true</code>.<br>
374 Should you request a connection with the credentials user1/password1 and the connection
375 was previously connected using different user2/password2, the connection will be closed,
376 and reopened with the requested credentials. This way, the pool size is still managed
377 on a global level, and not on a per schema level. <br>
378 The default value is <code>false</code>.<br>
379 This property was added as an enhancement to <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=50025">bug 50025</a>.
380 </p>
381 </td></tr><tr><td align="left" valign="center"><code class="attributeName">dataSource</code></td><td align="left" valign="center">
382 <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.
383 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>
384 </p>
385 </td></tr><tr><td align="left" valign="center"><code class="attributeName">dataSourceJNDI</code></td><td align="left" valign="center">
386 <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>
387 </p>
388 </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDisposableConnectionFacade</code></td><td align="left" valign="center">
389 <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
390 reference of a connection it has already called closed on, to execute queries on it. Default value is <code>true</code>.
391 </p>
392 </td></tr><tr><td align="left" valign="center"><code class="attributeName">logValidationErrors</code></td><td align="left" valign="center">
393 <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.
394 </p>
395 </td></tr><tr><td align="left" valign="center"><code class="attributeName">propagateInterruptState</code></td><td align="left" valign="center">
396 <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.
397 </p>
398 </td></tr></table>
399 </blockquote></td></tr></table>
400</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>
401 <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>
402 <p>To see an example of how to use an interceptor, take a look at
403 <code>org.apache.tomcat.jdbc.pool.interceptor.ConnectionState</code>.
404 This simple interceptor is a cache of three attributes, transaction isolation level, auto commit and read only state,
405 in order for the system to avoid not needed roundtrips to the database.
406 </p>
407 <p>Further interceptors will be added to the core of the pool as the need arises. Contributions are always welcome!</p>
408 <p>Interceptors are of course not limited to just <code>java.sql.Connection</code> but can be used to wrap any
409 of the results from a method invokation as well. You could build query performance analyzer that provides JMX notifications when a
410 query is running longer than the expected time.</p>
411 </blockquote></td></tr></table>
412 <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>
413 <p>Configuring JDBC interceptors is done using the <b>jdbcInterceptors</b> property.
414 The property contains a list of semicolon separated class names. If the
415 classname is not fully qualified it will be prefixed with the
416 <code>org.apache.tomcat.jdbc.pool.interceptor.</code> prefix.
417 </p>
418 <p>Example:<br>
419 <code>
420 jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
421 org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
422 </code>
423 <br>
424 is the same as
425 <br>
426 <code> jdbcInterceptors="ConnectionState;StatementFinalizer"</code>
427 </p>
428 <p>
429 Interceptors can have properties as well. Properties for an interceptor
430 are specified within parentheses after the class name. Several properties
431 are separated by commas.
432 </p>
433 <p>Example:<br>
434 <code>
435 jdbcInterceptors="ConnectionState;StatementFinalizer(useEquals=true)"
436 </code>
437 </p>
438 <p>
439 Extra whitespace characters around class names, property names and values
440 are ignored.
441 </p>
442 </blockquote></td></tr></table>
443 <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>
444 <p>Abstract base class for all interceptors, can not be instantiated.</p>
445 <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">
446 <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>
447 when you wish to use <code>==</code> when comparing method names.
448 The default value is <code>true</code>.
449 </p>
450 </td></tr></table>
451 </blockquote></td></tr></table>
452 <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>
453 <p>Caches the connection for the following attributes <code>autoCommit</code>, <code>readOnly</code>,
454 <code>transactionIsolation</code> and <code>catalog</code>.
455 It is a performance enhancement to avoid roundtrip to the database when getters are called or setters are called with an already set value.
456 </p>
457 <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>
458 </blockquote></td></tr></table>
459 <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>
460 <p>Keeps track of all statements created using <code>createStatement</code>, <code>prepareStatement</code> or <code>prepareCall</code>
461 and closes these statements when the connection is returned to the pool.
462 </p>
463 <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>
464 </blockquote></td></tr></table>
465 <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.StatementCache"><strong>org.apache.tomcat.jdbc.pool.interceptor.StatementCache</strong></a></font></td></tr><tr><td><blockquote>
466 <p>Caches <code>PreparedStatement</code> and/or <code>CallableStatement</code>
467 instances on a connection.
468 </p>
469 <p>The statements are cached per connection.
470 The count limit is counted globally for all connections that belong to
471 the same pool. Once the count reaches <code>max</code>, subsequent
472 statements are not returned to the cache and are closed immediately.
473 </p>
474 <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">prepared</code></td><td align="left" valign="center">
475 <p>(boolean as String) Enable caching of <code>PreparedStatement</code>
476 instances created using <code>prepareStatement</code> calls.
477 The default value is <code>true</code>.
478 </p>
479 </td></tr><tr><td align="left" valign="center"><code class="attributeName">callable</code></td><td align="left" valign="center">
480 <p>(boolean as String) Enable caching of <code>CallableStatement</code>
481 instances created using <code>prepareCall</code> calls.
482 The default value is <code>false</code>.
483 </p>
484 </td></tr><tr><td align="left" valign="center"><code class="attributeName">max</code></td><td align="left" valign="center">
485 <p>(int as String) Limit on the count of cached statements across
486 the connection pool.
487 The default value is <code>50</code>.
488 </p>
489 </td></tr></table>
490 </blockquote></td></tr></table>
491 <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>
492 <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
493 using the methods <code>ResultSet.getStatement().getConnection()</code> and <code>Statement.getConnection()</code>
494 </p>
495 <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>
496 </blockquote></td></tr></table>
497 <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>
498 <p>Automatically calls <code>java.sql.Statement.setQueryTimeout(seconds)</code> when a new statement is created.
499 The pool itself doesn't timeout the query, it is still up to the JDBC driver to enforce query timeouts.
500 </p>
501 <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">
502 <p>(int as String) The number of seconds to set for the query timeout
503 The default value is <code>1000</code> milliseconds.
504 </p>
505 </td></tr></table>
506 </blockquote></td></tr></table>
507 <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>
508 <p>Keeps track of query performance and issues log entries when queries exceed a time threshold of fail.
509 The log level used is <code>WARN</code>
510 </p>
511 <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">
512 <p>(int as String) The number of milliseconds a query has to exceed before issuing a log alert.
513 The default value is <code>1000</code> milliseconds.
514 </p>
515 </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxQueries</code></td><td align="left" valign="center">
516 <p>(int as String) The maximum number of queries to keep track of in order to preserve memory space
517 The default value is <code>1000</code>.
518 </p>
519 </td></tr></table>
520 </blockquote></td></tr></table>
521 <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>
522 <p>Extends the <code>SlowQueryReport</code> and in addition to log entries it issues JMX notification
523 for monitoring tools to react to. Inherits all the attributes from its parent class.
524 This class uses Tomcat's JMX engine so it wont work outside of the Tomcat container.
525 By default, JMX notifications are sent through the ConnectionPool mbean if it is enabled.
526 The <code>SlowQueryReportJmx</code> can also register an MBean if <code>notifyPool=false</code>
527 </p>
528 <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">
529 <p>(boolean as String) Set to false if you want JMX notifications to go to the <code>SlowQueryReportJmx</code> MBean
530 The default value is <code>true</code>.
531 </p>
532 </td></tr><tr><td align="left" valign="center"><code class="attributeName">objectName</code></td><td align="left" valign="center">
533 <p>(String) Define a valid <code>javax.management.ObjectName</code> string that will be used to register this object with the platform mbean server
534 The default value is <code>null</code> and the object will be registered using
535 tomcat.jdbc:type=org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx,name=the-name-of-the-pool
536 </p>
537 </td></tr></table>
538 </blockquote></td></tr></table>
539 <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>
540 <p>
541 The abandoned timer starts when a connection is checked out from the pool.
542 This means if you have a 30second timeout and run 10x10second queries using the connection
543 it will be marked abandoned and potentially reclaimed depending on the <code>abandonWhenPercentageFull</code>
544 attribute.
545 Using this interceptor it will reset the checkout timer every time you perform an operation on the connection or execute a
546 query successfully.
547 </p>
548 <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>
549 </blockquote></td></tr></table>
550</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>
551 <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>
552 <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>
553 <p>Here is a simple example of how to create and use a data source.</p>
554<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>
555 import java.sql.Connection;
556 import java.sql.ResultSet;
557 import java.sql.Statement;
558
559 import org.apache.tomcat.jdbc.pool.DataSource;
560 import org.apache.tomcat.jdbc.pool.PoolProperties;
561
562 public class SimplePOJOExample {
563
564 public static void main(String[] args) throws Exception {
565 PoolProperties p = new PoolProperties();
566 p.setUrl("jdbc:mysql://localhost:3306/mysql");
567 p.setDriverClassName("com.mysql.jdbc.Driver");
568 p.setUsername("root");
569 p.setPassword("password");
570 p.setJmxEnabled(true);
571 p.setTestWhileIdle(false);
572 p.setTestOnBorrow(true);
573 p.setValidationQuery("SELECT 1");
574 p.setTestOnReturn(false);
575 p.setValidationInterval(30000);
576 p.setTimeBetweenEvictionRunsMillis(30000);
577 p.setMaxActive(100);
578 p.setInitialSize(10);
579 p.setMaxWait(10000);
580 p.setRemoveAbandonedTimeout(60);
581 p.setMinEvictableIdleTimeMillis(30000);
582 p.setMinIdle(10);
583 p.setLogAbandoned(true);
584 p.setRemoveAbandoned(true);
585 p.setJdbcInterceptors(
586 "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+
587 "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer");
588 DataSource datasource = new DataSource();
589 datasource.setPoolProperties(p);
590
591 Connection con = null;
592 try {
593 con = datasource.getConnection();
594 Statement st = con.createStatement();
595 ResultSet rs = st.executeQuery("select * from user");
596 int cnt = 1;
597 while (rs.next()) {
598 System.out.println((cnt++)+". Host:" +rs.getString("Host")+
599 " User:"+rs.getString("User")+" Password:"+rs.getString("Password"));
600 }
601 rs.close();
602 st.close();
603 } finally {
604 if (con!=null) try {con.close();}catch (Exception ignore) {}
605 }
606 }
607
608 }
609</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>
610 </blockquote></td></tr></table>
611 <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>
612 <p>And here is an example on how to configure a resource for JNDI lookups</p>
613<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>
614&lt;Resource name="jdbc/TestDB"
615 auth="Container"
616 type="javax.sql.DataSource"
617 factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
618 testWhileIdle="true"
619 testOnBorrow="true"
620 testOnReturn="false"
621 validationQuery="SELECT 1"
622 validationInterval="30000"
623 timeBetweenEvictionRunsMillis="30000"
624 maxActive="100"
625 minIdle="10"
626 maxWait="10000"
627 initialSize="10"
628 removeAbandonedTimeout="60"
629 removeAbandoned="true"
630 logAbandoned="true"
631 minEvictableIdleTimeMillis="30000"
632 jmxEnabled="true"
633 jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
634 org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
635 username="root"
636 password="password"
637 driverClassName="com.mysql.jdbc.Driver"
638 url="jdbc:mysql://localhost:3306/mysql"/&gt;
639</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>
640
641 </blockquote></td></tr></table>
642 <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>
643 <p> The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the
644 pool library. It does this by adding a method to the data source called <code>Future&lt;Connection&gt; getConnectionAsync()</code>.
645 In order to use the async retrieval, two conditions must be met:
646 <ol>
647 <li>You must configure the <code>fairQueue</code> property to be <code>true</code>.</li>
648 <li>You will have to cast the data source to <code>org.apache.tomcat.jdbc.pool.DataSource</code></li>
649 </ol>
650 An example of using the async feature is show below.
651<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>
652 Connection con = null;
653 try {
654 Future&lt;Connection&gt; future = datasource.getConnectionAsync();
655 while (!future.isDone()) {
656 System.out.println("Connection is not yet available. Do some background work");
657 try {
658 Thread.sleep(100); //simulate work
659 }catch (InterruptedException x) {
660 Thread.currentThread().interrupt();
661 }
662 }
663 con = future.get(); //should return instantly
664 Statement st = con.createStatement();
665 ResultSet rs = st.executeQuery("select * from user");
666</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>
667 </p>
668 </blockquote></td></tr></table>
669 <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>
670 <p>Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components.
671 There are many different use cases for when interceptors are useful. By default, and for performance reasons, the connection pool is stateless.
672 The only state the pool itself inserts are <code>defaultAutoCommit</code>, <code>defaultReadOnly</code>, <code>defaultTransactionIsolation</code>, <code>defaultCatalog</code> if
673 these are set. These 4 properties are only set upon connection creation. Should these properties be modified during the usage of the connection,
674 the pool itself will not reset them.</p>
675 <p>An interceptor has to extend the <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class. This class is fairly simple,
676 You will need to have a no arg constructor</p>
677<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>
678 public JdbcInterceptor() {
679 }
680</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>
681 <p>
682 When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the
683<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>
684 public abstract void reset(ConnectionPool parent, PooledConnection con);
685</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>
686 method. This method gets called with two parameters, a reference to the connection pool itself <code>ConnectionPool parent</code>
687 and a reference to the underlying connection <code>PooledConnection con</code>.
688 </p>
689 <p>
690 When a method on the <code>java.sql.Connection</code> object is invoked, it will cause the
691<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>
692 public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
693</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>
694 method to get invoked. The <code>Method method</code> is the actual method invoked, and <code>Object[] args</code> are the arguments.
695 To look at a very simple example, where we demonstrate how to make the invokation to <code>java.sql.Connection.close()</code> a noop
696 if the connection has been closed
697<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>
698 if (CLOSE_VAL==method.getName()) {
699 if (isClosed()) return null; //noop for already closed.
700 }
701 return super.invoke(proxy,method,args);
702</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>
703 There is an observation being made. It is the comparison of the method name. One way to do this would be to do
704 <code>"close".equals(method.getName())</code>.
705 Above we see a direct reference comparison between the method name and <code>static final String</code> reference.
706 According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work.
707 One could of course do this as well:
708<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>
709 if (compare(CLOSE_VAL,method)) {
710 if (isClosed()) return null; //noop for already closed.
711 }
712 return super.invoke(proxy,method,args);
713</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>
714 The <code>compare(String,Method)</code> will use the <code>useEquals</code> flag on an interceptor and do either reference comparison or
715 a string value comparison when the <code>useEquals=true</code> flag is set.
716 </p>
717 <p>Pool start/stop<br>
718 When the connection pool is started or closed, you can be notifed. You will only be notified once per interceptor class
719 even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool.
720<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>
721 public void poolStarted(ConnectionPool pool) {
722 }
723
724 public void poolClosed(ConnectionPool pool) {
725 }
726</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>
727 When overriding these methods, don't forget to call super if you are extending a class other than <code>JdbcInterceptor</code>
728 </p>
729 <p>Configuring interceptors<br>
730 Interceptors are configured using the <code>jdbcInterceptors</code> property or the <code>setJdbcInterceptors</code> method.
731 An interceptor can have properties, and would be configured like this
732<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>
733 String jdbcInterceptors=
734 "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)"
735</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>
736 </p>
737 <p>Interceptor properties<br>
738 Since interceptors can have properties, you need to be able to read the values of these properties within your
739 interceptor. Taking an example like the one above, you can override the <code>setProperties</code> method.
740<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>
741 public void setProperties(Map&lt;String, InterceptorProperty&gt; properties) {
742 super.setProperties(properties);
743 final String myprop = "myprop";
744 InterceptorProperty p1 = properties.get(myprop);
745 if (p1!=null) {
746 setMyprop(Long.parseLong(p1.getValue()));
747 }
748 }
749</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>
750 </p>
751 </blockquote></td></tr></table>
752 <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>
753 <p>Connection pools create wrappers around the actual connection in order to properly pool them.
754 We also create interceptors in these wrappers to be able to perform certain functions.
755 If there is a need to retrieve the actual connection, one can do so using the <code>javax.sql.PooledConnection</code>
756 interface.
757<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>
758 Connection con = datasource.getConnection();
759 Connection actual = ((javax.sql.PooledConnection)con).getConnection();
760</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>
761 </p>
762 </blockquote></td></tr></table>
763
764</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>
765 <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>
766 <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>
767 <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>
768 <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>
769<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>
770 javac -classpath tomcat-juli.jar \
771 -d . \
772 org/apache/tomcat/jdbc/pool/*.java \
773 org/apache/tomcat/jdbc/pool/interceptor/*.java \
774 org/apache/tomcat/jdbc/pool/jmx/*.java
775</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>
776 <p>
777 A build file can be found in the Tomcat <a href="http://svn.apache.org/viewvc/tomcat/trunk/modules/jdbc-pool/">source repository</a>.
778 </p>
779 <p>
780 As a convenience, a build file is also included where a simple build command will generate all files needed.
781<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>
782 ant download (downloads dependencies)
783 ant build (compiles and generates .jar files)
784 ant dist (creates a release package)
785 ant test (runs tests, expects a test database to be setup)
786</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>
787 </p>
788 <p>
789 The system is structured for a Maven build, but does generate release artifacts. Just the library itself.
790 </p>
791 </blockquote></td></tr></table>
792</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 comments section collects your suggestions
793 on improving documentation for Apache Tomcat.<br><br>
794 If you have trouble and need help, read
795 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
796 and ask your question on the tomcat-users
797 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
798 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
799 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
800 Comments may be removed by our moderators if they are either
801 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
802 var comments_shortname = 'tomcat';
803 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html';
804 (function(w, d) {
805 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
806 d.write('<div id="comments_thread"><\/div>');
807 var s = d.createElement('script');
808 s.type = 'text/javascript';
809 s.async = true;
810 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
811 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
812 }
813 else {
814 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
815 }
816 })(window, document);
817 //--><!]]></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>
818 Copyright &copy; 1999-2013, Apache Software Foundation
819 </em></font></div></td></tr></table></body></html>