J2EE Connector Programmer's Guide

The content of this guide is the following:

Target Audience and Content
Principles
Defining the JOnAS Connector Deployment Descriptor
Resource Adapter (RAR) Packaging
Use and Deployment of a Resource Adapter
JDBC Resource Adapters
Appendix: Connector Architecture Principles

Target Audience and Content

This chapter is provided for advanced JOnAS users concerned with EAI (Enterprise Application Integration) and using the J2EE Connector Architecture principles (refer to the Appendix for an introduction to the connectors). The target audience for this guide is the Resource Adapter deployer and programmer. It describes the JOnAS specific deployment file (jonas-ra.xml) and the sample code to access deployed RARs.

Principles

Resource Adapters are packaged for deployment in a standard Java programming language Archive file called a rar file (Resource ARchive), which is described in the J2EE Connector Architecture specification.

The standard method for creating the jonas-ra.xml file is to use the RAConfig tool. For a complete description refer to RAConfig.

Defining the JOnAS Connector Deployment Descriptor

The jonas-ra.xml contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values.

Deployment Tags:
- jndiname: (Required) Name the RAR will be registered as. This value will be used in the resource-ref section of an EJB.
- rarlink: Jndiname of a base RAR file. Useful for deploying multiple connection factories without having to deploy the complete RAR file again. When this is used, the only entry in RAR is a META-INF/jonas-ra.xml.
- native-lib: Directory where additional files in the RAR should be deployed.
Logging Tags:
- log-enabled: Determines if logging should be enabled for the RAR.
- log-topic: Log topic to use for the PrintWriter logger, which allows a separate handler for each deployed RAR.
Pooling Tags:
- pool-init: Initial size of the managed connection pool.
- pool-min: Minimum size of the managed connection pool.
- pool-max: Maximum size of the managed connection pool. Value of -1 is unlimited.
- pool-max-age: Maximum number of milliseconds to keep the managed connection in the pool. Value of 0 is an unlimited amount of time.
- pstmt-max: Maximum number of PreparedStatements per managed connection in the pool. Only needed with the JDBC RA of JOnAS or another database vendor's RAR. Value of 0 is unlimited and -1 disables the cache.
JDBC Connection Tags: Only valid with a Connection implementation of java.sql.Connection.
- jdbc-check-level: Level of checking that will be done for the jdbc connection. Values are 0 for no checking, 1 to validate that the connection is not closed before returning it, and greater than 1 to send the jdbc-test-statement.
- jdbc-test-statement: Test SQL statement sent on the connection if the jdbc-check-level is set accordingly.
Config Property Value Tags:
- Each entry must correspond to the config-property specified in the ra.xml of the RAR file.

Deployment Descriptor Examples

The following portion of a jonas-ra.xml file shows the linking to a base RAR file named BaseRar. All properties from the base RAR will be inherited and any values given in this jonas-ra.xml will override the other values.

  <jonas-resource>
    <jndiname>rar1</jndiname>
    <rarlink>BaseRar</rarlink>
    <native-lib>nativelib</native-lib>
    <log-enabled>false</log-enabled>
    <log-topic>com.xxx.rar1</log-topic>
    <jonas-config-property>
      <jonas-config-property-name>ip</jonas-config-property-name>
      <jonas-config-property-value>www.xxx.com</jonas-config-property-value>
    </jonas-config-property>
    .
    .
  </jonas-resource>

The following portion of a jonas-ra.xml file shows the configuration of a jdbc rar file.

  <jonas-resource>
    <jndiname>jdbc1</jndiname>
    <rarlink></rarlink>
    <native-lib>nativelib</native-lib>
    <log-enabled>false</log-enabled>
    <log-topic>com.xxx.jdbc1</log-topic>
    <pool-params>
      <pool-init>0</pool-init>
      <pool-min>0</pool-min>
      <pool-max>100</pool-max>
      <pool-max-age>0</pool-max-age>
      <pstmt-max>20</pstmt-max>
    </pool-params>
    <jdbc-conn-params>
      <jdbc_check-level>2</jdbc_check-level>
      <jdbc-test-statement>select 1</jdbc-test-statement>
    </jdbc-conn-params>
    <jonas-config-property>
      <jonas-config-property-name>url</jonas-config-property-name>
      <jonas-config-property-value>jdbc:oracle:thin:@test:1521:DB1</jonas-config-property-value>
    </jonas-config-property>
    .
    .
  </jonas-resource>

Resource Adapter (RAR) Packaging

Resource Adapters are packaged for deployment in a standard Java programming language Archive file called an RAR file (Resource Adapter ARchive). This file can contain the following:

Resource Adapters' deployment descriptor

The RAR file must contain the deployment descriptors, which are made up of:

The standard xml deployment descriptor, in the format defined in the J2EE 1.3 specification. Refer to $JONAS_ROOT/xml/connector_1_0.dtd. This deployment descriptor must be stored with the name META-INF/ra.xml in the RAR file.
The JOnAS-specific XML deployment descriptor in the format defined in $JONAS_ROOT/xml/jonas-ra_X_Y.dtd. This JOnAS deployment descriptor must be stored with the name META-INF/jonas-ra.xml in the RAR file.

Resource adapter components (jar): One or more jars which contain the java interfaces, implementation, and utility classes required by the resource adapter.
Platform-specific native libraries: One or more native libraries used by the resource adapter
Misc: One or more html, image files, or locale files used by the resource adapter.

Before deploying an RAR file, the JOnAS-specific XML must be configured and added. Refer to the RAConfig section for information.

Use and Deployment of a Resource Adapter

Accessing Resource Adapter involves the following steps:

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) 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, it must be closed using the close method on the Connection interface:
```
         cx.close();
    
```

The resource adapter must be deployed before being used by the application. Deploying the resource adapter requires the following:
- 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 RAConfig that is capable of building this XML file from an RA deployment descriptor inside an RAR file. 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 getter and setter method for each of its supported properties (as it is required in the Connector Architecture specification).
  After configuring the jonas-ra.xml file created above, it can be added to the resource adapter by executing the following:
```
           RAConfig -u jonas-ra.xml ra
        
```
  This will add the xml file to the ra.rar file, which is now ready for deployment.
The JOnAS resource service must be configured and started at JOnAS launching time:
In the jonas.properties file:
- Verify that the name resource is included in the jonas.services property.
- Use one of the following methods to deploy an RAR file:
  - The names of the resource adapter files (the '.rar' suffix is optional) must be added in the list of Resource Adapters to be used in the jonas.service.resource.resources property. 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 connectors 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 via the "jonas admin -a xxx.rar" command.
  - Add the RAR via the JonasAdmin console.

JDBC Resource Adapters

These generic JDBC resource adapters are supplied by JOnAS and are a replacement for the DBM service. Refer to Configuring JDBC Resource Adapters for a complete description and usage guide.

Appendix: Connector Architecture Principles

The Java Connector Architecture allows the connection of different Enterprise Information Systems (EIS) to an application server such as JOnAS. It defines a way for enterprise applications (based on EJB, servlet, JSP or J2EE clients) to communicate with existing EIS. This requires the use of a third party software component called "Resource Adapter" for each type of EIS, which should be previously deployed on the application server. The Resource Adapter is an architecture component comparable to a software driver, which connects the EIS, the application server, and the enterprise application (J2EE components in the case of JOnAS as application server). The RA provides an interface (the Common Client Interface or CCI) to the enterprise application (J2EE components) for accessing the EIS. The RA also provides standard interfaces for plugging into 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 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).