"When Connection.close() should not close", or the J2EE JCA ManagedConnection life cycle

One of the things I've struggled with most when I was developing the JMSJCA Resource Adapter at SeeBeyond, was the life cycle of the ManagedConnection. I wasted numerous hours going into fruitless directions simply because I did not fully grasp the intricacies of the ManagedConnection life cycle. If you're involved in developing Resource Adapters, you're likely to stumble onto the same problems, so read on!

What do you mean, close() should not close?

Let's take a look at how you might use a JMS Connection in an EJB:

@Resource(name="jms/cf") ConnectionFactory cf;
@Resource(name = "jmx/q1") Queue q;

@TransactionAttribute(TransactionAttributeType.REQUIRED)
public void myBusinessMethod() throws Exception {
 Connection c = cf.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 c.close();
}

Should c.close() really close the connection?

Keep in mind that since J2EE 1.4, JMS providers interface with the application server using JCA. JMS connections should be pooled so that repeated execution of the statement fact.createConnection() is cheap. So the answer is no, the connection should not really be closed.

Should c.close() return the connection to the pool then, so that another EJB could use it? Remember that there is a transaction in progress, so the container should hold on to the connection until the transaction is completed. Only then should the container return the connection to the pool.

Are you appreciating yet the complexities that the application server has to deal with? If not, let's add the following to the method above:

@TransactionAttribute(TransactionAttributeType.REQUIRED)
public void myBusinessMethod() throws Exception {
 ConnectionFactory fact = (ConnectionFactory) new InitialContext().lookup("jms/cf");
 Connection c = fact.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
 s.createProducer(s.createQueue("q")).send(s.createTextMessage("Hello world"));
 c.close();

 otherMethod();
}


public void otherMethod() throws Exception {
 ConnectionFactory fact = (ConnectionFactory) new InitialContext().lookup("jms/cf");
 Connection c = fact.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
 s.createProducer(s.createQueue("q")).send(s.createTextMessage("Goodbye world"));
 c.close();
}

When myBusinessMethod() is called, which in turn calls otherMethod(), how many connections are created? Good application servers like the Java CAPS Integration Server, the Sun Java System Application Server, and Glassfish use only one connection in this example. The connection that is used in otherMethod() is the same connection that was created in myBusinessMethod().

Let's look in more detail at what is happening under the covers, and why that is important.

Alphabet soup

Before we begin, let me reiterate some of the terms and abbreviations used. JCA stands for the Java Connector Architecture. It provides the interfacing between applications running in an application server, and external systems such as CRM packages, but also systems such as JMS.

A Resource Adapter is a set of classes that implement the JCA. The central interface for outbound communications is the ManagedConnection. An application, e.g. an EJB, never gets access to a a ManagedConnection directly. Instead, it gets a connection handle. The handle in the above example is the JMS Connection (actually, it is the JMS Session -- but let's not go into that right now). This Connection object is not the JMS Connection that is implemented by the JMS provider, but is a wrapper around such a connection. The wrapper is implemented by the Resource Adapter.

A ManagedConnection holds the physical connection to the external system, e.g. the JMS Connection and Session. Because the physical connection and hence the ManagedConnection is expensive to create, the application server tries to pool the ManagedConnections.

State transitions, and why they are important

We've already seen that a ManagedConnection can be in an idle state or pooled state and it can be in use. It would be very nice if the application server would tell the ManagedConnection when these state transitions happen. But it doesn't. Why would the ManagedConnection care to know when it is being used or when it is being returned to the pool? Let's look at an example in JMS. Let's change the example a little bit:

@TransactionAttribute(TransactionAttributeType.REQUIRED)
public void usingTemp() throws Exception {
 ConnectionFactory fact = (ConnectionFactory) new InitialContext().lookup("jms/cf");
 Connection c = fact.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
 Queue temp = s.createTemporaryQueue();
 Message request = s.createTextMessage("541897-9841");
 request.setJMSReplyTo(temp);
 sendRequest(request);
 Message reply = s.createConsumer(temp).receive();
 c.close();
} 

The sendRequest() method would somehow start a new transaction and send the request message. The question is when the temporary destination should be deleted. According to the JMS spec, the temporary destination should be invalidated as soon as the connection is closed. However, a transaction is still in progress, so the JMS provider will throw an exception if the temporary destination is deleted when c.close() is called. Can't we just ignore the temporary destination? After all, it will be deleted some time, e.g. when the physical JMS connection is closed. However, since the connection is pooled, it may take a long time before the physical JMS connection is closed. During that time temporary destinations just keep piling up. This approach will exhaust the JMS server.

The temporary destination can be deleted safely when the ManagedConnection is returned to the pool. And that's why it's important to know the state transitions.

How to detect state transitions

What hints does the application server give the ManagedConnection about the state transitions? Let's take a look at the ManagedConnection interface:

public interface ManagedConnection {
 Object getConnection(Subject subject, ConnectionRequestInfo connectionRequestInfo) throws ResourceException;
 void destroy() throws ResourceException;
 void cleanup() throws ResourceException;
 void associateConnection(Object object) throws ResourceException;
 void addConnectionEventListener(ConnectionEventListener connectionEventListener);
 void removeConnectionEventListener(ConnectionEventListener connectionEventListener);
 XAResource getXAResource() throws ResourceException;
 LocalTransaction getLocalTransaction() throws ResourceException;
 ManagedConnectionMetaData getMetaData() throws ResourceException;
 void setLogWriter(PrintWriter printWriter) throws ResourceException;
 PrintWriter getLogWriter() throws ResourceException;
}

The getConnection() method tells the ManagedConnection to create a new connection handle, so after that method the ManagedConnection knows that it is not in the pooled state.

The destroy() method destroys the ManagedConnection so it signals a state transition to "non-existent".

Doesn't the cleanup() method indicate that a connection is no longer used and will be returned to the pool? It depends on the application server when exactly this method is called. Most application servers will call cleanup() immediately when the application calls Connection.close(). At that moment the connection may still be enlisted in a transaction, and may be reused as we've seen in the examples above.

As it turns out, there are two states that the ManagedConnection needs to keep track of so that it can detect a state transition from "in-use" to "pooled".  The two diagrams keep track of whether the application has access to the ManagedConnection through a connection handle. In other words, it keeps track of whether the ManagedConnection has any outstanding connection handles. See the figure below.

The second state is a transactional state: it keeps track of whether the ManagedConnection is enlisted in a transaction. See the figure below:

Let's look at a few examples that illustrate this concept:

@Resource EJBContext ctx;
@Resource(name="jms/cf") ConnectionFactory cf;
@Resource(name = "jmx/q1") Queue q;

public void ex1() {
 ctx.getUserTransaction().begin();
 Connection c = cf.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 c.close();
 ctx.getUserTransaction().commit();
}

In this example the getConnection() method is called upon cf.createConnection().createSession(): the ManagedConnection is in use. At the same time the connection is enlisted in the transaction; this is done through the XAResource obtained through ManagedConnection.getXAResource(). When c.close() is called, the ManagedConnection is no longer accessible to the application: all the connection handles are closed. The application server may and probably will call ManagedConnection.cleanup(). However, the connection is still enlisted in the transaction, so the connection is not returned to the pool yet. That happens when getUserTransaction().commit() is called. While the connection is still enlisted, the resource adapter should not try to delete any objects such as temporary destinations in the example mentioned above.

In the following example the enlistment happens a little later. See the inline comments for the state transitions.

public void ex2() {
 Connection c = cf.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE); // Accessible, but not enlisted
 ctx.getUserTransaction().begin(); // Accessible and enlisted
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 c.close(); // Inaccessible and enlisted
 ctx.getUserTransaction().commit(); // Inaccessible and not enlisted
 // Return to pool
}

There is also a possible transition from "Inaccessible and enlisted" back to "Accessible and enlisted":

public void ex3() {
 Connection c = cf.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE); // Accessible, but not enlisted
 ctx.getUserTransaction().begin(); // Accessible and enlisted
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 c.close(); // Inaccessible and enlisted
 
 c = cf.createConnection();
 s = c.createSession(false, Session.AUTO_ACKNOWLEDGE); // Accessible and enlisted
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 c.close(); // Inaccessible and enlisted
 ctx.getUserTransaction().commit(); // Inaccessible and not enlisted

 // Return to pool
}

The following example shows that there can be multiple connection handles:

public void ex4() {
 Connection c = cf.createConnection();
 Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE); // Accessible, but not enlisted
 ctx.getUserTransaction().begin(); // Accessible and enlisted
 s.createProducer(q).send(s.createTextMessage("Hello world"));
 
 Connection c2 = cf.createConnection();
 Session s2 = c.createSession(false, Session.AUTO_ACKNOWLEDGE);// Accessible and enlisted
 s2.createProducer(q).send(s2.createTextMessage("Hello world"));
 c2.close(); // Accessible and enlisted
 ctx.getUserTransaction().commit(); // Accessible and not enlisted
 c.close(); // Inaccessible and not enlisted
 // Return to pool
}

How to monitor transaction enlistment

To monitor enlistment and the commit() or rollback() method on the XAResource it is possible to write a wrapper around the XAResource of the underlying provider. There are some drawbacks associated with that, and it is better to monitor the transaction through a javax.transaction.Synchronization object. I've described this in more detail in my blog of July 23, 2006: J2EE JCA Resource Adapters: The problem with XAResource wrappers .

Conclusion

By keeping track of both the number of outstanding connection handles given out to the application and the enlistment in a transaction, the ManagedConnection can figure out when it is returned to the pool so that it can undertake necessary actions such as destruction of objects indirectly created by the application.