The PooledConnectionFactory class is our entry point into the pooling library; applications that use it generally create one PooledConnectionFactory instance and share it throughout the application code. PooledConnectionFactory exposes a number of configuration options to control how the Connection instances it creates behave. By default, PooledConnectionFactory creates a single Connection instance and returns that same instance every time the createConnection() methods are called.

Some applications, such as the example used in this recipe, can benefit from having more than one Connection instance in the pool, and it's easy enough to configure this using the factory's setMaxConnections() method. When the pool contains more than one connection, the connections are handed out in a round robin manner each time a create call is made; this provides a bit of load balancing across the connections for the resources created by each.

Each time the PooledConnectionFactory instance is asked to create a connection it returns a PooledConnection instance that refers to one of the real connections in the pool. PooledConnection manages its own set of sessions in a session pool similar to the connection pool. Unlike the pooled connections, however, the sessions that are pooled in the connection are not shared; each call to create a session either returns a new session or a free one from the pool. The maximum number of sessions that PooledConnection will create is configurable, as is the behavior. When the maximum number has been reached, the code can either block any more sessions or it can throw an exception to indicate no more sessions can be created.

PooledSession also does its own sort of pooling for the MessageProducer objects it's asked to create. However, it is a bit different from the other object pools. Since a MessageProducer object can be created to be an anonymous producer and sent to any destination, the session creates a special wrapper that caches the destination your code asked it to associate with a JMS MessageProducer and always uses that cached destination to perform a send using a single MessageProducer instance, thereby saving the overhead of creating many different producer objects. While this still results in the allocation of objects on the client side, it saves the cost of the network overhead needed to register a new producer on the broker.

All of this may sound complicated but it's really not that bad. The classes in the pooling library behave pretty much the same as their pure JMS client counterparts. What you need to keep in mind is that when you close a PooledSession instance you close its cached producer, and when you close a PooledConnection instance you close all those PooledSession instances. The code that uses these types needs to ensure that it's taking advantage of the properties of the pooled library in a way that makes sense, otherwise it won't perform any better than the non-pooled JMS client code and could perform worse in some cases.

The example application we ran earlier performed significantly better using the pooling library than it did using the plain ActiveMQ JMS client library code. Let's look at what the sample does and why it performs so much better.

The example application creates a ThreadPoolExecutorService instance that has a fixed thread pool of 10 and a PooledConnectionFactory instance which also sets its max connections to 10. The example then places 1,000 tasks into the executor; we show a portion of that code here:

connectionFactory = new ActiveMQConnectionFactory(connectionUri);
pooledFactory = new PooledConnectionFactory(connectionFactory);
…
ExecutorService service = Executors.newFixedThreadPool(10);

for (int i = 0; i < 1000; ++i) {
    service.execute(new Sender(factory.createConnection()));
}

As you can see, each of the queued tasks is given a connection from the ConnectionFactory instance we created. In the non-pooled case, we would be opening a large number of connections; this is not ideal as it involves a lot of network overhead adding each new connection to the broker. Each task in the executor then creates a session and sends some messages; let's take a look at that code now:

Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
for (int i = 0; i < 20; i++) {
    Destination destination = session.createTopic("TestTopic" + i);
    MessageProducer producer = session.createProducer(destination);
    producer.send(session.createMessage());
    producer.close();
}

As you can see, our task creates a session and then loops 20 times creating a MessageProducer instance each time in order to send to a specific destination on each send. In the non-pooled case, we'd be creating 20 MessageProducer objects in every loop and every task would create its own session. In the pooled case, though, we only create one session in each of the 10 connections and each session only creates one MessageProducer instance for each task as they are executed.

This example represents a worst-case scenario of bad JMS code that creates a lot of resources and destroys them without consideration for performance or resource utilization. It's because of this bad implementation that we see such a huge difference in performance between the pooled and non-pooled cases, but it makes clear the benefit of applying connection pooling in the right situations.

Once our example application finishes its work, it shuts down using the same style as our other examples by calling its after() method to clean up. Since we are using PooledConnectionFactory as opposed to the normal ActiveMQConnectionFactory, instance we need to ensure that those connections in the pool get shut down cleanly; we do that by calling the clear() method on PooledConnectionFactory; the code is shown here:

    public void after() throws Exception {
        pooledFactory.clear();
        broker.stop();
    }

Before we leave this section, it's good to note that we needed to update our standard Maven POM file for this project to make use of the ActiveMQ pooling library. We need to add one more dependency to our project. The XML is shown here:

    <dependency>
      <groupId>org.apache.activemq</groupId>
      <artifactId>activemq-pool</artifactId>
      <version>5.8.0</version>
    </dependency>

While the purpose of the pooling library is to keep our JMS resources open even when not being used, each of these resources does represent some overhead both on the client side and on the broker. We can configure our PooledConnectionFactory instance with an eviction time so that it will periodically close any resources that have sat idle in the pool for too long. Refer to the ActiveMQ API documentation at http://activemq.apache.org/maven/5.8.0/apidocs/org/apache/activemq/pool/PooledConnectionFactory.html for the various settings available for tuning PooledConnectionFactory.