<th>Method of Access</th>
	<th>Explanation</th>
</tr>
<tr>
	<td><code>getInstance()</code>*</td>
	<td>Returns the pool manager instance as defined by the default properties file (dbpool.properties) which is located in the CLASSPATH (or equivalent location for specific host system)<sup>+</sup>.</td>
</tr>
<tr>
	<td><code>getInstance(String)</code>*</td>
	<td>Returns the pool manager instance as defined by the properties file with the filename specified, located in the CLASSPATH (or equivalent location for specific host system)<sup>+</sup>.</td>
</tr>
<tr>
	<td><code>getInstance(File)</code>*</td>
	<td>Returns the pool manager instance as defined by the properties file specified.</td>
</tr>
<tr>
	<td><code>createInstance(Properties)</code> followed by <code>getInstance()</code>*</td>
	<td>Creates a pool manager instance from the specified Properties object and makes it available via the <code>getInstance()</code> method.</td>
</tr>
<tr><td colspan="2">*<i>Note 1: Each of these methods can throw an IOException if there is a problem loading the properties from the file.</td></tr>
<tr><td colspan="2"><sup>+</sup><i>Note 2: Application servers often specify user-accessible areas differently from the CLASSPATH variable. For example, when used with Apache Tomcat it can be placed in the &lt;webapp&gt;/WEB-INF/classes directory.</td></tr>
</table>
</blockquote>

<p><i><b>Important:</b> It is not possible to use both a default properties file instance and a Properties object instance simulteneously. If the default properties file instance is obtained and not released, a call to createInstance(Properties) will fail with a RuntimeException. Aside from this limitation multiple instances of ConnectionPoolManagers can be obtained and used, each with it's own parameters.</i></p>

<p>Using these various instance accessors you have access to a theoretically unlimited number of different pool managers, although in reality using more than just one is rare.</p>

<p>So, to obtain the pool manager defined by the default properties file us:</p>
<pre>
	ConnectionPoolManager cpm = null;
	try
	{
		cpm = ConnectionPoolManager.getInstance();
	}
	catch (IOException ioe)
	{
		...
	}
</pre>

<p>This step would normally be done at the initialization stage of an application. For instance, in a web application the pool manager could be created and assigned to an application scope variable, where it could be accessed by other classes which require database access.</p>

<p>Once a reference to a pool manager has been obtained you can now checkout/checkin (obtain/return) connections from/to it's pools. To obtain a connection use the getConnection(&lt;poolname&gt;) method. This method will obtain a database connection if one is immediately available, or return null if not. If you would rather wait a certain amount of time in case a connection becomes available use the getConnection(&lt;poolname&gt;, timeout) instead, where <i>timeout</i> is specified in milliseconds. If a connection becomes available within the timeout the method will return with the connection, otherwise null is returned. Once you have finished with this connection you simply close it as you would a normal connection. On closing the connection it is cleaned up and then returned to the pool for re-use.</p>

<p>For example, the following code obtains a connection from the ConnectionPoolManager, performs some operations, then returns the connection.</p>
<blockquote><pre>
	Connection con = null;
	long timeout = 2000;  // 2 second timeout
	try
	{
	  con = cpm.getConnection(&lt;poolname&gt;, timeout);
	  if (con != null)
	    <i>...use the connection...</i>
	  else
	    <i>...do something else (timeout occurred)...</i>
	}
	catch (SQLException sqle)
	{
	  <i>...whatever...</i>
	}
	finally
	{
	  try { con.close(); }
	  catch (SQLException e) { ... }
	}
</pre></blockquote>

<p>Notice that when you have finished working with a connection you simply call it's close() method as you would normally. Instead of being closed the connection is actually recycled within the pool ready to be used again.</p>

<p>When you have completely finished with all the pools managed by a ConnectionPoolManager object you should release it to ensure all of the resources it is using are released. This is done using the call:</p>
<blockquote><pre>
	cpm.release();
</pre></blockquote>

<p>which if necessary shuts down the pools and releases the resources held by the pool manager.</p>

<h4>Important Notes about ConnectionPoolManager</h4>

<p>Every successful call to one of the getInstance() methods increases an internal counter of the number of clients which hold a reference to that pool manager. A call to release() decrements this client counter. If the counter hits zero then the pool manager shuts down all it's connection pools and cleans up all it's resources. Any database connections referred to by the underlying pools that are still open may be forcibly closed by this operation, which could have undesirable effects. Therefore is it recommended (and good programming practice) to ensure that all your connections are closed when no longer needed.</p>

<p>What this means is that you need to keep a careful track of the references to each pool manager created. Each call to getInstance() should be matched by a call to release() for that pool manager, but it is a good idea to keep a global reference within an application for as long as the database access is required, to avoid unnecessary destruction and new creation of the pool manager.</p>




<a name="properties"></a><h3>Defining the behaviour of the pool</h3>

<p>The behaviour of the pools used by the ConnectionPoolManager is governed by either a properties file (by default called <b>dbpool.properties</b>) or by a Properties object supplied by the user.</p>

<p>The format of the properties file is shown below. The same key/value pairs apply when specifying a pool manager using a Properties object.</p>
<blockquote><pre>
	 drivers=&lt;fully-qualified class name of driver&gt;
	 logfile=&lt;filename&gt;

	 &lt;poolname&gt;.url=&lt;JDBC connection URL for database&gt;
	 &lt;poolname&gt;.user=&lt;user name&gt;
	 &lt;poolname&gt;.password=&lt;password&gt;
	[&lt;poolname&gt;.maxpool=&lt;maximum pooled connections&gt;]
	[&lt;poolname&gt;.maxconn=&lt;maximum possible connections&gt;]
	[&lt;poolname&gt;.expiry=&lt;expiry time of connections (seconds)&gt;]
	[&lt;poolname&gt;.init=&lt;initial number of connections&gt;]
	[&lt;poolname&gt;.validator=&lt;fully-qualified classname of ConnectionValidator&gt;]
	[&lt;poolname&gt;.decoder=&lt;fully-qualified classname of PasswordDecoder&gt;]
	[&lt;poolname&gt;.cache=true/false]
	[&lt;poolname&gt;.debug=true/false]
	[&lt;poolname&gt;.prop.<i>property</i>=<i>value</i>]
</pre></blockquote>

<p>Those properties in [brackets] are optional and take on default values when not supplied as described in the table below. Inevitably is is worthwhile supplying values for at least <code>maxpool</code> and <code>maxconn</code>, or you will get no benefit from the pooling system.</p>

<blockquote>
<table border="1" cellspacing="0" cellpadding="3" width="100%">
<tr>
	<th>Property</th>
	<th>Purpose</th>
	<th>Possible values</th>
	<th>Default value</th>
</tr>
<tr>
	<td>maxpool</td>
	<td>Determines the maximum number of connections that are held in the pool</td>
	<td>integer, &gt;=0<br>(&gt;=minpool)</td>
	<td>0</td>
</tr>
<tr>
	<td>maxconn</td>
	<td>Determines the absolute maximum number of connections that can be created for use</td>
	<td>integer, &gt;=0<br>(&gt;=maxpool)</td>
	<td>0 - unlimited</td>
</tr>
<tr>
	<td>expiry</td>
	<td>The expiry time for individual connections that are unused (seconds)</td>
	<td>integer, &gt;=0</td>
	<td>0 - no expiry</td>
</tr>
<tr>
	<td>init</td>
	<td>Initial a number of connections on startup (if more than minpool required)</td>
	<td>integer, &gt;=0<br>(&lt;=maxpool)</td>
	<td>0 - none</td>
</tr>
<tr>
	<td>validator</td>
	<td>Determines how to ensure that connections are valid</td>
	<td>Java class name<br>(must implement ConnectionValidator)</td>
	<td>none - validates with <code>Connection.isClosed()</code></td>
</tr>
<tr>
	<td>decoder</td>
	<td>Allows use of a custom password decoder class</td>
	<td>Java class name<br>(must implement PasswordDecoder)</td>
	<td>none - no password encoding supported</td>
</tr>
<tr>
	<td>cache</td>
	<td>Option to turn off caching of statements</td>
	<td>true/false</td>
	<td>true</td>
</tr>
<tr>
	<td>debug</td>
	<td>Option to turn on debug information in the log file</td>
	<td>true/false</td>
	<td>false</td>
</tr>
<tr>
	<td>prop.<i>property</i></td>
	<td>Optional properties to be passed to the JDBC driver</td>
	<td>string</td>
	<td>&nbsp;</td>
</tr>
<tr><th colspan="4" align="left">In addition there are a few properties which control advanced features for each pool:</th></tr>
<tr>
	<td>async</td>
	<td>Option to turn on asynchronous destruction of invalid/dead connections</td>
	<td>true/false</td>