SmartPool 1.1 User Documentation
Every documented bug becomes a feature

Introduction

Loading SmartPool

Accessing Connections from the pool.

Detecting leaks

Monitoring Pool Status

Automatic closing of associated Statements, PreparedStatements, and CallableStatements

Wrapping SmartPool to an existing pool

DTD for configuration file

Sample Configuration file

Sample ConnectionProvider Implementation

API Documentation

Glossary

Introduction

     SmartPool is a connection-pooling component modeled on connection pooling features provided by an Application Server. SmartPool makes an attempt to solve critical issues like connection leaks, connection blocking, open JDBC objects like Statements, PreparedStatements etc. Features of SmartPool include support for multiple pools, automatic closing of associated JDBC objects, detect connection leaks based on configurable time-outs, track connection usage, wrap SmartPool to an existing pool, monitor run time status of the pools apart from conventional pooling support. 

Loading SmartPool

Using the PoolManager: PoolManager is an interface defining the behavior of the class that manages each Pool. You can load the SmartPool component by using the following:

PoolManager pm = new PoolManagerImpl("/home/ssshetty/pool-config.xml");

Once the PoolManger is instantiated you can call the methods on the PoolManager interface with the following:

String poolName = "MyPool";
Connection conn = pm.getConnection(poolName);

          For more details refer to Java Documentation of PoolManager Interface.

Note: You are creating an Instance of a PoolManager, which is not Singleton by itself, and thus multiple PoolManager instances would result in multiple pools.

Using SmartPoolFactory: SmartPoolFactory provides a Singleton access to SmartPool. This is a Singleton Wrapper to the PoolManagerImpl. This is the recommended way to load the Pool.

SmartPoolFactory smp = new SmartPoolFactory("/home/pool-config.xml");

This would create a Singleton object smp in the memory. Static methods on this object can be invoked from any class loaded within the same JVM.

Connection con = SmartPoolFactory.getConnection();

Note: Static methods on SmartPoolFactory can only be used after it is initialized with a configuration file as shown above. It is recommended to load this SmartPoolFactory in memory on your application start-up  (like the start-up servlet in a web application).
For more details refer to Java Documentation of SmartPoolFactory.

 Accessing Connections from the pool

Connection can be accessed from the PoolManager/SmartPoolFactory depending on the method you have used to load the pool. The following examples are applicable when you use SmartPoolFactory.
You can draw connections from the pool is the following way:

Connection conn = SmartPoolFactory.getConnection();

This fetches a connection from the default pool, with owner set to N/A i.e. Not Applicable

Default Pool: Default pool is one where is set to default-pool="true" in the configuration file. In a simple application where only one pool is required and no ownership is to be tracked, developers need not provide the pool name each time they take a connection from the pool. At most one pool can be marked as a default pool.

Owner: Owner is the identity of the user/class drawing the connection from the pool. Ownership is used for debugging while detecting connection leaks to exactly identify the owners of connections. Preferably this should be a combination of the class and method that is drawing the connection since this would directly help in attacking and solving the problem of Connection leaks.

Anonymous Connection: A connection drawn from the pool without specifying the owner name is an anonymous connection. It is not possible to keep track of ownerships if anonymous connections are allowed.

To disallow anonymous connections set allow-anonymous-connections="false" in the configuration file.

Other methods to get Connections are:

Connection conn = SmartPoolFactory.getConnection("poolName");

Here “poolName” is the pool name.

Connection conn = SmartPoolFactory.getConnection("poolName", “TestSmartPool:getMyConnection”);

Here TestSmartPool:getMyConnection is the owner name.

Releasing Connection to the pool:
To release connection to the Pool just call close on the method.

Connection conn = SmartPoolFactory.getConnection("poolName")
....
....
conn.close();

This will return the connections to the pool.

Following things are worth noting when a connection is released:

• If auto-commit is set to false for the connection, SmartPool will call rollback on that method and set auto-commit to true. This is to destroy the existing state of the connection before it is made available to others.

•  If auto-close="true" in the configuration file, all the associated Statements, PreparedStatements, and CallableStatements will be closed when the connection is released to the pool.
   

Detecting Leaks

Leak detection is time-out based.

leak-time-out="100"

To set a time-interval of 100 seconds for which a class can hold the connection without being considered as leak set leak-time-out="100".
A Connection Leak is said to have occurred when a class is holding on to a connection for more than the leak-time-out.

     poll-thread-time = "100”
A leak detector Poll thread will poll all used connections every 100 seconds. As soon as the leak detector Poll thread finds out a Connection leak, it will notify all the registered connection leak listeners.

Connection leak listener is a class implementing the ConnectionLeakListener interface. Connection leak listener class receives a notification of a leak through the following call back method:
     public void connectionTimeOut(ConnectionLeakEvent cle)
Where ConnectionLeakEvent is the class encapsulating the information about the leak.
See Java documentation of ConnectionLeakEvent, ConnectionLeakListener for more info.  

You can register a ConnectionLeakLister by calling the following method on PoolManager/SmartPoolFactory
     PoolManager.addConnectionLeakListener(ConnectionLeakListener cle);

You can also provide a default listener in the configuration file.
     For e.g.     default-listener="testconnectionpool.LeakDetector"
PoolManager will load this listener on load and it will be able to listen to leaks right from the instance PoolManager object is created.

NOTE: The connection leak event will also provide you with access to the actual Connection object which you can be returned back to the pool by calling close() in it, however be sure of what you are doing, because this may result in functionality bugs which would be very difficult to debug.

    Monitoring Pool Status

Monitoring Interfaces allows you to keep track how the connections are being used, who is blocking up the Connections, detect leaks if any, thus helping in identifying and attacking problems where the application/system crashes because of excessive connections or tables get locked etc.

To monitor the Pools you can use the Following method
          PoolMonitor pm = SmartPoolFactory.getPoolMonitor("Sachin");
     PoolMonitor is an interface defining methods to monitor the current status of the pool.

To get the Configuration of the pool, use the following method
    ConfigMonitor cm = pm.getConfigMonitor();
ConfigMonitor provides access to pool configuration.

To get information on the Connections being used
                Vector v = pm.getConnectionsInUse();
         This will return a vector of ConnectionMonitor providing all the information about the connection in use.

For more information see Java Documentation of PoolMonitor, ConfigMonitor, ConnectionMonitor.

     Automatic closing of associated Statements, PreparedStatements, and CallableStatements  

If auto-close="true" in the configuration file then all the Statements, PreparedStatements, and CallableStatements associated with a Connection will be closed when the connection is released to the pool.

    Wrapping SmartPool to an existing pool  

Wrapping SmartPool to an existing pool implies that SmartPool will not draw raw connections to the database; it would rather draw connections from another connection pool, for e.g. DataSource from an Application Server.

In this case SmartPool does not maintain any pool, it simply delegates the connection requests to the parent pool. SmartPool however keeps a track of connections in use, and thus can be used for leak detecting, automatic closing of associated Statements, PreparedStatements, CallableStatements objects.

SmartPool can be wrapped to an existing pool with the help of the interface ConnectionProvider. ConnectionProvider provides two methods

public Connection getConnection() throws Exception

This method should return a connection from the pool to which SmartPool is wrapped.

public void returnConnection(Connection conn) throws Exception

This method should return the connection conn back to the parent pool.

For more information see Java Documentation of ConnectionProvider.
 

To wrap smart pool to an existing pool, you need to write an implementation of ConnectionProvider and provide the fully qualified class name in the configuration file.

For e.g. If the class implementing ConnectionProvider is com.your_company.your_project.SampleConnectionProviderImpl, then in the configuration file, you will have to put the following entry.

connection-loader-class= "com.your_company.your_project.SampleConnectionProviderImpl"

 DTD for configuration file

    $EXTRACT_DIR/samples/pool-config.dtd

 Sample Configuration file

    $EXTRACT_DIR/samples/pool-config.xml

Sample ConnectionPrvider Implementation

    $EXTRACT_DIR/samples/SampleConnectionProviderImpl.java

Java/API Documentation

    $EXTRACT_DIR/doc/java_doc

     Glossary

Consumer: Consumer is a class/component that draws connections from the SmartPool.

Default Pool: Default pool is the pool where you have said default-pool="true" in the configuration file. Thus in a simple application where only one pool is required and no ownership is to be tracked, developers need not provide the pool name each time they take a connection from the pool. Only one pool can be marked as a default pool at the most.

Owner: Owner is an identity of the user/class drawing the connection from the pool. This is used for debugging while detecting connection leaks so as to exactly identify who is blocking the connections. Preferably this should be a combination of the class and method that is drawing the connection as this would directly help in attacking and solving the problem of Connection leaks.

Anonymous Connection: An anonymous connection is a connection drawn from the pool without specifying the owner name. Hence not possible to keep track of where the connection is being blocked.

When allow-anonymous-connections="false" in the configuration file, anonymous connections are not allowed.

Connection Leak: When a Consumer holds on to a connection for more than the time specified in leak-time-out in configuration file, a connection leak is said to have occurred and the Consumer is the owner of the connection and is responsible for the connection leak.