J2EE Connector Programmer's Guide

The content of this guide is the following:

  1. Target Audience and Content
  2. Principles
  3. Defining the JOnAS Connector Deployment Descriptor
  4. Resource Adapter (RAR) Packaging
  5. Use and Deployment of a Resource Adapter
  6. JDBC Resource Adapters
  7. 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 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:
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:

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.

JCA Architecture

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).