addConnectionPoolListener(ConnectionPoolListener)
	removeConnectionPoolListener(ConnectionPoolListener)
</pre>
<p>Also provided for convenience is the ConnectionPoolEventAdapter class, which provides null implementations of all the methods in the ConnectionPoolEventListener interface.</p>
<p>The events triggered are as follows:</p>
<blockquote>
<table border="1" cellspacing="0" cellpadding="3">
<tr>
	<th>Event Identifier</th>
	<th>Description</th>
</tr>
<tr>
	<td><code>CHECKOUT</code></td>
	<td>Fired just before a valid connection is handed back to a checkOut(...) request.</td>
</tr>
<tr>
	<td><code>CHECKIN</code></td>
	<td>Fired when a connection is handed back with a checkIn(...) call.</td>
</tr>
<tr>
	<td><code>MAX_POOL_LIMIT_REACHED</code></td>
	<td>Fired when a check-out request causes the pooling limit (maxpool) to be reached.</td>
</tr>
<tr>
	<td><code>MAX_POOL_LIMIT_EXCEEDED</code></td>
	<td>Fired when a check-out request causes the pooling limit (maxpool) to be exceeded.</td>
</tr>
<tr>
	<td><code>MAX_SIZE_LIMIT_REACHED</code></td>
	<td>Fired when a check-out request causes the pool's maximum size limit (maxconn) to be reached.</td>
</tr>
<tr>
	<td><code>MAX_SIZE_LIMIT_ERROR</code></td>
	<td>Fired when a check-out request is made but the pool's maximum size limit (maxconn) has been reached.</td>
</tr>
<tr>
	<td><code>VALIDATION_ERROR</code></td>
	<td>Fired when a connection cannot be validated (when the isValid(...) method call fails).</td>
</tr>
<tr>
	<td><code>PARAMETERS_CHANGED</code></td>
	<td>Fired when the pool's parameters have been changed.</td>
</tr>
<tr>
	<td><code>POOL_RELEASED</code></td>
	<td>Fired when a pool has been released. No more events are fired following this one, as all listeners are deregistered automatically.</td>
</tr>
</table>
</blockquote>
<p>The event notification is synchronous, therefore registered listeners should make sure that code executed in their event-handling methods is executed quickly. Code that requires more time should spawn a separate thread to avoid disrupting the pooling mechanism.</p>


<h4>Debugging</h4>
<p>There is an extra property that can be set to allow more detailed debug information about the pooling mechanism to be output to the log file. To enable this add the following property:</p>
<pre>
	&lt;poolname&gt;.debug=true
</pre>

<p>or invoke the <code>setDebug(true)</code> method on a ConnectionPool instance.<br> <i>Note, this is for debugging purposes only, and in a deployment environment it is likely to impact performance.</i></p>


<hr size="1">


<a name="Notes"></a><h3>Notes &amp; Troubleshooting</h3>

<h4>CLASSPATH problems? Unable to find properties file?</h4>
<p>With some application servers the CLASSPATH variable is less than obvious. Due to the need for segregation of both resources and security policies they very often use separate classloaders which only permit loading of classes and resources from specific locations. Not surprisingly this is vendor-specific, and the only way to really get to grips with the problem is to thoroughly read the documentation provided with the application server. If it helps to diagnose the problem the pool manager uses the following syntax to obtain a locate the properties file:</p>
<pre>
	ConnectionPoolManager.class.getResourceAsStream(filename)
</pre>
<p>where <code>filename</code> is prepended with a &quot;/&quot; character to ensure it is accessed directly. The default properties file is therefore accessed using the call: <code>Class.getResourceAsStream(&quot;/dbpool.properties&quot;)</code>. Bear in mind that different classloaders provided by vendors may well not conform to the standard resource-finding mechanism as used by the system classloader, but this should help in tracking down problems.</p>

<p>Alternatively you can simply use one of the other methods of specifying properties to the ConnectionPoolManager, either referencing a specific file, or passing a Properties object. See the <a href="#ConnectionPoolManager">ConnectionPoolManager</a> section for more details.</p>

<h4>Connection Creation</h4>
<p>This is how the connection pool tries to establish new database connections:</p>
<pre><ol>
<li>if Properties object used
<li>    use <code>DriverManager.getConnection(url, properties)</code>
<li>else if username specified
<li>    use <code>DriverManager.getConnection(url, username, password)</code>
<li>    if this fails
<li>        use <code>DriverManager.getConnection(url)</code>
<li>else
<li>    use <code>DriverManager.getConnection(url)</code>
</ol></pre>

<p>This pseudo-code may help debug certain problems when using the pooling system.</p>

<h4>Bad statement caching performance</h4>
<p>If you experience bad statement caching performance, as indicated when debugging is enabled, it is likely that statements are not being explicitly closed. To be recycled, statements must be closed so that the pool knows they can be reused, otherwise it assumes they are still in use.</p>



<hr size="1">


<a name="Changes"></a><h3>Latest Changes</h3>

<table border="1" cellspacing="0" cellpadding="3">
<tr><td>21/07/2006<br>(v4.8.3)</td><td><ul>
	<li>Workaround for locale-specific exceptions during date-formatting of log entries.
	<li>Bug fix for recycling problem when connection's type map is null.
</ul></td></tr>
<tr><td>31/05/2006<br>(v4.8.2)</td><td><ul>
	<li>Bug fix for handling of non-cached statements on connection closure/destruction.
</ul></td></tr>
<tr><td>07/04/2006<br>(v4.8.1)</td><td><ul>
	<li>Moved pool initialization from ConnectionPool to ObjectPool to provide a generic implementation.
	<li>Added ability to better specify method of item retrieval from pool (LIFO, FIFO, random).
	<li>Added option to override default log file for each pool if required.
	<li>Bug fix to avoid deadlock when statement caching is disabled.
	<li>Bug fix for statements sometimes not getting recycled correctly after first use.
</ul></td></tr>
<tr><td>01/12/2005<br>(v4.8)</td><td><ul>
	<li>Added support for caching of non-standard statement types (type/concurrency/holdability).
	<li>Bug fixes in CacheConnection class.
</ul></td></tr>
<tr><td>14/11/2005<br>(v4.7.2)</td><td><ul>
	<li>Fixed a memory leak in CacheConnection class.
	<li>Fixed a bug which set expiry to zero when maxpool=maxconn in pool manager.
	<li>Changed default internal pool access method to LIFO instead of FIFO (better performance in low-load situations).
</ul></td></tr>
<tr><td>22/12/2004<br>(v4.7.1)</td><td><ul>
	<li>Bug fix to ObjectPool hit rate counting.
	<li>Bug fix to ConnectionPoolManager's logging mechanism. (Note: logging on new standalone ConnectionPools is now off by default, and should be enabled using one of the setLog() methods if required.)
</ul></td></tr>
<tr><td>14/12/2004<br>(v4.7)</td><td><ul>
	<li>Bug fix for CacheConnection statement caching which prevented correct disabling of caching.
	<li>Changed logging in ConnectionPoolManager to support PrintStream instead of PrintWriter for more generalized stream support.
	<li>Added support for pool event listeners.
	<li>Added support for encoding of passwords in properties files.
</ul></td></tr>
<tr><td>06/10/2004<br>(v4.6.2)</td><td><ul>
	<li>Updates to ConnectionPoolManager to allow more flexibility in specifying properties for initialization.
	<li>Bug fix to ensure statements are released correctly if statement caching is disabled on a connection after initialization.
	<li>Bug fix for connection creation which set statement caching based only on normal statements.
	<li>Finally added versioning to make life easier for everyone!
	<li>Changes and clarifications to documentation.
</ul></td></tr>
<tr><td>12/07/2004<br>(v4.6.1)</td><td><ul>
	<li>Bug fix for previous release which caused slowdown with large pool expiry values.
</ul></td></tr>
<tr><td>08/07/2004<br>(v4.6)</td><td><ul>
	<li>Several access-level changes to clarify recommended use of ObjectPool.
	<li>Better check-in logic to avoid unnecessary disposal of some items
	<li>Addition on connection validation at connection creation
	<li>Removed redundant PoolSystem interface (it was allowing incorrect use of freeConnection(); only required to solve circularity in compilation, so now when compiling from source all files should be compiled at once)
	<li>Overhaul of pool synchronization mechanism in response to several more reported deadlock situations
</ul></td></tr>
<tr><td>02/06/2004<br>(v4.5.5)</td><td><ul>
	<li>Minor adjustments to multithreading of cleaner thread causing possible deadlock in some circumstances.
</ul></td></tr>
<tr><td>11/05/2004<br>(v4.5.4)</td><td><ul>
	<li>Fixed a bug with connection initialization in new pools (sometimes causing deadlock).
	<li>Fixed a small problem with exception generation when problems encountered getting connections.
</ul></td></tr>
<tr><td>21/04/2004<br>(v4.5.3)</td><td><ul>
	<li>Fixed a synchronization bug in ObjectPool code.
	<li>Fixed a minor ConnectionPoolManager bug relating to reading a null validator from the properties file.
</ul></td></tr>
<tr><td>07/04/2004<br>(v4.5.2)</td><td><ul>
	<li>Fixed a synchronization bug in ObjectPool.Cleaner which sometimes caused hangups on returned connections.
	<li>Fixed bug in ObjectPool checkOut method to more reliably return valid connections.
</ul></td></tr>
</table>
<br>



<!-- End main page here  -->

<hr size="1">
</td></tr></table>
</div>
</body>
</html>