8 J2EE Connector Architecture (J2CA)

Standalone Resource Adapters

A resource adapter module that can be deployed directly into an application server independent of other applications is called a standalone resource adapter. These adapters, which are stored in standalone resource adapter archive (RAR) files, are available to all applications that are deployed in the application server instance. See "Example of RAR File Structure" for an example of the contents and structure of an RAR archive.

Embedded Resource Adapters

A resource adapter module that is deployed as part of a J2EE application that also contains one or more J2EE modules, is called an embedded resource adapter. These adapters are available only to the J2EE applications with which they are bundled in an enterprise application archive (EAR) file.

Example of RAR File Structure

Here is an example of the contents and structure of an RAR archive:

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

Depending on the resource adapter, applications or application modules might need to access adapter-specific classes that are bundled with the RAR. In the case of standalone resource adapters, these custom classes are available to all applications that are deployed within OC4J. In the case of embedded resource adapters, they are available only to modules that are part of the same application as the embedded adapter.

The ra.xml Descriptor

The ra.xml descriptor is the standard J2EE deployment descriptor for resource adapters. For details, see the J2EE Connector Architecture 1.0 specification.

The oc4j-ra.xml Descriptor

The oc4j-ra.xml descriptor provides OC4J-specific deployment information for resource adapters. The file contains one or more <connector-factory> elements.

You can do the following using oc4j-ra.xml:

• Configure and bind instances of connection factories.

  Connection factories are used by application components to obtain connections to the EIS. The name of the connection factory class is specified in the connectionfactory-impl-class element, defined in ra.xml. OC4J allows the deployer to configure instances of this class and to bind them to the Java Naming and Directory Interface (JNDI) name space.

  The deployer can do this by creating <connector-factory> elements and assigning a JNDI location to each using the location attribute. The deployer can also configure each instance using <config-property> elements.

  The list of configurable properties is specified in ra.xml, as <config-property> elements. The deployer can either specify or override values for these properties in oc4j-ra.xml, using <config-property> elements.

  Example: Consider a resource adapter with a connection factory implementation of com.example.eis.ConnectionFactoryImpl. Assume that this adapter has been deployed standalone with one configured connection factory, whose JNDI location is myEIS/connFctry1. The <connector-factory> has been configured to connect to host myMc123 on port 1999. Also assume there is an EJB application that looks up and use this connection factory, using a logical name of eis/myEIS.

  The following are the files that are relevant to this example.

  ra.xml: Specification of connection factory implementation (as provided by the resource adapter vendor).

  <resourceadapter>
      ...
      <config-property>
          <config-property-name>HostName</config-property-name>
          <config-property-type>java.lang.String</config-property-type>
      </config-property>
      <config-property>
          <config-property-name>Port</config-property-name>
          <config-property-type>java.lang.Integer</config-property-type>
          <config-property-value>2345</config-property-value>
      </config-property>
      <connectionfactory-impl-class>
          com.example.eis.ConnectionFactoryImpl
      </connectionfactory-impl-class>
      ...
  </resourceadapter>
  
  

  oc4j-ra.xml: Specification of connection factory implementation with properties myMc123 (host) and 1999 (port), to be bound to JNDI location myEIS/connFctry1 (likely generated by OC4J and edited by deployer).

  <connector-factory location="myEIS/connFctry1">
      ...
      <config-property>
          <config-property-name>HostName</config-property-name>
          <config-property-value>myMc123</config-property-value>
      </config-property>
      <config-property>
          <config-property-name>Port</config-property-name>
          <config-property-value>1999</config-property-value>
      </config-property>
      ...
  </connector-factory>
  

  
  

  Note: The <config-property-type> element does not appear in the oc4j-ra.xml file because the type cannot be changed.

  
  

  ejb-jar.xml: Specification of resource reference (that is, connection factory) accessed by EJB (as provided by the application vendor).

  <resource-ref> 
    <res-ref-name>eis/myEIS</res-ref-name> 
    <res-type>javax.resource.cci.ConnectionFactory</res-type> 
    <res-auth>Application</res-auth> 
  </resource-ref>
  
  

  orion-ejb-jar.xml: Mapping of the logical reference name to the real JNDI name (likely generated by OC4J and edited by deployer).

  <resource-ref-mapping name ="eis/myEIS" location ="myEIS/connFctry1"/>
  
  

  EJB class: Usage of the connection factory (created by developer).

  try
  {
      Context ic = new InitialContext();
      cf = (ConnectionFactory) ic.lookup("java:comp/env/eis/myEIS");
  } catch (NamingException ex) {
      ex.printStackTrace();
  }
  
  

• Customize connection pooling

  The deployer can configure connection pooling for each instance of a connection factory using the <connection-pooling> element. This element is discussed under "Configuring Connection Pooling".

• Manage authentication

  The deployer can use the <security-config> element to configure an authentication scheme for each instance of a connection factory. This element is applicable only if application components use container-managed sign-on. Also see "Managing EIS Sign-On".

• Set up logging

  The deployer can set up logging, per connection factory instance, using the <log> element. Here is an example:

   <connector-factory location="myEIS/connFctry1">
           <log>
                   <file path="./logConnFctry1.log" />
           </log>
   </connector-factory>
  
  

  If the path name is not specified or if the directory does not exist, logging is not enabled and OC4J prints out a warning message. If the directory exists but the file does not, OC4J creates the file and enables logging. Because there is no default location for the log file, if the <log> element is not specified, logging is not enabled.

  Additionally, the deployer can also add a <description> element to each <connector-factory> element. The element contains a description of the connection factory and is not interpreted by OC4J.

The oc4j-connectors.xml Descriptor

The resource adapters that are deployed to OC4J can be configured through the oc4j-connectors.xml descriptor. There is one oc4j-connectors.xml file for all of the standalone adapters (as a group) as well as one per application.

The root element is <oc4j-connectors>. Each individual connector is represented by a <connector> element that specifies the name and path name for the connector. Each <connector> element contains the following elements:

• <description>: text description of the connector. It is not interpreted by OC4J. This element is optional.

• <native-library path="pathname">: directory containing native libraries. If you do not specify this element, OC4J expects the libraries to be located in the directory containing the decompressed RAR directory. OC4J interprets the pathname attribute relative to the decompressed RAR directory. This element is optional.

• <security-permission enabled="booleanvalue">: permissions to be granted to each resource adapter. Each <security-permission> contains a <security-permission-spec> that conforms to the Java 2 Security policy file syntax.

  OC4J automatically generates a <security-permission> element in oc4j-connectors.xml for each <security-permission> element in ra.xml. Each generated element has the enabled attribute set to false. Setting the enabled attribute to true grants the named permission. That is, the deployer has to explicitly grant the permissions requested by the resource adapter. The default behavior of OC4J is to not grant those permissions during deployment.

  Example:

  <oc4j-connectors> 
    <connector name="myEIS" path="eis.rar"> 
      <native-library> path="lib"</native-library> 
      <security-permission>
        <security-permission-spec enabled="false">
          grant {permission java.lang.RuntimePermission "LoadLibrary.*"};
        </security-permission-spec>
      </security-permission>
    </connector> 
  </oc4j-connectors>
  
  

  
  

  Note: The path attribute of the <native-library> element should point to the directory in which the .dll or .so files are located. For the preceding example, here is a possible RAR structure: /META-INF/ra.xml /ra.jar /lib/win.dll /lib/solaris.so

  
  

Deployment

During deployment, OC4J decompresses the RAR file and creates OC4J-specific deployment descriptor files if they do not exist already. The deployment process automatically adds <connector> entries in the oc4j-connectors.xml file. Skeleton entries for <connector-factory> elements are created as well in oc4j-ra.xml. The deployer can edit these two files for further configuration. For more information, see the Oracle Application Server Administrator's Guide.

You deploy standalone resource adapters in one of the following ways:

• Deploying and Undeploying Using dcmctl

• Deploying and Undeploying Using admin.jar

dcmctl deployApplication -f example.rar -a example

dcmctl undeployApplication -a example

-deployconnector -file mypath.rar -name myname -nativeLibPath libpathname -grantAllPermissions

Example:

java -jar admin.jar ormi://localhost admin welcome -deployconnector -file ./myRA.rar -name myRA

Deploying Manually

If you prefer to deploy your connector manually, follow these steps:

1. Create a connectorname directory under OC4J_HOME/connectors_dir.

2. Copy the connector's RAR file into OC4J_HOME/connectors_dir/connectorname.

3. Create an oc4j-connectors.xml file in connectors_dir for the new resource adapter, or add a <connector> element to the file if it already exists.

4. Restart OC4J. OC4J generates a new oc4j-ra.xml in OC4J_HOME/application-deployments/default/connectorname for the adapter. You must modify the generated file to contain a <connector_factory> element that is appropriate for your connector.

To remove a deployed resource adapter, use the -undeployconnector switch of admin.jar. Here is the syntax:

-undeployconnector -name myname

The required -name argument specifies which adapter is being removed. This command removes all <connector> entries that use the specified resource adapter from oc4j-connectors.xml and deletes the directories and files that were created during deployment.

Deployment

As part of deploying the EAR file that contains the embedded resource adapter, OC4J decompresses the RAR file and creates OC4J-specific deployment descriptor files if they do not exist already. The deployment process automatically adds <connector> entries in the oc4j-connectors.xml file. Skeleton entries for <connector-factory> elements are created as well in oc4j-ra.xml. The deployer can edit these two files for further configuration.

Deploy applications that include embedded resource adapters in one of the following ways:

• Deploying Using dcmctl

• Deploying Using admin.jar

Component-Managed Sign-On

When deploying applications that manage EIS sign-on by themselves, set <res-auth> to Application. The application component is responsible for providing explicit security information for the sign-on.

Figure 8-2 shows the steps involved in component-managed sign-on. The steps are detailed following the diagram.

Figure 8-2 Component-Managed Sign-On

Description of the illustration O_1078.gif

1. The client makes a request, which is associated with an incoming security context.

2. As part of servicing the request, the application component maps the incoming security context to an outgoing security context and then uses the outgoing security context to request a connection to the EIS.

3. As part of the connection acquisition, the resource adapter logs on to the EIS using the outgoing security context provided by the application component.

4. Once the connection is acquired, the application component can interact with the EIS under the established outgoing security context.

The following example is an excerpt from an application that performs component-managed sign-on.

Example:

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");

// 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);

Container-Managed Sign-On

When deploying applications that depend on the container for EIS sign-on, set <res-auth> to Container. The container is responsible for providing security information for the sign-on. Additionally, the container uses deployment descriptors or pluggable authentication classes to determine outgoing security context.

shows the steps involved in container-managed sign-on. The steps are detailed following the diagram.

Figure 8-3 Container-Managed Sign-On

Description of the illustration O_1079.gif

1. The client makes a request, which is associated with an incoming security context.

2. As part of servicing the request, the application component requests a connection to the EIS.

3. As part of the connection acquisition, the container (the OC4J security context manager shown in ) maps the incoming security context to outgoing security context, based on deployment descriptor elements (not shown in the figure) or authentication class provided.

4. The resource adapter logs on to the EIS using the outgoing security context provided by the container.

5. Once the connection is acquired, the application component can interact with the EIS under the established outgoing security context.

The following example is an excerpt from an application that depends on container-managed sign-on.

Example:

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();

OC4J-Specific Authentication Classes

OC4J provides the oracle.j2ee.connector.PrincipalMapping interface for principal mapping. Its methods appear in Table 8-2.

To use OC4J-specific programmatic container-managed sign-on, an implementation of this interface must be provided.

When a connection to the EIS is created, OC4J invokes the mapping method with the initiating user as the initiatingPrincipal. The mapping method must return a Subject containing the resource principal and credential. The Subject that is returned must adhere to either option A or option B in section 8.2.6 of the Connector Architecture 1.0 specification.

OC4J also provides the abstract class oracle.j2ee.connector.AbstractPrincipalMapping. This class furnishes a default implementation of the setManagedConnectionFactory() and setAuthenticationMechanism() methods, as well as utility methods to determine whether the resource adapter supports the BasicPassword or Kerberos version 5 (Kerbv5) authentication mechanisms, and a method for extracting the Principal from the application server user Subject. By extending the oracle.j2ee.connector.AbstractPrincipalMapping class, developers need only implement the init and mapping methods.

The methods exposed by the oracle.j2ee.connector.AbstractPrincipalMapping class appear in Table 8-4.

package com.acme.app;

import java.util.*;
import javax.resource.spi.*;
import javax.resource.spi.security.*;
import oracle.j2ee.connector.AbstractPrincipalMapping;
import javax.security.auth.*;
import java.security.*;

public class MyMapping extends AbstractPrincipalMapping
{
  String m_defaultUser;
  String m_defaultPassword;

  public void init(Properties prop)
  {
    if (prop != null)
    {
      // Retrieves the default user and password from the properties
      m_defaultUser = prop.getProperty("user");
      m_defaultPassword = prop.getProperty("password");
    }
  }
  public Subject mapping(Subject initiatingSubject)
  {
    // This implementation only supports BasicPassword authentication
    // mechanism. Return if the resource adapter does not support it.
    if (!isBasicPasswordSupported())
      return null;
    // Use the utility method to retrieve the Principal from the
    // OC4J user. This code is included here only as an example.
    // The principal obtained is not being used in this method.
    Principal principal = getPrincipal(initiatingSubject);
    char[] resPasswordArray = null;    
    if (m_defaultPassword != null)
      resPasswordArray = m_defaultPassword.toCharArray();
    // Create a PasswordCredential using the default user name and
    // password, and add it to the Subject per option A in section
    // 8.2.6 in the Connector 1.0 spec.
    PasswordCredential cred =
      new PasswordCredential(m_defaultUser, resPasswordArray);
    cred.setManagedConnectionFactory(getManagedConnectionFactory());
    initiatingSubject.getPrivateCredentials().add(cred);
    return initiatingSubject;
  }
}

<connector-factory name="..." location="...">
  ...
  <security-config>
    <principal-mapping-interface>
      <impl-class>com.acme.app.MyMapping</impl-class>
      <property name="user" value="scott" />
      <property name="password" value="tiger" />
    </principal-mapping-interface>
  </security-config>
  ...
</connector-factory>

JAAS Pluggable Authentication Classes

You can also manage sign-on to the EIS programmatically with JAAS. OC4J furnishes a JAAS pluggable authentication framework that conforms to Appendix C in the Connector Architecture 1.0 specification. With this framework, an application server and its underlying authentication services remain independent from each other, and new authentication services can be plugged in without requiring modifications to the application server.

Some examples of authentication modules are:

• Principal Mapping JAAS module

• Credential Mapping JAAS module

• Kerberos JAAS module (for Caller Impersonation)

The JAAS login modules can be furnished by the customer, the EIS vendors, or the resource adapter vendors. Login modules must implement the javax.security.auth.spi.LoginModule interface, as documented in the Sun JAAS specification.

OC4J provides initiating user subjects to login modules by passing an instance of javax.security.auth.Subject containing any public certificates and an instance of an implementation of java.security.Principal representing the OC4J user. OC4J can pass a null Subject if there is no authenticated user (that is, an anonymous user). The initiating user subject is passed to the initialize method of the JAAS login module.

The JAAS login module's login method must, based on the initiating user, find the corresponding resource principal and create new PasswordCredential or GenericCredential instances for the resource principal. The resource principal and credential objects are then added to the initiating Subject in the commit method. The resource credential is passed to the createManagedConnection method in the javax.resource.spi.ManagedConnectionFactory implementation that is provided by the resource adapter.

If a null Subject is passed, the JAAS login module is responsible for creating a new javax.security.auth.Subject containing the resource principal and the appropriate credential.

  <connector-factory connector-name="myBlackbox" location="eis/myEIS1"> 
    <description>Connection to my EIS</description>
    <config-property name="connectionURL"
        value="jdbc:oracle:thin:@localhost:5521:orcl" />
    <security-config>
      <jaas-module>
        <jaas-application-name>JAASModuleDemo</jaas-application-name>
      </jaas-module>
    </security-config>
  </connector-factory>

Special Features Accessible Via Programmatic Interface

In addition to mapping from OC4J users to EIS users, login modules and OC4J-specific authentication classes can also map from OC4J groups to EIS users.

The the oracle.j2ee.connector package contains the InitiatingPrincipal class that represents OC4J users and the InitiatingGroup class that represents OC4J groups. OC4J creates instances of InitiatingPrincipal and incorporates them into the Subject that is passed to the initialize method of the login modules as well as to the mapping method of the OC4J-specific authentication class.

The the oracle.j2ee.connector package also contains the InitiatingPrincipal class that implements the java.security.Principal interface and adds the method getGroups(). The getGroups method returns a java.util.Set of oracle.j2ee.connector.InitiatingGroup objects, representing the OC4J groups or JAZN roles that this OC4J user belongs to. The group membership is defined in OC4J-specific descriptor files such as principals.xml or jazn-data.xml, depending on the user manager. The oracle.j2ee.connector.InitiatingGroup class implements but does not extend the functionality of the java.security.Principal interface.