JMS connection pool error handling

Connection pool error handling is carried out by various methods of a purge policy.

• Close only the connection that encountered the problem. This is known as the FailingConnectionOnly purge policy and is the default behavior.

  Any other connections created from the factory, that is, those in use by other applications, and those that are in the free pool of the factory, are left alone.

• Close the connection that encountered the problem, throw away any connections in the free pool of the factory, and mark any in-use connections as stale.

  The next time the application that is using the connection tries to perform a connection-based operation, the application receives a StaleConnectionException. For this behavior, set the purge policy to Entire Pool.

Purge policy - failing connection only

Use the example described in How MDB listener ports use the connection pool. Two MDBs are deployed into the application server, each one using a different listener port. The listener ports both use the jms/CF1 connection factory.

After 600 seconds, you stop the first listener, and the connection that this listener port was using is returned to the connection pool.

If the second listener encounters a network error while polling the JMS destination, the listener port shuts down. Because the purge policy for the jms/CF1 connection factory is set to FailingConnectionOnly, the connection manager throws away only the connection that was used by the second listener. The connection in the free pool remains where it is.

If you now restart the second listener, the connection manager passes the connection from the free pool to the listener.

Purge policy - entire pool

For this situation, assume that we have three MDBs installed into our application server, each one using its own listener port. The listener ports have created connections from the jms/CF1 factory. After a period of time you stop the first listener, and its connection, c1, is put into the jms/CF1 free pool.

When the second listener detects a network error, it shuts itself down and closes c2. The connection manager now closes the connection in the free pool. However, the connection being used by third listener remains.

What should you set the purge policy to?

As previously stated, the default value of the purge policy for JMS connection pools is FailingConnectionOnly.

However, setting the purge policy to EntirePool is a better option. In most cases, if an application detects a network error on its connection to the JMS provider, it is likely that all open connections created from the same connection factory have the same problem.

If the purge policy is set to FailingConnectionOnly, the connection manager leaves all of the connections in the free pool. The next time an application tries to create a connection to the JMS provider, the connection manager returns one from the free pool if there is one available. However, when the application tries to use the connection, it encounters the same network problem as the first application.

Now, consider the same situation with the purge policy set to EntirePool. As soon as the first application encounters the network problem, the connection manager discards the failing connection and closes all connections in the free pool for that factory.

When a new application starts up and tries to create a connection from the factory, the connection manager tries to create a new one, as the free pool is empty. Assuming that the network problem has been resolved, the connection returned to the application is valid.