Object pooling in a Java EE environment

Java EE application servers provide connection pooling functionality that can be used by message-driven bean applications, Enterprise Java Beans and Servlets.

WebSphere® Application Server maintains a pool of connections to a JMS provider, in order to improve performance. When an application creates a JMS connection, the application server determines if a connection already exists in the free connection pool. If so, the connection is returned to the application; otherwise, a new connection is created.

Figure 1 shows how both activation specifications and listener ports establish a JMS connection and use that connection to monitor a destination for messages in normal mode.
Figure 1. Normal mode
A flowchart showing how activation specifications and listener ports establish a JMS connection and use that connection to monitor a destination for messages.

When using the IBM® MQ messaging provider, applications that perform outbound messaging (such as enterprise Java Beans and servlets), and the message-driven bean listener port component, can make use of these connection pools.

IBM MQ messaging provider activation specifications use connection pooling functionality provided by the IBM MQ resource adapter. See Configuring properties for the WebSphere MQ resource adapter for more information.

Examples of using the connection pool explains how applications that perform outbound messaging, and listener ports, use the free pool when creating JMS connections.

Free connection pool maintenance threads explains what happens to these connections when an application, or listener port, has finished with the connections.

Pool maintenance thread examples explains how the free connection pool is cleaned to prevent JMS connections from becoming stale.

WebSphere Application Server has a limit on the number of connections that can be created from a factory, specified by the maximum connections property of the Connection Factory. The default value for this property is 10, which means there can be up to 10 connections created from a factory at any one time.

Each factory has an associated free connection pool. When the application server starts up, the free connection pools are empty. The maximum number of connections that can exist in the free pool for a factory is also specified by the Maximum connections property.

Tip: With JMS 2.0, a connection factory can be used to create both connections and contexts. As a result, it is possible to have a connection pool associated with a connection factory that contains a mixture of both connections and contexts. It is recommended that a connection factory is only used for creating connections or creating contexts. This ensures that the connection pool for that connection factory only contains objects of a single type, which makes the pool more efficient.

For information about how connection pooling works in WebSphere Application Server, see Configuring connection pooling for JMS connections. For other application servers, refer to the appropriate application server documentation.

How the connection pool is used

Every JMS connection factory has a connection pool associated with it, and the connection pool contains zero or more JMS connections. Every JMS connection has an associated JMS session pool, and every JMS session pool contains zero or more JMS sessions.

Figure 2 shows the relationship between these objects.
Figure 2. Connection pools and session pools
A flowchart showing the relationship between JMS connections and sessions
When a listener port starts up, or an application that wants to do outbound messaging uses the factory to create a connection, the port or application calls one of the following methods:
  • connectionFactory.createConnection()
  • ConnectionFactory.createConnection(String, String)
  • QueueConnectionFactory.createQueueConnection()
  • QueueConnectionFactory.createQueueConnection(String, String)
  • TopicConnectionFactory.createTopicConnection()
  • TopicConnectionFactory.createTopicConnection(String, String)
The WebSphere Application Server connection manager tries to obtain a connection from the free pool for this factory, and return it to the application.

If there are no free connections in the pool, and the number of connections created from this factory has not reached the limit specified in the maximum connections property of that factory, the Connection Manager creates a new connection for the application to use.

However, if an application attempts to create a connection, but the number of connections created from this factory already is equal to the maximum connections property of the factory, the application waits for a connection to become available (to be put back in the free pool).

The time that the application waits is specified in the connection timeout property of the connection pool, which has a default value of 180 seconds. If a connection is put back in the free pool within this 180 second period, the Connection Manager immediately takes it out of the pool again and passes it to the application. However, if the timeout period elapses, a ConnectionWaitTimeoutException is thrown.

When an application has finished with the connection and closes it by calling:
  • Connection.close()
  • QueueConnection.close()
  • TopicConnection.close()
the connection is actually kept open, and is returned to the free pool so that it can be reused by another application. Therefore, you can have connections open between WebSphere Application Server and the JMS provider, even if no JMS applications are running on the application server.