oracle.portal.utils.v1
Class ConnectionManager

java.lang.Object
  |
  +--oracle.portal.utils.v1.ConnectionManager

public class ConnectionManager

extends java.lang.Object

The ConnectionManager is a singleton class that manages a set of 'pooled' JDBC database connections. The ConnectionManager allows multi-threaded applications to overcome the overhead involved in repeatedly initializing and closing database connections by maintaining named 'pools' of pre-initialized connections which can grow and shrink over time as needs suit. Provided the details of each type of connection to be pooled are declared in ConnectionManager's XML configuration file, threads can gain easy access to a connection of a particular type by calling the static getConnection(String) method with the name associated with the corresponding connection pool, and can return the connection back to its pool once finished by calling the static releaseConnection(String, Connection) method.

ConnectionManager is configured through an XML file, whose location must be specified by the system property ConnectionManager.config. Typically, you would specify a value for this property when you invoke your JVM by using the -D option, e.g.:

java -DConnectionManager.config=E:\jpdk\providers\dbPersonalization\connectionManager.xml

If your JVM runs under JServ, you can specify this option in jserv.properties with the wrapper.bin.properties option, e.g.:

wrapper.bin.parameters=-DConnectionManager.config=E:\jpdk\providers\dbPersonalization\connectionManager.xml

The contents of an example XML configuration file for ConnectionManager are included below:

<connectionManager>
   <minCount>6</minCount>
   <maxCount>25</maxCount>
   <maxWaitTime>60</maxWaitTime>
   <maxIdleTime>3600</maxIdleTime>
 
   <connection>
     <name>demo</name>
     <username>scott</username>
     <password>tiger</password>
     <driver>oracle.jdbc.driver.OracleDriver</driver>
     <dburl>jdbc:oracle:thin:@localhost:1521:ORCL</dburl>
   </connection>
   <connection>
     <name>provider</name>
     <username>provider</username>
     <password>provider</password>
     <driver>oracle.jdbc.driver.OracleDriver</driver>
     <dburl>jdbc:oracle:oci8:@provider</dburl>
   </connection>
   <connection>
     <name>lite</name>
     <username>system</username>
     <password>manager</password>
     <driver>oracle.lite.poljdbc.POLJDBCDriver</driver>
     <dburl>jdbc:Polite:POlite</dburl>
   </connection>
 </connectionManager>

As illustrated, the document should contain a <connectionManager> element, below which should be a number of <connection> elements describing the properties of each type of connection to be pooled. Each element within a <connection> element corresponds to a particular property of that connection type. These are described in the table below.

Property	Default Value	Description
name	none	Name to be associated with the pool for this 'type' of connection
username	none	User name of the database account to be used by this pool
password	none	Password of the database account to be used by this pool
driver	"oracle.jdbc.driver.OracleDriver"	Full class name of the JDBC driver to be used. Note this class must be present in your CLASSPATH
dburl	none	JDBC URL to the database (e.g. jdbc:oracle:oci8:@tiger). Consult the documentation for JDBC driver you intend to use for details on the format of this URL.
minCount	5	Minimum number of connections in this pool. This will be the number of connections initialized when this pool is first accessed, and the minimum number of connections maintained in the pool throughout its lifetime. Connections above this minimum number will be removed from this pool if they remain unused for a period in seconds greater than maxIdleTime (see below).
maxCount	25	Maximum number of connections in this pool. If the pool ever reaches this size and a request is made for another connection, then the request will be blocked until a connection has been returned to the pool or the maxWaitTime timeout period has expired.
maxWaitTime	20 seconds	The maximum number of seconds to wait for a connection to be returned to the pool.
maxIdleTime	3600 seconds (1 hour)	The maximum number of seconds that a connection should be kept in the pool for since it was last used.

Within the top-level <connectionManager> element, 'defaults' for the minCount, maxCount, maxWaitTime, and maxIdleTime connection properties can also be specified, which are 'inherited' by all <connection> elements for which the corresponding property is not specified.

Method Summary

static java.sql.Connection	getConnection(java.lang.String pool) Get a JDBC connection from the pool of the given name.
static void	releaseConnection(java.lang.String pool, java.sql.Connection conn) Return a JDBC connection to the pool of the given name.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getConnection

public static java.sql.Connection getConnection(java.lang.String pool)
                                         throws ConnectionManagerException,
                                                java.sql.SQLException

Get a JDBC connection from the pool of the given name. Any Connection obtained from this method must later be retured with releaseConnection(String, Connection), even if normal execution is interrupted by an exception. This is typically achieved by puting the releaseConnection call in a finally{} code block.

Parameters:

pool - name of one of the pools managed by this ConnectionManager from which the connection should be retrieved.

Returns:

a JDBC connection

Throws:

ConnectionManagerException - if an error occurs whilst initializing this ConnectionManager

java.sql.SQLException - if an error occurs whilst getting a Connection from the pool.

releaseConnection

public static void releaseConnection(java.lang.String pool,
                                     java.sql.Connection conn)

Return a JDBC connection to the pool of the given name.

Parameters:

pool - name of one of the pools managed by this ConnectionManager from which the connection was obtained.

conn - a Connection obtained from the pool with getConnection(String).