12
Java Connector Architecture

This chapter describes how the Java Connector Architecture (JCA) can be used in an Oracle9iAS Containers for J2EE (OC4J) application. This chapter covers the following topics:

• Introduction

• Deploying Resource Adapters with OC4J

• Container-Managed Sign-on vs. Component-Managed Sign-on

Introduction

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

Figure 12-1 JCA Architecture

Text description of the illustration jcaarch.gif

Resource Adapter

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 JDBC or SQLJ drivers 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. J2EE 1.3 requires application servers to support both stand-alone and embedded resource adapters.

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.

Here is an example of files found in a RAR file. The list of files can vary.

/META-INF/ra.xml 
/META-INF/oc4j-ra.xml 
/howto.html 
/images/icon.jpg 
/ra.jar 
/cci.jar 
/win.dll 
/solaris.so 

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

Application Contracts

The client API furnished by a resource adapter can either be the standard Common Client Interface (CCI), or a client API specific to the type of a resource adapter and its underlying EIS. For example, the JDBC API is the client API specific to relational database accesses. The EIS side of the contract is implemented by the resource adapter, transparently to the application components.

Quality of Service Contracts

JCA also defines three "Quality of Service" (QoS) contracts between an application server and an EIS.

• Connection Pooling: enables an application server to pool connections to an underlying EIS, and enables application components to connect to an EIS.

• Transaction Management: enables an application server to use a transaction manager (JTA XAResource) to manage transactions across multiple resource managers.

• Security management: provides authentication, authorization, and secure communication between the J2EE server and the EIS.

All resource adapters must support their side of the QoS contracts to be pluggable into application servers.

Deploying Resource Adapters with OC4J

This section discusses creating deployment descriptors, deploying stand-alone resource adapters, and deploying embedded resource adapters.

JCA Deployment Descriptors

OC4J provides the following 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, there should be one oc4j-connectors.xml file in the $OC4J_HOME/config directory, which contains a list of stand-alone resource adapters that have been deployed in this OC4J instance.

Example:

<oc4j-connectors> 
  <connector name="myEIS" path="eis.rar"> 
 <native-library>lib</native-library> 
  </connector> 
</oc4j-connectors> 

Deploying Stand-Alone Resource Adapter Archives

Stand-alone resource adapter archives can be deployed in OC4J. During deployment, each stand-alone resource adapter should be given a unique name for future operations such as undeployment of the resource adapter. Deployment of resource adapters in OC4J can be done in one of the following ways:

Deployment using Admin command-line tool

A -deployconnector switch should be added to the admin command-line tool (admin.jar) to allow deployment of stand-alone resource adapters:

-deployconnector 
-file [path] - path to the .rar file 
- name [name] - a name given to this resource adapter 

OC4J should decompress the .rar file into $OC4J_HOME/<connector-directory>/<connector-name> directory. If the directory does not already exist, it will be created. A new attribute connector-directory should be added to the <application-server> element in application-server.dtd to specify the path used for the storage of stand-alone resource adapters. connector-directory defaults to ../connectors.

For example, a certain resource adapter is deployed using the following values in the -deployconnector switch:

java -jar admin.jar ... -deployconnector -name myname -file path/myconnector.rar 

OC4J will uncompress myconnector.rar and store the files in $OC4J_HOME/connectors/myname directory.

The deployment tool should verify that the transaction level and authentication mechanism specified in the deployment descriptor of the resource adapter (ra.xml) are supported by OC4J. Otherwise, the resource adapter cannot be deployed into OC4J and an error message should be displayed.

Manual deployment through directory manipulation

Stand-alone resource adapter archives should also allowed to be deployed manually by creating a <connector-name> directory under $OC4J_HOME/<connector-directory>, copying the .rar file into that directory, and adding an entry to the oc4j-connectors.xml file for the new resource adapter.

Deploying Embedded Resource Adapters

For each application deployed in an OC4J instance that contains resource adapter(s), there should be one oc4j-connectors.xml file under $OC4J_HOME/application-deployments/<app-name>/.

The oc4j-connectors.xml file contains the list of resource adapters for a Web application packaged within an EAR file (one entry for each resource adapter).

The name and path of this file is defined in a new element called <connectors> under the <orion-application> element in orion-application.xml. (If no <connectors> element is specified in orion-application.xml, the default file is oc4j-connectors.xml).

A resource adapter archive, myPackaged.rar, is packaged within the EAR file myApp.ear. The application is then deployed with OC4J, under $OC4J_HOME/applications/myapp/myPackaged_rar.

If an oc4j-connectors.xml, which specifies a deployment name "myRA", is included in the .ear file; the generated oc4j-ra.xml file will be located in $OC4J_HOME/application-deployment/myapp/myRA/. An oc4j-connectors.xml file will be created under the $OC4J_HOME/application-deployment/myapp/ directory.

Example

Let's assume that a stand-alone resource adapter connection is configured in oc4j-ra.xml to be bound to the location eis/myEIS. An application component would look up its connection factory using the JNDI name "java:comp/env/eis/myEIS". The application component should have the resource-ref element defined in its deployment descriptor in web.xml or ejb-jar.xml, which may look like the following example:

<resource-ref> 
  <res-ref-name>eis/myEIS</res-ref-name> 
  <res-type>javax.resource.cci.ConnectionFactory</res-type> 
  <res-auth>Application</res-auth> 
  <res-sharing-scope>Shareable</res-sharing-scope> 
</resource-ref> 
--- 
try 
{ 
 Context ic = new InitialContext(); 
 user = (String) ic.lookup("java:comp/env/user"); 
 password = (String) ic.lookup ("java:comp/env/password"); 
cf = (ConnectionFactory) 
      ic.lookup("java:comp/env/eis/myEIS"); 
    } catch (NamingException ex) { 
ex.printStackTrace(); 
} 

Container-Managed Sign-on vs. Component-Managed Sign-on

The sign-on to the EIS system through a resource adapter can be managed either by the application component or by the application server, OC4J. This can be specified through the <res-auth> deployment descriptor element for EJB or web components. If the <res-auth> element is set to "Application", the application component would sign on to the EIS programmatically. The application component is responsible for providing explicit security information for the sign-on. If the <res-auth> element is set to "Container", OC4J will provide the resource principal and credentials required for signing on to the EIS.

Example of application code:

     Context initctx = new InitialContext(); 
     // perform JNDI lookup to obtain a connection factory 
     javax.resource.cci.ConnectionFactory cxf = 
       
(javax.resource.cci.ConnectionFactory)initctx.lookup("java:com/env/eis/MyEIS"); 
     // For container-managed sign-on, no security information is passed in the 
getConnection call 
     javax.resource.cci.Connection cx = cxf.getConnection(); 
     // If component-managed sign-on is specified, the code should instead 
provide explicit security 
     // information in the getConnection call 
     // We need to get a new ConnectionSpec implementation instance for setting 
login 
     // attributes 
     com.myeis.ConnectionSpecImpl connSpec = ... 
     connSpec.setUserName("EISuser"); 
     connSpec.setPassword("EISpassword"); 
     javax.resource.cci.Connection cx = cxf.getConnection(connSpec);

In either case, the createManagedConnection method in the resource adapter's implementation of javax.resource.spi.ManagedConnectionFactory interface will be called to create a physical connection to the EIS.

In the case of component-managed sign-on, OC4J will invoke the createManagedConnection method with a null Subject and the ConnectionRequestInfo object passed in from the application component code.

If container-managed sign-on is specified, OC4J will provide a javax.security.auth.Subject object to the createManagedConnection method. The content of the Subject object is different depending on the value in the <authentication-mechanism-type> and <credential-interface> elements in the resource adapter deployment descriptor.

If the <authentication-mechanism-type> is BasicPassword and the <credential-interface> is javax.resource.spi.security.PasswordCredential, the Subject object should contain javax.resource.spi.security.PasswordCredential objects in the private credential set.

On the other hand, if the <authentication-mechanism-type> is Kerbv5 or any other non-password based authentication mechanism that OC4J will support in the future, and the <credential-interface> is javax.resource.spi.security.GenericCredential, the Subject object should contain credentials represented by instances of implementers of the javax.resource.spi.security.GenericCredential interface. The GenericCredential interface is used for resource adapters that support non password-based authentication mechanism types such as Kerberos.