Oracle Application Server 10g(9.0.4) Containers for J2EE

Date: December 2, 2003

How-To: J2EE Connectors

• Understand the basic features of OC4J J2EE Connectors support.
• Deploy standalone resource adapter.
• Deploy embedded resource adapter.

Overview

The J2EE Connector Architecture (JCA), is a required J2EE 1.3 API. It defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems, or EISs. Examples of EISs include ERP, mainframe transaction processing systems, database systems, and legacy applications that may not be written in the Java programming language.

A resource adapter is a driver used by an application server or an application client to connect to a specific EIS. Examples of resource adapters are a JDBC or SQLJ driver to connect to a relational database, an ERP resource adapter to connect to an ERP system, and a TP resource adapter to connect to a TP monitor.

A stand-alone resource adapter, materialized by a stand-alone Resource Adapter Archive (RAR) file, is available to all deployed applications in the application server instance.

An embedded resource adapter, bundled within an enterprise application archive (EAR), is available only to the J2EE application with which it is packaged.

J2EE 1.3 requires application servers to support the deployment of both stand-alone and embedded resource adapters.

When deploying resource adapters with OC4J, you need to work with the following JCA deployment descriptors:

ra.xml: standard J2EE deployment descriptor for developing against resource adapters

oc4j-ra.xml: contains deployment configurations for deploying resource adapters to OC4J. It contains EIS connection information as specified in the deployment descriptor of the resource adapter (ra.xml), JNDI name to be used, connection pooling parameters, and resource principal mappings (security-config element)

oc4j-connectors.xml: In an OC4J instance with stand-alone resource adapters deployed, this file contains a list of stand-alone resource adapters that have been deployed in this OC4J instance. In and J2EE application with embedded resource adapters deployed, this file contains a list of embedded resource adapters that have been bundled with the application.

Pre-requisites for running the examples

•     OC4J 10g(9.0.4) installed (OC4J home directory is referred to as  <j2ee_home> in this document).
•     Access to an Oracle database (with the scott/tiger demo schema).
•     Downloaded Sun's blackbox resource adapter.
  

Download and unpack example files

Download the jcademo904.zip How-To package with the examples files and unzip it into a directory of your choice. This directory will be referred to as  <jca_home> from now on.  Download the Sun J2EE Connector Architecture 1.0.1 Sample Source and Binary Code Adaptor from the J2EE 1.3 SDK download area and copy the Blackbox Resource adapter (extract blackbox-notx.rar from j2ee_connector-1_0-sample_adapters.zip) to the <jca_home>/embedded directory. Your <jca_home> directory should now contain the following files and directories:

• embedded/
• blackbox-notx.rar - Sun's blackbox resource adapter.
• META-INF/
• application.xml - J2EE application deployment descriptor.
• jcaweb.war - Web module of the J2EE application, containing emp.jsp which accesses the database via JCA
• standalone/
• jcasademo.ear - A simple J2EE application for testing standalone resource adapter
  

Deploying Standalone Resource Adapter Archives

Deploying the resource adapter archive

1. In the <j2ee_home>/config/server.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as follows:
   

      <application-server
      	application-directory="../applications"
   
      	deployment-directory="../application-deployments"
       	connector-directory="../connectors"
      >
   
   

   The connector-directory attribute refers to the directory under which standalone resource adapters will be unpacked. The path is relative to the <j2ee_home>/config directory. The rest of the document is based on this setting. Please adjust for the configuration set in your environment.
   
   
2. In the <j2ee_home>/config/application.xml file, make sure that there is a <connectors> element under <orion-application> that looks like this:
   

      <connectors path="./oc4j-connectors.xml"/>  

3. Start OC4J if it is not already started.
   
   
4. Standalone resource adapters can be deployed into OC4J by using the admin.jar utility. You can deploy Sun's Blackbox resource adapter that you have downloaded into OC4J as follows:
   
   java -jar <j2ee_home>/admin.jar ormi://<host> <uid> < pwd> -deployConnector -file <jca_home>/embedded/blackbox-notx.rar -name standalone
   
   Replace <host> with the host name where your OC4J instance is running, <uid> and <pwd> with the username and password of the OC4J adminstrator.
   
   Here, standalone is a name we choose to give to this resource adapter deployment. You will need to use this name when you wish to undeploy this resource adapter at a later time using the -undeployConnector switch in admin.jar.
   

Configuring Your Resource Adapter

1. OC4J has created a directory called standalone in <j2ee_home>/application-deployments/default/ when you deployed your resource adapter. A default deployment descriptor file oc4j-ra.xml is also generated automatically into that directory. Edit the generated oc4j-ra.xml file at <j2ee_home>/application-deployments/default/standalone directory as follow:
   
   Set the JNDI location of the connector to "eis/standaloneEIS":

     <connector-factory connector-name="BlackboxNoTx" location="eis/standaloneEIS">   
   

   Modify the value for tthe ConnectionURL property to point to your database:

     <config-property name="ConnectionURL" value="jdbc:oracle:thin:@<host>:<port>:<sid>" />     
   

   Replace <host>, <port> and <sid> above with the proper values for your database. OC4J will configure an instance of connection factory with the proper connection URL, and bound it into the specified JNDI location for use by application code.
   
   
2. Restart OC4J for the modified configuration to become effective.
   

Testing Your Resource Adapter Deployment

1. The standalone resource adapter that you have just deployed is now available to all applications that are deployed into the OC4J instance. You can deploy the sample application jcasademo.ear located in the <jca_home>/standalone directory for testing your resource adapter.
   
   
2. Start up OC4J if it is not already started.
   
   
3. Deploy the jcasademo.ear sample application to your OC4J instance:
    
       java -jar <j2ee_home>/admin.jar ormi://<host> <uid> < pwd>  -deploy -file jcasademo.ear -deploymentName jcasademo
   
   Replace <host> with the host name where your OC4J instance is running, <uid> and <pwd> with the username and password of the OC4J adminstrator.
   
   
4. Bind the virtual path for the web module:
   
          java -jar <j2ee_home>/admin.jar ormi://<host> <uid> < pwd>  -bindWebApp jcasademo jcasademoweb http-web-site /jcasademo
   
   You may need to replace http-web-site with a web site that is defined inside a <web-site> element in your <j2ee_home>/config/server.xml file.
   
   
5. Run emp.jsp in your browser using the URL: http://<host>:<port>/jcasademo/emp.jsp. You should be able to see the query result returned from the database (emp table). This JSP looks up the connection factory from the standalone resource adapter using the JNDI name "java:comp/env/eis/standaloneEIS" for creating a connection to the database.
   
   

Deploying Embedded Resource Adapter Archives

Packaging Your RAR archive into an Application

1. Make sure the <jca_home>/embedded directory contains the blackbox-notx.rar file (Sun's blackbox resource adapter). It will be bundled with your J2EE application as an embedded adapter and will be only available to your application.
   
   
2. Go to the <jca_home>/embedded directory. This directory is compliant with the J2EE standard EAR format. Package the directory into a single EAR file:

       jar cMf jcademo.ear *

Deploying the Application Archive

1. Start up OC4J if it is not already started.
   
   
2. Deploy the EAR file to your running OC4J instance (<j2ee_home> is the home directory of your OC4J instance):
   
          java -jar <j2ee_home>/admin.jar ormi://<host> <uid> < pwd>  -deploy -file jcademo.ear -deploymentName jcademo
   
   Replace <host> with the host name where your OC4J instance is running, <uid> and <pwd> with the username and password of the OC4J adminstrator.
   
   
3. Bind the virtual path for the web module:
   
          java -jar <j2ee_home>/admin.jar ormi://<host> <uid> < pwd>  -bindWebApp jcademo jcaweb http-web-site /jcademo
   
   You may need to replace http-web-site with a web site that is defined inside a <web-site> element in your <j2ee_home>/config/server.xml file.
   

Configuring the Resource Adapter embedded in the application

1. After deployment, OC4J have generated a default oc4j-ra.xml file which needs to be configured. Edit the generated oc4j-ra.xml file in <j2ee_home>/application-deployments/jcademo/blackbox-notx directory as follows:
   
   Set the JNDI location of the connector to "eis/embeddedEIS":

     <connector-factory connector-name="BlackboxNoTx" location="eis/embeddedEIS">   
   

   Modify the value for tthe ConnectionURL property to point to your database:

     <config-property name="ConnectionURL" value="jdbc:oracle:thin:@<host>:<port>:<sid>" />     
   

   Replace <host>, <port> and <sid> above with the proper values for your database. OC4J will configure an instance of connection factory with the proper connection URL, and bound it into the specified JNDI location for use by application code.
   
   
2. Restart OC4J  for the modified configuration to become effective.
   

Testing Your Embedded Resource Adapter Deployment

1. Run emp.jsp in your browser from the URL: http://<host>:<port>/jcademo/emp.jsp. You should be able to see the result returned from the database (emp table). This JSP looks up the connection factory from the embedded resource adapter using the JNDI name "java:comp/env/eis/embeddedEIS" for creating a connection to the database.

Summary

• Understand the basic features of OC4J JCA support.
• Deploy standalone resource adapter.
• Deploy embedded resource adapter.