Anatomy of an inbound jca connector

Continuing with the posts about JCA lets now have a look on the specifics of an Inbound JCA connector. As already mentioned in a previous post the term inbound is related to the flow of the call on your application.
The endpointActivation method plays a key role in an Inbound adapter. This is the method that is triggered by the container on each of the Activation Specs you have configured on your Application Server instance. This is also the point where you start your monitoring thread (FooMonitor in our example). Remember that this monitoring object has to have access to a number of key container classes such as MessageEndpointFactory implementation and also WorkManager.
Apart from container objects you’ll certainly need to have the ActivationSpec object passed on the endpointActivation method since it carries on the configuration provided for this activation spec (taking JMS as an example it’d be host, queue, username, …).
Another point to remember is that you’ll need to have a reference to the monitor threads that were activated since on container shutdown it’ll invoke the endpointDeactivation method and you’ll need to retrieve the related monitor thread and stop its execution.

Inbound Connector classes

Too much text lets now have a look on some diagrams:

As you may have already guessed, FooMonitor is the thread that will poll for events and schedule their notifications through the WorkManager. You should never use the monitor thread for the notification since it’ll be blocked during notification denying the sending of other notifications. That’s the reason you should schedule an asynchronous notification using WorkManager.

FooNotification implementation

Skipping to the FooNotification class, its implementation will be something like the following code:

public void run() {
	MessageEndpoint endpoint = null;
	try {
		endpoint =  messageEndpointFactory.createEndpoint(null);
		((FooListener) endpoint).onMessage(msg);
	} catch (Exception ex) {
		logger.error("Error on foo notification" ,ex);
	} finally {
		if (endpoint != null)
			endpoint.release();
	}
}

As already mentioned, that’s the point where the MessageEndpointFactory is used. It provides us proxies for FooMDB classes. Remember to ALWAYS invoke release after using this proxy otherwise your container may run out of proxies since it’ll think you are still using them.
Another aspect not really detailed is the msg parameter on the onMessage method: this one is dependent on your ResourceAdapter – You are the one responsible for defining it (unless you have chosen a regular API like JMS).

Inbound JCA Connectors Introduction

After some posts about Outbound JCA connectors, let’s have a look at the concepts related to an Inbound JCA connector.

First question I always hear: “So, the server (legacy application) connects a client socket into a server socket on my J2EE server, right?” and I always answer: “depends”. People tends to think that the term inbound and outbound are related to TCP/IP connection, but, in fact, it is related to the flow of the process. In an outbound connector, our system is the actor and if you trace the flow of the call you’ll notice that it is leaving from our system to the legacy one; or perharps we could say outgoing. On the other hand, in an inbound connector, the actor is the legacy system that is triggering an ingoing message that is started outside our system and goes all the way into it.

Let’s see a sequence diagram of an inbound connector to make things clearer:

JCA Inbound Connector Sequence Diagram

As you can see in the diagram, the component that ties the Application Server, the legacy system and the J2EE Application is the ActivationSpec.

Usually, instance configurations such as port, host and other instance related data is stored on the ActivationSpec, you may also have configuration in the ResourceAdapter itself, but remember that all the configurations placed on the ResourceAdapter will be shared across multiple ActivationSpecs that may be deployed on this ResourceAdapter.

The real class responsible for handling Enterprise Events is ResourceAdapter dependant and will be initialized during endpointActivation method call on a ResourceAdapter. These classes are usually implemented as a Thread or they implement the Work interface and are submitted to the container for execution through the WorkManager instance. If you opt to use a simple Thread, remember to daemonize it otherwise your application server wont be able to properly shutdown.

For the next weeks I’ll be posting some insights about how to implement an Inbound Connector using JCA.