# JOnAS and the Connector Architecture

1. Target Audience and Rationale
2. Introducing the Connector Architecture
3. Using a JCA Resource Adapter with JOnAS

## Target Audience and Rationale

This chapter is dedicated to advanced JOnAS users concerned by EAI (Enterprise Application Integration). The Java Connector Architecture (JCA) defines a way for enterprise applications (based on EJB, servlet, JSP or J2EE clients) to communicate with external existing Enterprise Information Systems (EIS). This requires the use of a third party software component called "Resource Adapter", provided for a kind of EIS, and which should be previously deployed on the application server. In the case of JOnAS as application server, this chapter describes the way such a Resource Adapter should be deployed, and how an EJB application may use it. As JOnAS currently provides only an EJB container, only the EJB components of an enterprise application may access an EIS through a JCA Resource Adapter; JSP, Servlets or EJB clients are currently not concerned.

## Introducing the Connector Architecture

The Java Connector Architecture allows the connection of different Enterprise Information Systems (EIS) to an application server such as JOnAS. It is based on the Resource Adapter (RA), an architecture component comparable to a software driver, connecting the EIS, the application server, and the enterprise application (EJB components in the case of JOnAS as application server). The RA is generally provided by an EIS vendor, and provides an interface (the Common Client Interface or CCI) to the enterprise application (EJBs) for accessing the EIS. The RA also provides standard interfaces for being plugged to the application server, so that they can collaborate to keep all system-level mechanisms (transactions, security, and connection management) transparent from the application components.

The resource adapter plugs into JOnAS and provides connectivity between the EIS, JOnAS, and the EJB application. The application performs "business logic" operations on the EIS data using the RA client API (CCI), while transactions, connections (including pooling) and security on the EIS is managed by JOnAS through the RA (system contract).

## Using a JCA Resource Adapter with JOnAS

The following steps are involved for using a JCA Resource Adapter with JOnAS

- The bean provider must specify the connection factory requirements by declaring a resource manager connection factory reference in its EJB deployment descriptor. for example:

            <resource-ref>
            <res-ref-name>eis/MyEIS</res-ref-name>
            <res-type>javax.resource.cci.ConnectionFactory</res-type>
            <res-auth>Container</res-auth>
            </resource-ref>

  The mapping to the actual JNDI name of the connection factory (here `adapt_1`) will be done in the JOnAS specific deployment descriptor with the following element:

            <jonas-resource>
            <res-ref-name>eis/MyEIS</res-ref-name>
            <jndi-name>adapt_1</jndi-name>
            </jonas-resource>

  This means that the bean programmer will have access to a connection factory instance using the JNDI interface via the java:comp/env/eis/MyEIS name:

           // obtain the initial JNDI naming context
           Context inictx = new InitialContext();

           // perform JNDI lookup to obtain the connection factory
           javax.resource.cci.ConnectionFactory cxf =
                   (javax.resource.cci.ConnectionFactory)
                        inictx .lookup("java:comp/env/eis/MyEIS<");

  The bean programmer can then get a connection by calling the method `getConnection` on the connection factory.

            javax.resource.cci.Connection cx = cxf.getConnection();

  The returned connection instance represents an application-level handle to a physical connection for accessing the underlying EIS.
  After finishing with the connection, it must be closed by using the `close` method on the `Connection` interface:

               cx.close();

- The resource adapter must be deployed before launching the JOnAS server. Deploying the resource adapter means:

  - build a resource adapter configuration properties file that will be used by the JOnAS's resource service.
    This properties file is used to configure the resource adapter in the operational environment and reflects the values of all properties declared in the deployment descriptor for the resource adapter. JOnAS provides a deployment tool `RAXml2Prop` that is capable to build this properties file from a Resource adapter deployment descriptor. example:

                   RAXml2Prop -o MyRA.properties -j adap_1 ra.xml

    These properties may be specific for each resource adapter and its underlying EIS. They are used to configure the resource adapter via its `managedConnectionFactory` class. It is important for JOnAS that this class provides getter and setter method for each of its supported properties (as it is required in the JCA specification).

  - put the `.jar` files that are part of the resource adapter archive file (`.rar` file) in a location that can be seen by the server at launching time via the classpath.

- The JOnASresource service must be configured and started at JOnAS launching time:

In `jonas.properties` file:

- the name `resource` must be inserted in the`jonas.services` property,
- the name of the resource adapter configuration properties file (without the '.properties' suffix) must be added in the list of Resource Adapter to be used in the `jonas.service.resource.resources` property.

             jonas.service.resource.resources  MyRA