Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - The Tomcat JDBC Connection Pool</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><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="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</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><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><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 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Tomcat JDBC Connection Pool</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<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="#System_Properties">System Properties</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>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>The <strong>JDBC Connection Pool <code>org.apache.tomcat.jdbc.pool</code></strong>
9 
  is a replacement or an alternative to the <a href="https://commons.apache.org/dbcp/">Apache Commons DBCP</a>
10 
  connection pool.</p>
11 
 
12 
  <p>So why do we need a new connection pool?</p>
13 
 
14 
  <p>Here are a few of the reasons:</p>
15 
    <ol>
16 
      <li>Commons DBCP 1.x is single threaded. In order to be thread safe
17 
          Commons locks the entire pool for short periods during both object
18 
          allocation and object return. Note that this does not apply to
19 
          Commons DBCP 2.x.</li>
20 
      <li>Commons DBCP 1.x can be slow. As the number of logical CPUs grows and
21 
          the number of concurrent threads attempting to borrow or return
22 
          objects increases, the performance suffers. For highly concurrent
23 
          systems the impact can be significant. Note that this does not apply
24 
          to Commons DBCP 2.x.</li>
25 
      <li>Commons DBCP is over 60 classes. tomcat-jdbc-pool core is 8 classes,
26 
          hence modifications for future requirement will require much less
27 
          changes. This is all you need to run the connection pool itself, the
28 
          rest is gravy.</li>
29 
      <li>Commons DBCP uses static interfaces. This means you have to use the
30 
          right version for a given JRE version or you may see
31 
          <code>NoSuchMethodException</code> exceptions.</li>
32 
      <li>It's not worth rewriting over 60 classes, when a connection pool can
33 
          be accomplished with a much simpler implementation.</li>
34 
      <li>Tomcat jdbc pool implements the ability retrieve a connection
35 
          asynchronously, without adding additional threads to the library
36 
          itself.</li>
37 
      <li>Tomcat jdbc pool is a Tomcat module, it depends on Tomcat JULI, a
38 
          simplified logging framework used in Tomcat.</li>
39 
      <li>Retrieve the underlying connection using the
40 
          <code>javax.sql.PooledConnection</code> interface.</li>
41 
      <li>Starvation proof. If a pool is empty, and threads are waiting for a
42 
          connection, when a connection is returned, the pool will awake the
43 
          correct thread waiting. Most pools will simply starve.</li>
44 
    </ol>
45 
 
46 
  <p>Features added over other connection pool implementations</p>
47 
    <ol>
48 
      <li>Support for highly concurrent environments and multi core/cpu systems.</li>
49 
      <li>Dynamic implementation of interface, will support <code>java.sql</code> and <code>javax.sql</code> interfaces for
50 
          your runtime environment (as long as your JDBC driver does the same), even when compiled with a lower version of the JDK.</li>
51 
      <li>Validation intervals - we don't have to validate every single time we use the connection, we can do this
52 
          when we borrow or return the connection, just not more frequent than an interval we can configure.</li>
53 
      <li>Run-Once query, a configurable query that will be run only once, when the connection to the database is established.
54 
          Very useful to setup session settings, that you want to exist during the entire time the connection is established.</li>
55 
      <li>Ability to configure custom interceptors.
56 
          This allows you to write custom interceptors to enhance the functionality. You can use interceptors to gather query stats,
57 
          cache session states, reconnect the connection upon failures, retry queries, cache query results, and so on.
58 
          Your options are endless and the interceptors are dynamic, not tied to a JDK version of a
59 
          <code>java.sql</code>/<code>javax.sql</code> interface.</li>
60 
      <li>High performance - we will show some differences in performance later on</li>
61 
      <li>Extremely simple, due to the very simplified implementation, the line count and source file count are very low, compare with c3p0
62 
          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
63 
          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>
64 
      <li>Asynchronous connection retrieval - you can queue your request for a connection and receive a <code>Future&lt;Connection&gt;</code> back.</li>
65 
      <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>
66 
      <li>You can decide at what moment connections are considered abandoned, is it when the pool is full, or directly at a timeout
67 
          by specifying a pool usage threshold.
68 
      </li>
69 
      <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.
70 
          This is achieved using the <code>ResetAbandonedTimer</code>
71 
      </li>
72 
      <li>Close connections after they have been connected for a certain time. Age based close upon return to the pool.
73 
      </li>
74 
      <li>Get JMX notifications and log entries when connections are suspected for being abandoned. This is similar to
75 
          the <code>removeAbandonedTimeout</code> but it doesn't take any action, only reports the information.
76 
          This is achieved using the <code>suspectTimeout</code> attribute.</li>
77 
      <li>Connections can be retrieved from a <code>java.sql.Driver</code>, <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code>
78 
          This is achieved using the <code>dataSource</code> and <code>dataSourceJNDI</code> attributes.</li>
79 
      <li>XA connection support</li>
80 
    </ol>
81 
 
82 
 
83 
</div><h3 id="How_to_use">How to use</h3><div class="text">
84 
  <p>
85 
    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
86 
    transition will be very simple. Moving from other connection pools is also fairly straight forward.
87 
  </p>
88 
  <div class="subsection"><h4 id="Additional_features">Additional features</h4><div class="text">
89 
    <p>The Tomcat connection pool offers a few additional features over what most other pools let you do:</p>
90 
    <ul>
91 
      <li><code>initSQL</code> - the ability to run an SQL statement exactly once, when the connection is created</li>
92 
      <li><code>validationInterval</code> - in addition to running validations on connections, avoid running them too frequently.</li>
93 
      <li><code>jdbcInterceptors</code> - flexible and pluggable interceptors to create any customizations around the pool,
94 
          the query execution and the result set handling. More on this in the advanced section.</li>
95 
      <li><code>fairQueue</code> - Set the fair flag to true to achieve thread fairness or to use asynchronous connection retrieval</li>
96 
    </ul>
97 
  </div></div>
98 
  <div class="subsection"><h4 id="Inside_the_Apache_Tomcat_Container">Inside the Apache Tomcat Container</h4><div class="text">
99 
    <p>
100 
      The Tomcat Connection pool is configured as a resource described in <a href="http://tomcat.apache.org/tomcat-9.0-doc/jndi-datasource-examples-howto.html" target="_blank">The Tomcat JDBC documentation</a>
101 
      With the only difference being that you have to specify the <code>factory</code> attribute and set the value to
102 
      <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code>
103 
    </p>
104 
  </div></div>
105 
  <div class="subsection"><h4 id="Standalone">Standalone</h4><div class="text">
106 
    <p>
107 
      The connection pool only has another dependency, and that is on tomcat-juli.jar.
108 
      To configure the pool in a stand alone project using bean instantiation, the bean to instantiate is
109 
      <code>org.apache.tomcat.jdbc.pool.DataSource</code>. The same attributes (documented below) as you use to configure a connection
110 
      pool as a JNDI resource, are used to configure a data source as a bean.
111 
    </p>
112 
  </div></div>
113 
  <div class="subsection"><h4 id="JMX">JMX</h4><div class="text">
114 
    <p>
115 
      The connection pool object exposes an MBean that can be registered.
116 
      In order for the connection pool object to create the MBean, the flag <code>jmxEnabled</code> has to be set to true.
117 
      This doesn't imply that the pool will be registered with an MBean server, merely that the MBean is created.
118 
      In a container like Tomcat, Tomcat itself registers the DataSource with the MBean server, the
119 
      <code>org.apache.tomcat.jdbc.pool.DataSource</code> object will then register the actual
120 
      connection pool MBean.
121 
      If you're running outside of a container, you can register the DataSource yourself under any object name you specify,
122 
      and it propagates the registration to the underlying pool. To do this you would call <code>mBeanServer.registerMBean(dataSource.getPool().getJmxPool(),objectname)</code>.
123 
      Prior to this call, ensure that the pool has been created by calling <code>dataSource.createPool()</code>.
124 
    </p>
125 
  </div></div>
126 
 
127 
</div><h3 id="Attributes">Attributes</h3><div class="text">
128 
  <p>To provide a very simple switch to and from commons-dbcp and tomcat-jdbc-pool,
129 
     Most attributes are the same and have the same meaning.</p>
130 
  <div class="subsection"><h4 id="JNDI_Factory_and_Type">JNDI Factory and Type</h4><div class="text">
131 
    <table class="defaultTable"><tr><th style="width: 15%;">
132 
          Attribute
133 
        </th><th style="width: 85%;">
134 
          Description
135 
        </th></tr><tr id="Attributes_JNDI Factory and Type_factory"><td><strong><code class="attributeName">factory</code></strong></td><td>
136 
        <p>factory is required, and the value should be <code>org.apache.tomcat.jdbc.pool.DataSourceFactory</code></p>
137 
      </td></tr><tr id="Attributes_JNDI Factory and Type_type"><td><strong><code class="attributeName">type</code></strong></td><td>
138 
        <p>Type should always be <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code></p>
139 
        <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>
140 
      </td></tr></table>
141 
  </div></div>
142 
 
143 
  <div class="subsection"><h4 id="System_Properties">System Properties</h4><div class="text">
144 
    <p>System properties are JVM wide, affect all pools created in the JVM</p>
145 
    <table class="defaultTable"><tr><th style="width: 15%;">
146 
          Attribute
147 
        </th><th style="width: 85%;">
148 
          Description
149 
        </th></tr><tr id="Attributes_System Properties_org.apache.tomcat.jdbc.pool.onlyAttemptCurrentClassLoader"><td><code class="attributeName">org.apache.tomcat.jdbc.pool.onlyAttemptCurrentClassLoader</code></td><td>
150 
        <p>(boolean) Controls classloading of dynamic classes, such as
151 
           JDBC drivers, interceptors and validators. If set to
152 
           <code>false</code>, default value, the pool will first attempt
153 
           to load using the current loader (i.e. the class loader that
154 
           loaded the pool classes) and if class loading fails attempt to
155 
           load using the thread context loader. Set this value to
156 
           <code>true</code>, if you wish to remain backwards compatible
157 
           with Apache Tomcat 8.0.8 and earlier, and only attempt the
158 
           current loader.
159 
           If not set then the default value is <code>false</code>.
160 
        </p>
161 
      </td></tr></table>
162 
  </div></div>
163 
 
164 
  <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
165 
  <p>These attributes are shared between commons-dbcp and tomcat-jdbc-pool, in some cases default values are different.</p>
166 
  <table class="defaultTable"><tr><th style="width: 15%;">
167 
          Attribute
168 
        </th><th style="width: 85%;">
169 
          Description
170 
        </th></tr><tr id="Attributes_Common Attributes_defaultAutoCommit"><td><code class="attributeName">defaultAutoCommit</code></td><td>
171 
      <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>
172 
    </td></tr><tr id="Attributes_Common Attributes_defaultReadOnly"><td><code class="attributeName">defaultReadOnly</code></td><td>
173 
      <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>
174 
    </td></tr><tr id="Attributes_Common Attributes_defaultTransactionIsolation"><td><code class="attributeName">defaultTransactionIsolation</code></td><td>
175 
      <p>(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )</p>
176 
         <ul>
177 
           <li><code>NONE</code></li>
178 
           <li><code>READ_COMMITTED</code></li>
179 
           <li><code>READ_UNCOMMITTED</code></li>
180 
           <li><code>REPEATABLE_READ</code></li>
181 
           <li><code>SERIALIZABLE</code></li>
182 
         </ul>
183 
         <p>If not set, the method will not be called and it defaults to the JDBC driver.</p>
184 
    </td></tr><tr id="Attributes_Common Attributes_defaultCatalog"><td><code class="attributeName">defaultCatalog</code></td><td>
185 
      <p>(String) The default catalog of connections created by this pool.</p>
186 
    </td></tr><tr id="Attributes_Common Attributes_driverClassName"><td><strong><code class="attributeName">driverClassName</code></strong></td><td>
187 
      <p>(String) The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible
188 
         from the same classloader as tomcat-jdbc.jar
189 
      </p>
190 
    </td></tr><tr id="Attributes_Common Attributes_username"><td><strong><code class="attributeName">username</code></strong></td><td>
191 
      <p>(String) The connection username to be passed to our JDBC driver to establish a connection.
192 
         Note that method <code>DataSource.getConnection(username,password)</code>
193 
         by default will not use credentials passed into the method,
194 
         but will use the ones configured here. See <code>alternateUsernameAllowed</code>
195 
         property for more details.
196 
      </p>
197 
    </td></tr><tr id="Attributes_Common Attributes_password"><td><strong><code class="attributeName">password</code></strong></td><td>
198 
      <p>(String) The connection password to be passed to our JDBC driver to establish a connection.
199 
         Note that method <code>DataSource.getConnection(username,password)</code>
200 
         by default will not use credentials passed into the method,
201 
         but will use the ones configured here. See <code>alternateUsernameAllowed</code>
202 
         property for more details.
203 
      </p>
204 
    </td></tr><tr id="Attributes_Common Attributes_maxActive"><td><code class="attributeName">maxActive</code></td><td>
205 
      <p>(int) The maximum number of active connections that can be allocated from this pool at the same time.
206 
         The default value is <code>100</code></p>
207 
    </td></tr><tr id="Attributes_Common Attributes_maxIdle"><td><code class="attributeName">maxIdle</code></td><td>
208 
      <p>(int) The maximum number of connections that should be kept in the pool at all times.
209 
         Default value is  <code>maxActive</code>:<code>100</code>
210 
         Idle connections are checked periodically (if enabled) and
211 
         connections that been idle for longer than <code>minEvictableIdleTimeMillis</code>
212 
         will be released. (also see <code>testWhileIdle</code>)</p>
213 
    </td></tr><tr id="Attributes_Common Attributes_minIdle"><td><code class="attributeName">minIdle</code></td><td>
214 
      <p>
215 
        (int) The minimum number of established connections that should be kept in the pool at all times.
216 
        The connection pool can shrink below this number if validation queries fail.
217 
        Default value is derived from <code>initialSize</code>:<code>10</code> (also see <code>testWhileIdle</code>)
218 
      </p>
219 
    </td></tr><tr id="Attributes_Common Attributes_initialSize"><td><code class="attributeName">initialSize</code></td><td>
220 
      <p>(int)The initial number of connections that are created when the pool is started.
221 
         Default value is <code>10</code></p>
222 
    </td></tr><tr id="Attributes_Common Attributes_maxWait"><td><code class="attributeName">maxWait</code></td><td>
223 
      <p>(int) The maximum number of milliseconds that the pool will wait (when there are no available connections)
224 
         for a connection to be returned before throwing an exception.
225 
         Default value is <code>30000</code> (30 seconds)</p>
226 
    </td></tr><tr id="Attributes_Common Attributes_testOnBorrow"><td><code class="attributeName">testOnBorrow</code></td><td>
227 
      <p>(boolean) The indication of whether objects will be validated before being borrowed from the pool.
228 
         If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
229 
         In order to have a more efficient validation, see <code>validationInterval</code>.
230 
         Default value is <code>false</code>
231 
      </p>
232 
    </td></tr><tr id="Attributes_Common Attributes_testOnConnect"><td><code class="attributeName">testOnConnect</code></td><td>
233 
      <p>(boolean) The indication of whether objects will be validated when a connection is first created.
234 
         If an object fails to validate, it will be throw <code>SQLException</code>.
235 
         Default value is <code>false</code>
236 
      </p>
237 
    </td></tr><tr id="Attributes_Common Attributes_testOnReturn"><td><code class="attributeName">testOnReturn</code></td><td>
238 
      <p>(boolean) The indication of whether objects will be validated before being returned to the pool.
239 
         The default value is <code>false</code>.
240 
      </p>
241 
    </td></tr><tr id="Attributes_Common Attributes_testWhileIdle"><td><code class="attributeName">testWhileIdle</code></td><td>
242 
      <p>(boolean) The indication of whether objects will be validated by the idle object evictor (if any).
243 
         If an object fails to validate, it will be dropped from the pool.
244 
         The default value is <code>false</code> and this property has to be set in order for the
245 
         pool cleaner/test thread is to run (also see <code>timeBetweenEvictionRunsMillis</code>)
246 
      </p>
247 
    </td></tr><tr id="Attributes_Common Attributes_validationQuery"><td><code class="attributeName">validationQuery</code></td><td>
248 
      <p>(String) The SQL query that will be used to validate connections from this pool before returning them to the caller.
249 
         If specified, this query does not have to return any data, it just can't throw a <code>SQLException</code>.
250 
         The default value is <code>null</code>.
251 
         If not specified, connections will be validation by the isValid() method.
252 
         Example values are <code>SELECT 1</code>(mysql), <code>select 1 from dual</code>(oracle), <code>SELECT 1</code>(MS Sql Server)
253 
      </p>
254 
    </td></tr><tr id="Attributes_Common Attributes_validationQueryTimeout"><td><code class="attributeName">validationQueryTimeout</code></td><td>
255 
      <p>(int) The timeout in seconds before a connection validation queries fail.  This works by calling
256 
         <code>java.sql.Statement.setQueryTimeout(seconds)</code> on the statement that executes the <code>validationQuery</code>.
257 
         The pool itself doesn't timeout the query, it is still up to the JDBC driver to enforce query timeouts.
258 
         A value less than or equal to zero will disable this feature.
259 
         The default value is <code>-1</code>.
260 
      </p>
261 
    </td></tr><tr id="Attributes_Common Attributes_validatorClassName"><td><code class="attributeName">validatorClassName</code></td><td>
262 
      <p>(String) The name of a class which implements the
263 
         <code>org.apache.tomcat.jdbc.pool.Validator</code> interface and
264 
         provides a no-arg constructor (may be implicit). If specified, the
265 
         class will be used to create a Validator instance which is then used
266 
         instead of any validation query to validate connections. The default
267 
         value is <code>null</code>. An example value is
268 
         <code>com.mycompany.project.SimpleValidator</code>.
269 
      </p>
270 
    </td></tr><tr id="Attributes_Common Attributes_timeBetweenEvictionRunsMillis"><td><code class="attributeName">timeBetweenEvictionRunsMillis</code></td><td>
271 
      <p>(int) The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread.
272 
         This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often
273 
         we validate idle connections. This value will be overridden by <code>maxAge</code> if the latter is non-zero and lower.
274 
         The default value is <code>5000</code> (5 seconds). <br>
275 
      </p>
276 
    </td></tr><tr id="Attributes_Common Attributes_numTestsPerEvictionRun"><td><code class="attributeName">numTestsPerEvictionRun</code></td><td>
277 
      <p>(int) Property not used in tomcat-jdbc-pool.</p>
278 
    </td></tr><tr id="Attributes_Common Attributes_minEvictableIdleTimeMillis"><td><code class="attributeName">minEvictableIdleTimeMillis</code></td><td>
279 
      <p>(int) The minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
280 
         The default value is <code>60000</code> (60 seconds).</p>
281 
    </td></tr><tr id="Attributes_Common Attributes_accessToUnderlyingConnectionAllowed"><td><code class="attributeName">accessToUnderlyingConnectionAllowed</code></td><td>
282 
      <p>(boolean) Property not used. Access can be achieved by calling <code>unwrap</code> on the pooled connection.
283 
         see <code>javax.sql.DataSource</code> interface, or call <code>getConnection</code> through reflection or
284 
         cast the object as <code>javax.sql.PooledConnection</code></p>
285 
    </td></tr><tr id="Attributes_Common Attributes_removeAbandoned"><td><code class="attributeName">removeAbandoned</code></td><td>
286 
      <p>(boolean) Flag to remove abandoned connections if they exceed the <code>removeAbandonedTimeout</code>.
287 
         If set to true a connection is considered abandoned and eligible for removal if it has been in use
288 
         longer than the <code>removeAbandonedTimeout</code> Setting this to <code>true</code> can recover db connections from
289 
         applications that fail to close a connection. See also <code>logAbandoned</code>
290 
         The default value is <code>false</code>.</p>
291 
    </td></tr><tr id="Attributes_Common Attributes_removeAbandonedTimeout"><td><code class="attributeName">removeAbandonedTimeout</code></td><td>
292 
      <p>(int) Timeout in seconds before an abandoned(in use) connection can be removed.
293 
         The default value is <code>60</code> (60 seconds). The value should be set to the longest running query your applications
294 
         might have.</p>
295 
    </td></tr><tr id="Attributes_Common Attributes_logAbandoned"><td><code class="attributeName">logAbandoned</code></td><td>
296 
      <p>(boolean) Flag to log stack traces for application code which abandoned a Connection.
297 
         Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
298 
         The default value is <code>false</code>.</p>
299 
    </td></tr><tr id="Attributes_Common Attributes_connectionProperties"><td><code class="attributeName">connectionProperties</code></td><td>
300 
      <p>(String) The connection properties that will be sent to our JDBC driver when establishing new connections.
301 
         Format of the string must be [propertyName=property;]*
302 
         NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
303 
         The default value is <code>null</code>.</p>
304 
    </td></tr><tr id="Attributes_Common Attributes_poolPreparedStatements"><td><code class="attributeName">poolPreparedStatements</code></td><td>
305 
      <p>(boolean) Property not used.</p>
306 
    </td></tr><tr id="Attributes_Common Attributes_maxOpenPreparedStatements"><td><code class="attributeName">maxOpenPreparedStatements</code></td><td>
307 
      <p>(int) Property not used.</p>
308 
    </td></tr></table>
309 
 
310 
  </div></div>
311 
 
312 
  <div class="subsection"><h4 id="Tomcat_JDBC_Enhanced_Attributes">Tomcat JDBC Enhanced Attributes</h4><div class="text">
313 
 
314 
  <table class="defaultTable"><tr><th style="width: 15%;">
315 
          Attribute
316 
        </th><th style="width: 85%;">
317 
          Description
318 
        </th></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_initSQL"><td><code class="attributeName">initSQL</code></td><td>
319 
      <p>(String) A custom query to be run when a connection is first created.
320 
         The default value is <code>null</code>.</p>
321 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_jdbcInterceptors"><td><code class="attributeName">jdbcInterceptors</code></td><td>
322 
      <p>(String) A semicolon separated list of classnames extending
323 
         <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class.
324 
         See <a href="#Configuring_JDBC_interceptors">Configuring JDBC interceptors</a>
325 
         below for more detailed description of syntax and examples.
326 
      </p>
327 
      <p>
328 
         These interceptors will be inserted as an interceptor into the chain
329 
         of operations on a <code>java.sql.Connection</code> object.
330 
         The default value is <code>null</code>.
331 
      </p>
332 
      <p>
333 
         Predefined interceptors:<br>
334 
         <code>org.apache.tomcat.jdbc.pool.interceptor.<br>ConnectionState</code>
335 
          - keeps track of auto commit, read only, catalog and transaction isolation level.<br>
336 
         <code>org.apache.tomcat.jdbc.pool.interceptor.<br>StatementFinalizer</code>
337 
          - keeps track of opened statements, and closes them when the connection is returned to the pool.
338 
      </p>
339 
      <p>
340 
         More predefined interceptors are described in detail in the
341 
         <a href="#JDBC_interceptors">JDBC Interceptors section</a>.
342 
      </p>
343 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_validationInterval"><td><code class="attributeName">validationInterval</code></td><td>
344 
      <p>(long) avoid excess validation, only run validation at most at this frequency - time in milliseconds.
345 
         If a connection is due for validation, but has been validated previously within this interval, it will not be validated again.
346 
         The default value is <code>3000</code> (3 seconds).</p>
347 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_jmxEnabled"><td><code class="attributeName">jmxEnabled</code></td><td>
348 
      <p>(boolean) Register the pool with JMX or not.
349 
         The default value is <code>true</code>.</p>
350 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_fairQueue"><td><code class="attributeName">fairQueue</code></td><td>
351 
      <p>(boolean) Set to true if you wish that calls to getConnection should be treated
352 
         fairly in a true FIFO fashion. This uses the <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue</code>
353 
         implementation for the list of the idle connections. The default value is <code>true</code>.
354 
         This flag is required when you want to use asynchronous connection retrieval.<br>
355 
         Setting this flag ensures that threads receive connections in the order they arrive.<br>
356 
         During performance tests, there is a very large difference in how locks
357 
         and lock waiting is implemented. When <code>fairQueue=true</code>
358 
         there is a decision making process based on what operating system the system is running.
359 
         If the system is running on Linux (property <code>os.name=Linux</code>.
360 
         To disable this Linux specific behavior and still use the fair queue, simply add the property
361 
         <code>org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true</code> to your system properties
362 
         before the connection pool classes are loaded.
363 
      </p>
364 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_abandonWhenPercentageFull"><td><code class="attributeName">abandonWhenPercentageFull</code></td><td>
365 
      <p>(int) Connections that have been abandoned (timed out) won't get closed and reported up unless
366 
         the number of connections in use are above the percentage defined by <code>abandonWhenPercentageFull</code>.
367 
         The value should be between 0-100.
368 
         The default value is <code>0</code>, which implies that connections are eligible for closure as soon
369 
         as <code>removeAbandonedTimeout</code> has been reached.</p>
370 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_maxAge"><td><code class="attributeName">maxAge</code></td><td>
371 
      <p>(long) Time in milliseconds to keep a connection before recreating it.
372 
         When a connection is borrowed from the pool, the pool will check to see
373 
         if the <code>now - time-when-connected &gt; maxAge</code> has been reached
374 
         , and if so, it reconnects before borrow it. When a connection is
375 
         returned to the pool, the pool will check to see if the
376 
         <code>now - time-when-connected &gt; maxAge</code> has been reached, and
377 
         if so, it tries to reconnect.
378 
         When a connection is idle and <code>timeBetweenEvictionRunsMillis</code> is
379 
         greater than zero, the pool will periodically check to see if the
380 
         <code>now - time-when-connected &gt; maxAge</code> has been reached, and
381 
         if so, it tries to reconnect.
382 
         Setting <code>maxAge</code> to a value lower than <code>timeBetweenEvictionRunsMillis</code>
383 
         will override it (so idle connection validation/cleaning will run more frequently).
384 
         The default value is <code>0</code>, which implies that connections
385 
         will be left open and no age check will be done upon borrowing from the
386 
         pool, returning the connection to the pool or when checking idle connections.</p>
387 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_useEquals"><td><code class="attributeName">useEquals</code></td><td>
388 
      <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>
389 
         when you wish to use <code>==</code> when comparing method names. This property does not apply to added interceptors as those are configured individually.
390 
         The default value is <code>true</code>.
391 
      </p>
392 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_suspectTimeout"><td><code class="attributeName">suspectTimeout</code></td><td>
393 
      <p>(int) Timeout value in seconds. Default value is <code>0</code>.<br>
394 
           Similar to to the <code>removeAbandonedTimeout</code> value but instead of treating the connection
395 
           as abandoned, and potentially closing the connection, this simply logs the warning if
396 
           <code>logAbandoned</code> is set to true. If this value is equal or less than 0, no suspect
397 
           checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
398 
           the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
399 
           logged and a JMX notification gets sent once.
400 
      </p>
401 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_rollbackOnReturn"><td><code class="attributeName">rollbackOnReturn</code></td><td>
402 
      <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
403 
          Default value is <code>false</code>.<br>
404 
      </p>
405 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_commitOnReturn"><td><code class="attributeName">commitOnReturn</code></td><td>
406 
      <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
407 
          If <code>rollbackOnReturn==true</code> then this attribute is ignored.
408 
          Default value is <code>false</code>.<br>
409 
      </p>
410 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_alternateUsernameAllowed"><td><code class="attributeName">alternateUsernameAllowed</code></td><td>
411 
      <p>(boolean) By default, the jdbc-pool will ignore the
412 
         <a href="https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)"><code>DataSource.getConnection(username,password)</code></a>
413 
         call, and simply return a previously pooled connection under the globally configured properties <code>username</code> and <code>password</code>, for performance reasons.
414 
      </p>
415 
      <p>
416 
         The pool can however be configured to allow use of different credentials
417 
         each time a connection is requested.  To enable the functionality described in the
418 
         <a href="https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html#getConnection(java.lang.String,%20java.lang.String)"><code>DataSource.getConnection(username,password)</code></a>
419 
         call, simply set the property <code>alternateUsernameAllowed</code>
420 
         to <code>true</code>.<br>
421 
         Should you request a connection with the credentials user1/password1 and the connection
422 
         was previously connected using different user2/password2, the connection will be closed,
423 
         and reopened with the requested credentials. This way, the pool size is still managed
424 
         on a global level, and not on a per schema level. <br>
425 
         The default value is <code>false</code>.<br>
426 
         This property was added as an enhancement to <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=50025">bug 50025</a>.
427 
      </p>
428 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_dataSource"><td><code class="attributeName">dataSource</code></td><td>
429 
      <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.
430 
         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>
431 
      </p>
432 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_dataSourceJNDI"><td><code class="attributeName">dataSourceJNDI</code></td><td>
433 
      <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>
434 
      </p>
435 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_useDisposableConnectionFacade"><td><code class="attributeName">useDisposableConnectionFacade</code></td><td>
436 
      <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
437 
                   reference of a connection it has already called closed on, to execute queries on it. Default value is <code>true</code>.
438 
      </p>
439 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_logValidationErrors"><td><code class="attributeName">logValidationErrors</code></td><td>
440 
      <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.
441 
      </p>
442 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_propagateInterruptState"><td><code class="attributeName">propagateInterruptState</code></td><td>
443 
      <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.
444 
      </p>
445 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_ignoreExceptionOnPreLoad"><td><code class="attributeName">ignoreExceptionOnPreLoad</code></td><td>
446 
      <p>(boolean) Flag whether ignore error of connection creation while initializing the pool.
447 
         Set to true if you want to ignore error of connection creation while initializing the pool.
448 
         Set to false if you want to fail the initialization of the pool by throwing exception.
449 
         The default value is <code>false</code>.
450 
      </p>
451 
    </td></tr><tr id="Attributes_Tomcat JDBC Enhanced Attributes_useStatementFacade"><td><code class="attributeName">useStatementFacade</code></td><td>
452 
      <p>(boolean) Set this to true if you wish to wrap statements in order to
453 
         enable <code>equals()</code> and <code>hashCode()</code> methods to be
454 
         called on the closed statements if any statement proxy is set.
455 
         Default value is <code>true</code>.
456 
      </p>
457 
    </td></tr></table>
458 
  </div></div>
459 
</div><h3 id="Advanced_usage">Advanced usage</h3><div class="text">
460 
  <div class="subsection"><h4 id="JDBC_interceptors">JDBC interceptors</h4><div class="text">
461 
    <p>To see an example of how to use an interceptor, take a look at
462 
    <code>org.apache.tomcat.jdbc.pool.interceptor.ConnectionState</code>.
463 
    This simple interceptor is a cache of three attributes, transaction isolation level, auto commit and read only state,
464 
    in order for the system to avoid not needed roundtrips to the database.
465 
    </p>
466 
    <p>Further interceptors will be added to the core of the pool as the need arises. Contributions are always welcome!</p>
467 
    <p>Interceptors are of course not limited to just <code>java.sql.Connection</code> but can be used to wrap any
468 
    of the results from a method invocation as well. You could build query performance analyzer that provides JMX notifications when a
469 
    query is running longer than the expected time.</p>
470 
  </div></div>
471 
  <div class="subsection"><h4 id="Configuring_JDBC_interceptors">Configuring JDBC interceptors</h4><div class="text">
472 
    <p>Configuring JDBC interceptors is done using the <b>jdbcInterceptors</b> property.
473 
    The property contains a list of semicolon separated class names. If the
474 
    classname is not fully qualified it will be prefixed with the
475 
    <code>org.apache.tomcat.jdbc.pool.interceptor.</code> prefix.
476 
    </p>
477 
    <p>Example:<br>
478 
      <code>
479 
      jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
480 
        org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
481 
      </code>
482 
      <br>
483 
      is the same as
484 
      <br>
485 
      <code> jdbcInterceptors="ConnectionState;StatementFinalizer"</code>
486 
    </p>
487 
    <p>
488 
    Interceptors can have properties as well. Properties for an interceptor
489 
    are specified within parentheses after the class name. Several properties
490 
    are separated by commas.
491 
    </p>
492 
    <p>Example:<br>
493 
    <code>
494 
      jdbcInterceptors="ConnectionState;StatementFinalizer(useEquals=true)"
495 
    </code>
496 
    </p>
497 
    <p>
498 
    Extra whitespace characters around class names, property names and values
499 
    are ignored.
500 
    </p>
501 
  </div></div>
502 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.JdbcInterceptor">org.apache.tomcat.jdbc.pool.JdbcInterceptor</h4><div class="text">
503 
    <p>Abstract base class for all interceptors, cannot be instantiated.</p>
504 
    <table class="defaultTable"><tr><th style="width: 15%;">
505 
          Attribute
506 
        </th><th style="width: 85%;">
507 
          Description
508 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.JdbcInterceptor_useEquals"><td><code class="attributeName">useEquals</code></td><td>
509 
        <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>
510 
         when you wish to use <code>==</code> when comparing method names.
511 
         The default value is <code>true</code>.
512 
        </p>
513 
      </td></tr></table>
514 
  </div></div>
515 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState">org.apache.tomcat.jdbc.pool.interceptor.ConnectionState</h4><div class="text">
516 
    <p>Caches the connection for the following attributes <code>autoCommit</code>, <code>readOnly</code>,
517 
       <code>transactionIsolation</code> and <code>catalog</code>.
518 
       It is a performance enhancement to avoid roundtrip to the database when getters are called or setters are called with an already set value.
519 
    </p>
520 
    <table class="defaultTable"><tr><th style="width: 15%;">
521 
          Attribute
522 
        </th><th style="width: 85%;">
523 
          Description
524 
        </th></tr></table>
525 
  </div></div>
526 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer">org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer</h4><div class="text">
527 
    <p>Keeps track of all statements created using <code>createStatement</code>, <code>prepareStatement</code> or <code>prepareCall</code>
528 
       and closes these statements when the connection is returned to the pool.
529 
    </p>
530 
    <table class="defaultTable"><tr><th style="width: 15%;">
531 
          Attribute
532 
        </th><th style="width: 85%;">
533 
          Description
534 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer_trace"><td><code class="attributeName">trace</code></td><td>
535 
        <p>(boolean as String) Enable tracing of unclosed statements.
536 
           When enabled and a connection is closed, and statements are not closed,
537 
           the interceptor will log all stack traces.
538 
           The default value is <code>false</code>.
539 
        </p>
540 
      </td></tr></table>
541 
  </div></div>
542 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.StatementCache">org.apache.tomcat.jdbc.pool.interceptor.StatementCache</h4><div class="text">
543 
    <p>Caches <code>PreparedStatement</code> and/or <code>CallableStatement</code>
544 
       instances on a connection.
545 
    </p>
546 
    <p>The statements are cached per connection.
547 
       The count limit is counted globally for all connections that belong to
548 
       the same pool. Once the count reaches <code>max</code>, subsequent
549 
       statements are not returned to the cache and are closed immediately.
550 
    </p>
551 
    <table class="defaultTable"><tr><th style="width: 15%;">
552 
          Attribute
553 
        </th><th style="width: 85%;">
554 
          Description
555 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.StatementCache_prepared"><td><code class="attributeName">prepared</code></td><td>
556 
        <p>(boolean as String) Enable caching of <code>PreparedStatement</code>
557 
           instances created using <code>prepareStatement</code> calls.
558 
           The default value is <code>true</code>.
559 
        </p>
560 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.StatementCache_callable"><td><code class="attributeName">callable</code></td><td>
561 
        <p>(boolean as String) Enable caching of <code>CallableStatement</code>
562 
           instances created using <code>prepareCall</code> calls.
563 
           The default value is <code>false</code>.
564 
        </p>
565 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.StatementCache_max"><td><code class="attributeName">max</code></td><td>
566 
        <p>(int as String) Limit on the count of cached statements across
567 
           the connection pool.
568 
           The default value is <code>50</code>.
569 
        </p>
570 
      </td></tr></table>
571 
  </div></div>
572 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor">org.apache.tomcat.jdbc.pool.interceptor.StatementDecoratorInterceptor</h4><div class="text">
573 
    <p>See <a href="https://bz.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
574 
       using the methods <code>ResultSet.getStatement().getConnection()</code> and <code>Statement.getConnection()</code>
575 
    </p>
576 
    <table class="defaultTable"><tr><th style="width: 15%;">
577 
          Attribute
578 
        </th><th style="width: 85%;">
579 
          Description
580 
        </th></tr></table>
581 
  </div></div>
582 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor">org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor</h4><div class="text">
583 
    <p>Automatically calls <code>java.sql.Statement.setQueryTimeout(seconds)</code> when a new statement is created.
584 
       The pool itself doesn't timeout the query, it is still up to the JDBC driver to enforce query timeouts.
585 
    </p>
586 
    <table class="defaultTable"><tr><th style="width: 15%;">
587 
          Attribute
588 
        </th><th style="width: 85%;">
589 
          Description
590 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.QueryTimeoutInterceptor_queryTimeout"><td><strong><code class="attributeName">queryTimeout</code></strong></td><td>
591 
        <p>(int as String) The number of seconds to set for the query timeout.
592 
           A value less than or equal to zero will disable this feature.
593 
           The default value is <code>1</code> seconds.
594 
        </p>
595 
      </td></tr></table>
596 
  </div></div>
597 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport">org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport</h4><div class="text">
598 
    <p>Keeps track of query performance and issues log entries when queries exceed a time threshold of fail.
599 
       The log level used is <code>WARN</code>
600 
    </p>
601 
    <table class="defaultTable"><tr><th style="width: 15%;">
602 
          Attribute
603 
        </th><th style="width: 85%;">
604 
          Description
605 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport_threshold"><td><code class="attributeName">threshold</code></td><td>
606 
        <p>(int as String) The number of milliseconds a query has to exceed before issuing a log alert.
607 
           The default value is <code>1000</code> milliseconds.
608 
        </p>
609 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport_maxQueries"><td><code class="attributeName">maxQueries</code></td><td>
610 
        <p>(int as String) The maximum number of queries to keep track of in order to preserve memory space.
611 
           A value less than or equal to 0 will disable this feature.
612 
           The default value is <code>1000</code>.
613 
        </p>
614 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport_logSlow"><td><code class="attributeName">logSlow</code></td><td>
615 
        <p>(boolean as String) Set to <code>true</code> if you wish to log slow queries.
616 
            The default value is <code>true</code>.
617 
        </p>
618 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReport_logFailed"><td><code class="attributeName">logFailed</code></td><td>
619 
        <p>(boolean as String) Set to <code>true</code> if you wish to log failed queries.
620 
            The default value is <code>false</code>.
621 
        </p>
622 
      </td></tr></table>
623 
  </div></div>
624 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx">org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx</h4><div class="text">
625 
    <p>Extends the <code>SlowQueryReport</code> and in addition to log entries it issues JMX notification
626 
       for monitoring tools to react to. Inherits all the attributes from its parent class.
627 
       This class uses Tomcat's JMX engine so it won't work outside of the Tomcat container.
628 
       By default, JMX notifications are sent through the ConnectionPool mbean if it is enabled.
629 
       The <code>SlowQueryReportJmx</code> can also register an MBean if <code>notifyPool=false</code>
630 
    </p>
631 
    <table class="defaultTable"><tr><th style="width: 15%;">
632 
          Attribute
633 
        </th><th style="width: 85%;">
634 
          Description
635 
        </th></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx_notifyPool"><td><code class="attributeName">notifyPool</code></td><td>
636 
        <p>(boolean as String) Set to false if you want JMX notifications to go to the <code>SlowQueryReportJmx</code> MBean
637 
           The default value is <code>true</code>.
638 
        </p>
639 
      </td></tr><tr id="Advanced usage_org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx_objectName"><td><code class="attributeName">objectName</code></td><td>
640 
        <p>(String) Define a valid <code>javax.management.ObjectName</code> string that will be used to register this object with the platform mbean server
641 
           The default value is <code>null</code> and the object will be registered using
642 
           tomcat.jdbc:type=org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx,name=the-name-of-the-pool
643 
        </p>
644 
      </td></tr></table>
645 
  </div></div>
646 
  <div class="subsection"><h4 id="org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer">org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer</h4><div class="text">
647 
    <p>
648 
        The abandoned timer starts when a connection is checked out from the pool.
649 
        This means if you have a 30second timeout and run 10x10second queries using the connection
650 
        it will be marked abandoned and potentially reclaimed depending on the <code>abandonWhenPercentageFull</code>
651 
        attribute.
652 
        Using this interceptor it will reset the checkout timer every time you perform an operation on the connection or execute a
653 
        query successfully.
654 
    </p>
655 
    <table class="defaultTable"><tr><th style="width: 15%;">
656 
          Attribute
657 
        </th><th style="width: 85%;">
658 
          Description
659 
        </th></tr></table>
660 
  </div></div>
661 
</div><h3 id="Code_Example">Code Example</h3><div class="text">
662 
  <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="https://tomcat.apache.org/tomcat-9.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p>
663 
  <div class="subsection"><h4 id="Plain_Ol'_Java">Plain Ol' Java</h4><div class="text">
664 
    <p>Here is a simple example of how to create and use a data source.</p>
665 
<div class="codeBox"><pre><code>  import java.sql.Connection;
666 
  import java.sql.ResultSet;
667 
  import java.sql.Statement;
668 
 
669 
  import org.apache.tomcat.jdbc.pool.DataSource;
670 
  import org.apache.tomcat.jdbc.pool.PoolProperties;
671 
 
672 
  public class SimplePOJOExample {
673 
 
674 
      public static void main(String[] args) throws Exception {
675 
          PoolProperties p = new PoolProperties();
676 
          p.setUrl("jdbc:mysql://localhost:3306/mysql");
677 
          p.setDriverClassName("com.mysql.jdbc.Driver");
678 
          p.setUsername("root");
679 
          p.setPassword("password");
680 
          p.setJmxEnabled(true);
681 
          p.setTestWhileIdle(false);
682 
          p.setTestOnBorrow(true);
683 
          p.setValidationQuery("SELECT 1");
684 
          p.setTestOnReturn(false);
685 
          p.setValidationInterval(30000);
686 
          p.setTimeBetweenEvictionRunsMillis(30000);
687 
          p.setMaxActive(100);
688 
          p.setInitialSize(10);
689 
          p.setMaxWait(10000);
690 
          p.setRemoveAbandonedTimeout(60);
691 
          p.setMinEvictableIdleTimeMillis(30000);
692 
          p.setMinIdle(10);
693 
          p.setLogAbandoned(true);
694 
          p.setRemoveAbandoned(true);
695 
          p.setJdbcInterceptors(
696 
            "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+
697 
            "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer");
698 
          DataSource datasource = new DataSource();
699 
          datasource.setPoolProperties(p);
700 
 
701 
          Connection con = null;
702 
          try {
703 
            con = datasource.getConnection();
704 
            Statement st = con.createStatement();
705 
            ResultSet rs = st.executeQuery("select * from user");
706 
            int cnt = 1;
707 
            while (rs.next()) {
708 
                System.out.println((cnt++)+". Host:" +rs.getString("Host")+
709 
                  " User:"+rs.getString("User")+" Password:"+rs.getString("Password"));
710 
            }
711 
            rs.close();
712 
            st.close();
713 
          } finally {
714 
            if (con!=null) try {con.close();}catch (Exception ignore) {}
715 
          }
716 
      }
717 
 
718 
  }</code></pre></div>
719 
  </div></div>
720 
  <div class="subsection"><h4 id="As_a_Resource">As a Resource</h4><div class="text">
721 
    <p>And here is an example on how to configure a resource for JNDI lookups</p>
722 
<div class="codeBox"><pre><code>&lt;Resource name="jdbc/TestDB"
723 
          auth="Container"
724 
          type="javax.sql.DataSource"
725 
          factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
726 
          testWhileIdle="true"
727 
          testOnBorrow="true"
728 
          testOnReturn="false"
729 
          validationQuery="SELECT 1"
730 
          validationInterval="30000"
731 
          timeBetweenEvictionRunsMillis="30000"
732 
          maxActive="100"
733 
          minIdle="10"
734 
          maxWait="10000"
735 
          initialSize="10"
736 
          removeAbandonedTimeout="60"
737 
          removeAbandoned="true"
738 
          logAbandoned="true"
739 
          minEvictableIdleTimeMillis="30000"
740 
          jmxEnabled="true"
741 
          jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
742 
            org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
743 
          username="root"
744 
          password="password"
745 
          driverClassName="com.mysql.jdbc.Driver"
746 
          url="jdbc:mysql://localhost:3306/mysql"/&gt;</code></pre></div>
747 
 
748 
  </div></div>
749 
  <div class="subsection"><h4 id="Asynchronous_Connection_Retrieval">Asynchronous Connection Retrieval</h4><div class="text">
750 
    <p> The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the
751 
        pool library. It does this by adding a method to the data source called <code>Future&lt;Connection&gt; getConnectionAsync()</code>.
752 
        In order to use the async retrieval, two conditions must be met:
753 
    </p>
754 
        <ol>
755 
          <li>You must configure the <code>fairQueue</code> property to be <code>true</code>.</li>
756 
          <li>You will have to cast the data source to <code>org.apache.tomcat.jdbc.pool.DataSource</code></li>
757 
        </ol>
758 
        An example of using the async feature is show below.
759 
<div class="codeBox"><pre><code>  Connection con = null;
760 
  try {
761 
    Future&lt;Connection&gt; future = datasource.getConnectionAsync();
762 
    while (!future.isDone()) {
763 
      System.out.println("Connection is not yet available. Do some background work");
764 
      try {
765 
        Thread.sleep(100); //simulate work
766 
      }catch (InterruptedException x) {
767 
        Thread.currentThread().interrupt();
768 
      }
769 
    }
770 
    con = future.get(); //should return instantly
771 
    Statement st = con.createStatement();
772 
    ResultSet rs = st.executeQuery("select * from user");</code></pre></div>
773 
 
774 
  </div></div>
775 
  <div class="subsection"><h4 id="Interceptors">Interceptors</h4><div class="text">
776 
    <p>Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components.
777 
       There are many different use cases for when interceptors are useful. By default, and for performance reasons, the connection pool is stateless.
778 
       The only state the pool itself inserts are <code>defaultAutoCommit</code>, <code>defaultReadOnly</code>, <code>defaultTransactionIsolation</code>, <code>defaultCatalog</code> if
779 
       these are set. These 4 properties are only set upon connection creation. Should these properties be modified during the usage of the connection,
780 
       the pool itself will not reset them.</p>
781 
    <p>An interceptor has to extend the <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class. This class is fairly simple,
782 
       You will need to have a no arg constructor</p>
783 
<div class="codeBox"><pre><code>  public JdbcInterceptor() {
784 
  }</code></pre></div>
785 
    <p>
786 
       When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the
787 
    </p>
788 
<div class="codeBox"><pre><code>  public abstract void reset(ConnectionPool parent, PooledConnection con);</code></pre></div>
789 
    <p>
790 
       method. This method gets called with two parameters, a reference to the connection pool itself <code>ConnectionPool parent</code>
791 
       and a reference to the underlying connection <code>PooledConnection con</code>.
792 
    </p>
793 
    <p>
794 
       When a method on the <code>java.sql.Connection</code> object is invoked, it will cause the
795 
    </p>
796 
<div class="codeBox"><pre><code>  public Object invoke(Object proxy, Method method, Object[] args) throws Throwable</code></pre></div>
797 
    <p>
798 
       method to get invoked. The <code>Method method</code> is the actual method invoked, and <code>Object[] args</code> are the arguments.
799 
       To look at a very simple example, where we demonstrate how to make the invocation to <code>java.sql.Connection.close()</code> a noop
800 
       if the connection has been closed
801 
    </p>
802 
<div class="codeBox"><pre><code>  if (CLOSE_VAL==method.getName()) {
803 
      if (isClosed()) return null; //noop for already closed.
804 
  }
805 
  return super.invoke(proxy,method,args);</code></pre></div>
806 
    <p>
807 
        There is an observation being made. It is the comparison of the method name. One way to do this would be to do
808 
        <code>"close".equals(method.getName())</code>.
809 
        Above we see a direct reference comparison between the method name and <code>static final String</code> reference.
810 
        According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work.
811 
        One could of course do this as well:
812 
    </p>
813 
<div class="codeBox"><pre><code>  if (compare(CLOSE_VAL,method)) {
814 
      if (isClosed()) return null; //noop for already closed.
815 
  }
816 
  return super.invoke(proxy,method,args);</code></pre></div>
817 
    <p>
818 
        The <code>compare(String,Method)</code> will use the <code>useEquals</code> flag on an interceptor and do either reference comparison or
819 
        a string value comparison when the <code>useEquals=true</code> flag is set.
820 
    </p>
821 
    <p>Pool start/stop<br>
822 
       When the connection pool is started or closed, you can be notified. You will only be notified once per interceptor class
823 
       even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool.
824 
    </p>
825 
<div class="codeBox"><pre><code>  public void poolStarted(ConnectionPool pool) {
826 
  }
827 
 
828 
  public void poolClosed(ConnectionPool pool) {
829 
  }</code></pre></div>
830 
    <p>
831 
       When overriding these methods, don't forget to call super if you are extending a class other than <code>JdbcInterceptor</code>
832 
    </p>
833 
    <p>Configuring interceptors<br>
834 
       Interceptors are configured using the <code>jdbcInterceptors</code> property or the <code>setJdbcInterceptors</code> method.
835 
       An interceptor can have properties, and would be configured like this
836 
    </p>
837 
<div class="codeBox"><pre><code>  String jdbcInterceptors=
838 
    "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)"</code></pre></div>
839 
 
840 
    <p>Interceptor properties<br>
841 
       Since interceptors can have properties, you need to be able to read the values of these properties within your
842 
       interceptor. Taking an example like the one above, you can override the <code>setProperties</code> method.
843 
    </p>
844 
<div class="codeBox"><pre><code>  public void setProperties(Map&lt;String, InterceptorProperty&gt; properties) {
845 
     super.setProperties(properties);
846 
     final String myprop = "myprop";
847 
     InterceptorProperty p1 = properties.get(myprop);
848 
     if (p1!=null) {
849 
         setMyprop(Long.parseLong(p1.getValue()));
850 
     }
851 
  }</code></pre></div>
852 
 
853 
  </div></div>
854 
  <div class="subsection"><h4 id="Getting_the_actual_JDBC_connection">Getting the actual JDBC connection</h4><div class="text">
855 
    <p>Connection pools create wrappers around the actual connection in order to properly pool them.
856 
       We also create interceptors in these wrappers to be able to perform certain functions.
857 
       If there is a need to retrieve the actual connection, one can do so using the <code>javax.sql.PooledConnection</code>
858 
       interface.
859 
    </p>
860 
<div class="codeBox"><pre><code>  Connection con = datasource.getConnection();
861 
  Connection actual = ((javax.sql.PooledConnection)con).getConnection();</code></pre></div>
862 
 
863 
  </div></div>
864 
 
865 
</div><h3 id="Building">Building</h3><div class="text">
866 
  <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>
867 
  <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="https://tomcat.apache.org/tomcat-9.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p>
868 
  <div class="subsection"><h4 id="Building_from_source">Building from source</h4><div class="text">
869 
    <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>
870 
<div class="codeBox"><pre><code>  javac -classpath tomcat-juli.jar \
871 
        -d . \
872 
        org/apache/tomcat/jdbc/pool/*.java \
873 
        org/apache/tomcat/jdbc/pool/interceptor/*.java \
874 
        org/apache/tomcat/jdbc/pool/jmx/*.java</code></pre></div>
875 
    <p>
876 
       A build file can be found in the Tomcat <a href="https://svn.apache.org/viewvc/tomcat/trunk/modules/jdbc-pool/">source repository</a>.
877 
    </p>
878 
    <p>
879 
      As a convenience, a build file is also included where a simple build command will generate all files needed.
880 
    </p>
881 
<div class="codeBox"><pre><code>  ant download  (downloads dependencies)
882 
  ant build     (compiles and generates .jar files)
883 
  ant dist      (creates a release package)
884 
  ant test      (runs tests, expects a test database to be setup)</code></pre></div>
885 
 
886 
    <p>
887 
      The system is structured for a Maven build, but does generate release artifacts. Just the library itself.
888 
    </p>
889 
  </div></div>
890 
</div></div></div></div></div><footer><div id="footer">
891 
    Copyright &copy; 1999-2025, The Apache Software Foundation
892 
    <br>
893 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
894 
    are either registered trademarks or trademarks of the Apache Software
895 
    Foundation.
896 
    </div></footer></div></body></html>