25.2. Defining the JOnAS Connector Deployment Descriptor

Using a Connector Resource Adapter with JOnAS involves the following steps:

1. 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 of the connection factory to the actual JNDI name (here adapt_1) is 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, you must close it using the close method on the Connection interface:

   cx.close();

2. The resource adapters must be deployed before being used by the application. Deploying the resource adapter requires that you build a JOnAS-specific resource adapter configuration file that will be included in the resource adapter.

   This jonas-ra XML 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, plus additional JOnAS-specific configuration properties. JOnAS provides a deployment tool (Section 6.7 RAConfig) that is capable of building this XML file from an RA deployment descriptor inside an RAR file. For example:

   RAConfig -j adap_1 ra

   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 mandatory that this class provide a getter and setter method for each of its supported properties (as it is required in the Connector Architecture specification). Refer to Chapter 41 Configuring Resource Adapters for a complete description of the JOnAS-specific configuration file, jonas-ra.xml.

3. The JOnAS resource service must be configured and started at JOnAS launching time:

   In the jonas.properties file:

   1. Insert the name resource in the jonas.services property.

   2. Use one of the following methods to deploy an RAR file:

      • The name of the resource adapter files (the .rar suffix is optional) must be added in the list of Resource Adapter to be used in the jonas.service.resource.resources RAR file. If the .rar suffix is not used on the property, it will be used when trying to allocate the specified Resource Adapter.

        jonas.service.resource.resources MyEIS.rar, MyEIS1

      • Place the RAR file in the autoload directory of $JONAS_BASE; default value is $JONAS_BASE/rars/autoload. Note that it may be different if jonas.service.resource.autoload in jonas.properties is configured differently.

      • Add the RAR:

        jonas admin -a xxx.rar