User Documentation for SmartPool 1.0

 

 

·         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

·         About the Author

 

 

·         Introduction

SmartPool is a connection-pooling component that is modeled on connection pooling features provided by an Application Server. It 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 the Pools. You can load the SmartPool component by using the following:

PoolManager pm = new PoolManagerImpl("/home/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 connection pools.

Using SmartPoolFactory:

SmartPoolFactory provides a Singleton access to SmartPool. This is a Singleton Wrapper to the PoolManagerImpl, 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 in your application start-up itself (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 chosen to load the pool. Once you have loaded the Pool you can draw connection 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 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.

Other methods to get Connection are

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

Here “poolName” is the pool name

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

Here TestSmartPool 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.
1) If auto-commit is set to false for the connection, it 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.
2) 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.

Leak detection is time-out based.

leak-time-out="100"

In the configuration file defines the time-interval of 100 seconds for which a class can hold the connection without being considered as leak.

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”

The leak detector Poll thread will poll all the used connection 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.

A connection leak listener is a class implementing the ConnectionLeakListener interface. The 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 word go.

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 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.
 

 

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 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 ConnectionProvider Implementation

$EXTRACT_DIR/samples/SampleConnectionProviderImpl.java

·        Java/API Documentation
          $EXTRACT_DIR/doc/java_doc

 

 

 

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.

 

 

·        About the Author
I am B.E from Bombay University (wasted four years), started of my career in August 2002 and since then have changed three organizations and right now working with an MNC in Hyderabad. I am pretty good with Linux, PERL and J2EE (I call myself a J2EE Champ, don’t want to pursue it for long time though). I also have a handful of stupid Java and J2EE certification to fool employers. Employers hire me because they believe in the popular saying “ If you cant fight them, hire them “.

I idolize: Linus Torvalds and Ramnath Payade and all illiterate achievers.

I am insane for: Aishwarya rai.

I hate: Rank and Certification holders.
A question for windows fans: Have you seen anything else?
A word for Managers: “ Its easy to walk on water and work on a specification, provided they are frozen. “
A word for EMACS fans: “ EMACSè Eight Megabytes And Constantly Swapping “

Smartest Shell Script: “#!/bin/rm”, guess what it does.

Finally my advice:

“ In the middle of sea of difficulties, there lies a pool of oppurtunities, oppurtunities to grow, oppurtunities to perform, oppurtunities to prove that you are above the rest. “

If the above does not work for you:

“ Don’t worry too much about your work, you are not paid enuf for that.“

Feel free to email me at sachintheonly@yahoo.com (I have my filters in place).