Connection request flow on outbound JCA connector

Continuing with the posts about outbound JCA connectors lets have a quick look at one of the main flows of an outbound JCA connector: the connection request flow.

By now you might be wondering: “What on earth is responsible for making my connectors poolable? Is there any dark magic involved?”.

First answer: “the ConnectionManager” and second answer: “Yes and it is container dependant!”. That’s the reason you should keep an instance of the ConnectionManager inside your ConnectionFactory when it is created, that’s how you delegate the connection creation to the pooling implementation of the container.

Enough explanation let’s have a look on a sequence diagram for a connection creation when we have no connections inside the pool.

First flow: connection request with no matching connections

First thing to take note, it is up to you to implement the matchManagedConnections, I’ve put a note on the next diagram that might help on this implementation: making the ManagedConnection be able to compare itself to a ConnectionRequestInfo makes the things easier. Also beaware that some Application Servers (eg.: WebSphere) skip the matchManagedConnections part if it detects by itself that the pool is empty or there isn’t any matching connection.

Sequence Diagram - No Matching Connection

Sequence Diagram - No Matching Connection

Another point about the specification is that it states that a single managed connection may be responsible for more than a single physical connection (FooConnectionImpl), this is required for scenarios where connection sharing is possible (refer to section of the specification).

Previously I tried implementing using a single handle but I noticed that it does not take much effort to make it fully adherent, in fact, it is only necessary to use a delegate (FooConnectionHandle) that implements the FooConnection interface and delegates almost all the methods to the FooConnectionImpl instance that is inside the FooManagedConnection instance (refer to sections and 6.8.1 of the specifications). The exception to the delegation is the close method that your connection must provide, this method in the delegate will be responsible for raising the Connection Closed Event, this is the way you signal the container that you are giving the connection back to the pool.
Second flow: connection request when there are matching connections inside the pool.

Sequence Diagram - Matching Connections

Sequence Diagram - Matching Connections

This flow is executed whenever the container guesses there are potential matching connections. The matchManagedConnection method is invoked with the minimal connection set that the container can identify. The connection set is a key point: specification states that the container is responbile for determining the minimal set that has a potential match to avoid degrading performance while looking for the connection. Also I noticed that some containers don’t check the connections inside this Set before sending them for matching.

Implementation Tips

Here are some decisions that might help on the implementation of the ManagedConnection and ManagedConnectionFactory.

  • Store the ConnectionRequestInfo that was passed to the ManagedConnectionFactory on the creation of the ManagedConnection as an attribute inside the ManagedConnection this leads to the next tip
  • Use the ConnectionRequestInfo stored in the ManagedConnection as argument to an overload of the equals method of the ManagedConnection class this helps in the implementation of the matchManagedConnection method
  • Never ever forget to include your ManagedConnection object on equals(Object) method implementation. The tip above may lead you to forget this details. Dont do this under any circumstance since specification requires this and some containers freak out after some use time if this method is not implemented (connection borrow time goes all way up if not implemented)

Next post I’ll focus on how to signal the container that something went wrong with the connection and how to validate the connection before it is returned to the requestor.


6 Responses to “Connection request flow on outbound JCA connector”

  1. September 17, 2008 at 10:33 pm


    Small suggestion for improving those diagrams :
    1) include the return value of the ‘equals’ call, should make it a bit clearer.
    2) make sure the activation bar for ‘allocateConnection’ extends below the (end of the) construction of the ‘FooConnectionImpl’ object.

    To avoid things like issue 2) I would recommend getting a UML sequence diagram editor that guarantees correct diagrams, but I’m biased of course ;o) But here’s a quick 30 sec demo if you’re curious.

  2. September 18, 2008 at 12:32 am

    Hi Yanic,

    I’ll give a try. The UML tool I am using already lacks some UML 2.0 features (not to mention that the frames (opt, alt, etc) does not work very nicely that’s why I did not put a loop frame on the matchManagedConnections flow).


  3. September 18, 2008 at 12:33 am


    I forgot to say thanks for the tip! I’ll remember for next posts!


  4. 4 PC
    May 4, 2010 at 5:24 am

    I am implementing a RA for hooking into a EIS. My doubt is in implementing the matchManagedConnection method. You seem to mention that the ConnectionRequestInfo can be used for deciding which ManagedConnection in set matches. The ConnectionRequestInfo always consists of username and password, and in our scenario this remains same for all connection requests. Do you have any idea, how else can matchManagedConnection can be implemented?

    Thanks in advance,

    • May 4, 2010 at 5:06 pm

      If this is the whole info you need for your EIS (username and pwd) then fine. Compare the request info being passed with the connection set and see if any of them match, if any match, you can safely return any of them even the first one. But sincerely, your EIS does not have even a simple host name info? If that’s the case take this into account too.

      Rafael Ribeiro

  5. 6 PC
    May 5, 2010 at 5:25 am

    Thanks Rafael.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


Blog Stats

  • 372,288 hits since aug'08

%d bloggers like this: