HomeDocumentation > Reference > Samples > Sample applications > not-in-svn - Inbound JCA example


The J2EE Connector Architecture (JCA) provides a Java technology solution to the problem of connectivity between the many application containers and today's enterprise information systems (EIS). In the 1.5 release of the JCA specification, the architecture defines an inbound communication model, whereby the EIS initiates all communication to an EJB application. The mechanism allows the inbound resource adapters to invoke Enterprise Java Beans (EJB).

Overview

This document will describe how to deploy an EJB application, so that it can receive inbound events from a JCA Adapter. It will first describe the key parts of the Resource Adapter that pertain to the inbound communication model, as well as the Geronimo-specific plans that will deploy the Resource Adapter stand-alone. It will then describe the Enterprise Application that will be executed by the EIS, via the inbound communication mechanism.

Resource Adapter

The code described in this section are classes that will be deployed as part of a resource adapter. For the most part, there is nothing Geronimo-specific about these files. However, the end of this section will discuss how to deploy the resource adapter into a Geronimo container.

In the JCA 1.5 specification, inbound adapters can support custom messaging formats. This allows a Message-Driven Bean (MDB) to implement any interface that has been defined by the inbound Resource Adapter. In the previous version of the JCA specification, Java Message Service (JMS) messages was the only mechanism for inbound communication, requiring the MDB to implement the interface javax.jms.MessageListener. With JCA 1.5, however, any interface definition can be used by a MDB to handle inbound requests.

Interface Definition

For this example, the interface com.sample.connector.EventListener interface has been defined. This interface will be implemented by any MDB that will be called by the inbound Resource Adapter.

EventListener.java

ActivationSpec implementation

Inbound resource adapters use implementations of the interface javax.resource.spi.ActivationSpec. The interface itself has no methods, but the class implementing the interface

  • must be a JavaBean, providing both getter and setter methods to the bean's fields
  • must be serializable

According the the API documentation, "the ActivationSpec implementation will hold the activation configuration information for a message endpoint". The message endpoint, in this case, will be an MDB in our enterprise application. Our ActivationSpec implementation is the class com.sample.connector.EventActivationSpec. Our example's ActivationSpec will store all the data required so that a connection can be opened, in order for the remote EIS system to call into the application container (machineName, port, user name, user password, and event pattern).

EventActivationSpec.java

Common Deployment Descriptor

In the JCA deployment descriptor (ra.xml), there is a section that allows the adapter to associate an interface with the ActivationSpec implementation. This is required, so that the application container can ensure that mandatory properties are defined in the MDB that will be called by the adapter.

ra.xml

Once an ActivationSpec has been implemented, the Resource Adapter's endpointActivation method can be updated. The application container will call this method on the Resource Adapter when a MDB is deployed into the environment. This allows the inbound adapter to open any connections. The method's signature is

The endpointFactory provides the ability to create new instances of MDBs, and the spec will be the implementation of ActivationSpec, which will contain all the required properties. The implementation of this method will be specific to the mechanism used by the EIS to support messaging. Typically, the resource adapter will define implementations of the javax.resource.spi.work.Work interface, which will service the inbound requests without directly creating new Threads.

Equally important is to implement the endpointDeactivation method.  This allows the adapter to free any resources that were created when the endpoint was activated.

Geronimo Deployment Descriptor

Finally, we've reached the Geronimo-specific details.  The Geronimo Deployment Descriptor provides a section that defines specific inbound Resource Adapters.

geronimo-ra.xml

When deploying the adapter's RAR file with the above deployment plan, a single inbound adapter will be created, named MyInboundEvents.

EJB Application

At this point, we've defined and deployed our resource adapter into the Geronimo server instance.  Now, an EJB application can be written and deployed that contains a Message-Driven Bean that will be called by the inbound Resource Adapter when it receives a message from the remote EIS.

In this example, a Message-Driven Bean implements the EventListener interface that was defined by the Resource Adapter.

EventBean.java

The bean doesn't do much, but it will show that the bean is being executed. However, it is using the ActivationConfigProperty annotation to define the properties required by the inbound resource adapter. These values will be defined against the appropriate ActivationSpec (in this case, the EventActivationSpec), which will be passed to the resource adapter's endpointActivation method.

Geronimo Deployment Descriptor

The final piece is to associate the MDB with the inbound Resource Adapter MyInboundEvents that was defined when the Resource Adapter was deployed into the Geronimo container. This is done in the EJB's Geronimo Deployment Descriptor, openejb-jar.xml.

openejb-jar.xml

In this file, we're associating the EventBean with the MyInboundEvents adapter.