The content of this guide is the following:
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.
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.
The jonas-ra.xml contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values.
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 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:
$JONAS_ROOT/xml/connector_1_5.xsdor http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd. This deployment descriptor must be stored with the name META-INF/ra.xml in the RAR file.
Before deploying an RAR file, the JOnAS-specific XML must be configured
and added. Refer to the
section for information.
Accessing Resource Adapter involves the following steps:
<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
getConnectionon 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.
closemethod on the
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 -path . -j adap_1 raThese properties may be specific for each resource adapter and its underlying EIS. They are used to configure the resource adapter via its
managedConnectionFactoryclass. 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 raThis will add the xml file to the ra.rar file, which is now ready for deployment.
resourceis included in the
jonas.service.resource.resourcesproperty. 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
jonas.service.resource.autoloadin jonas.properties is configured differently.
jonas admin -a xxx.rar" command.
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.
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).