Configuring a Connector

Whether you download, buy, or create your own RAR, unless you get it from Oracle, it's unlikely to come preconfigured for OC4J. The next sections will describe how to take this generic RAR and customize it with server-specific settings.

Once you have a RAR, you can customize it for OC4J by adding the server-specific oc4j-ra.xml descriptor to its META-INF directory, as we'll discuss shortly. Usually, nothing else in the archive needs to be changed.

Basic Packaging and Configuration

A typical RAR contains Java libraries (JARs), native libraries (for example, something.dll, something.so ), and a META-INF directory with one or more descriptors, as shown here:

 /META-INF/ra.xml /connector-impl.jar /netutils.jar /winnt.dll /solaris.so /linux.so 

The code in the resource adapter is usually vendor specific. It doesn't need to contain any platform-specific binaries; it can be purely Java code.

Most importantly, it must contain the META-INF/ra.xml descriptor that defines the resource Connector. However, as noted earlier, you need to add the OC4J-specifc Connector descriptor, oc4j-ra.xml , before you can use the Connector in OC4J.

OC4J Connector Descriptor

In order for OC4J to load a resource Connector, it must contain the oc4j-ra.xml descriptor in its META-INF directory, alongside the standard ra.xml descriptor. If you obtain a Connector from a vendor other than Oracle, you'll need to add an oc4j-ra.xml descriptor to the META-INF directory. An example oc4j-ra.xml might look as follows :

 <?xml version="1.0"?> <!DOCTYPE oc4j-connector-factories    PUBLIC "-//Oracle//DTD Oracle Connector 1.0//EN"    "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories.dtd"> <oc4j-connector-factories>     <connector-factory connector-name="CICSAdapter" location="eis/CICS">        <config-property name="HostName" value="cicsserver.acme.com">        <config-property name="Port" value="1780">        <connection-pooling>           <description>CICS pool </description>           <property name="waitTimeout" value="90" />           <property name="scheme" value="fixed_wait" />           <property name="maxConnections" value="10" />           <property name="minConnections" value="5" />        </connection-pooling>        <security-config>           <principal-mapping-entries>              <default-mapping>                 <res-user>jdoe</res-user>                 <res-password>somepassword</res-password>              </default-mapping>              <principal-mapping-entry>                 <initiating-user>scott</initiating-user>                 <res-user>scott</res-user>                 <res-password>tiger</res-password>              </principal-mapping-entry>           </principal-mapping-entries>        </security-config>        <log><file path="/var/log/oc4j/cicsadapter.log"></log>     </connector-factory> </oc4j-connector-factories> 

Each of these elements is described in the following sections.

Configuring the Name and JNDI Location

The root element <connector-factory> allows you to specify a name and a global JNDI location, as shown here:

 <oc4j-connector-factories>     <connector-factory connector-name="CICSAdapter" location="eis/CICS"> ...     </connector-factory> </oc4j-connector-factories> 

The global JNDI location specified here can be used directly by the J2EE components, or it can be remapped to local JNDI locations in the descriptors for those components .

The Connector name is used when managing the Connector (for example, when deploying or undeploying it from the command line).

The JNDI name differs depending on the deployment mode (embedded or standalone). For standalone, the name will be eis/CICS ; for the embedded Connector it will be java:comp/env/eis/CICS .

Overriding Values from ra.xml

Within <connector-factory> , you can use one or more <config-property> elements to override property values set in the ra.xml descriptor. This is useful if you prefer not to change theresource archive provided by the EIS vendor.

The following example overrides the HostName property to be "cicsserver.acme.com" :

 <oc4j-connector-factories>     <connector-factory>         <config-property name="HostName" value="cicsserver.acme.com">     </connector-factory> </oc4j-connector-factories> 

Configuring Connection Pooling

Since connections often tie up system resources and are costly to initialize, it's usually appropriate to configure a connection pool. This lets you improve performance by reusing connections, and can also throttle requests to avoid overloading a resource.

A typical connection pool configuration might look like this:

 <oc4j-connector-factories>     <connector-factory>        <connection-pooling>           <property name="waitTimeout" value="90" />           <property name="scheme" value="fixed_wait" />           <property name="maxConnections" value="10" />           <property name="minConnections" value="5" />        </connection-pooling>     </connector-factory> </oc4j-connector-factories> 

The following four connection properties may be specified, as described in Table 12-1.

Table 12-1: Setting the Connection Pool Properties

Property	Description	Default
maxConnections	Maximum number of connections kept open in this pool. If specified, choose a scheme for handling additional requests.	none (unlimited)
minConnections	Minimum number of connections kept open in this pool. OC4J will attempt to open this many connections during initialization of the pool, though this may not be possible if connection creation depends on other services such as JNDI. If this is the case, OC4J will create as many connections as possible.
scheme	How additional requests should be handled when the maximum number of connections is in use. Setting this to dynamic allows additional connections to be created, which are closed immediately after use. Fixed will cause an exception to be thrown if there are no free connections. Fixed_wait will cause the request to block until a connection becomes available (subject to waitTimeout ).	none
none waitTimeout	Maximum number of seconds to wait for a free connection (if using fixed_wait ) before throwing an exception.	none

The optimal values for these properties vary depending on system limitations (memory, processing power) and typical usage patterns. If resource access is infrequent and connections are costly to maintain, it may be best to leave minConnections at 0. More often, you'll want to maximize runtime performance by ensuring that there are enough open connections to handle the typical number of concurrent requests. In either case, it's usually prudent to set an upper limit to avoid overwhelming the resource.

Tip 

When a software license only allows a certain number of concurrent connections to a resource, you can stay within this limit by setting the maxConnections to the appropriate value and using the fixed_wait scheme.

Configuring Security

Typically, you'll be connecting to a resource that requires authentication. Since the credentials used to log in to an application are often different from those used to access a different system, OC4J allows you to choose one of the options described in the following sections.

Signing On Programmatically from Within the Application

One of the most straightforward options is to have the application authenticate programmatically. In this case, credentials are often stored in properties files, environment entries, or database tables, and passed inside a ConnectionSpec object (basically a Java bean) defined by the Connector when requesting a connection from a ConnectionFactory . The ConnectionSpec implementation is used by the ConnectionFactory implementation in the Connector's archive to pass details of the connection.

The ConnectionSpec object is implemented in the SampleConnectionData class from the Connector you've created in the previous section of the chapter, as shown here:

 package com.apress.oc4j.connectors; import java.io.Serializable; import javax.resource.cci.ConnectionSpec; import javax.resource.spi.ConnectionRequestInfo; public class SampleConnectionData implements    ConnectionSpec, ConnectionRequestInfo, Serializable {     private String username;     private String password;     public String getPassword() {         return password;     }     public void setPassword(String password) {         this.password = password;     }     public String getUsername() {         return username;     }     public void setUsername(String username) {         this.username = username;     } } 

You can then use this ConnectionSpec implementation to pass custom connection data to the ConnectionFactory to obtain an instance of the Connection implemented by the Connector, as follows:

 Context ctx = new InitialContext(); ConnectionFactory connectionFactory = (ConnectionFactory)ctx.lookup("java:comp/env/SomeConnector"); SampleConnectionData spec = new SampleConnectionData(); spec.setUserName("scott"); spec.setPassword("tiger"); Connection c = connectionFactory.getConnection(connectionSpec); 

The code in the previous example translates to a call to ConnectionFactory.getConnection (ConnectionSpec) , which can be implemented like this in the Connector:

 package com.apress.oc4j.connectors; import javax.naming.NamingException; import javax.naming.Reference; import javax.resource.ResourceException; import javax.resource.cci.Connection; import javax.resource.cci.ConnectionFactory; import javax.resource.cci.ConnectionSpec; import javax.resource.cci.RecordFactory; import javax.resource.cci.ResourceAdapterMetaData; import javax.resource.spi.ConnectionManager; import javax.resource.spi.ManagedConnectionFactory; public class SampleConnectionFactory implements ConnectionFactory {  public Connection getConnection(ConnectionSpec connectionSpec)   throws ResourceException {  SampleConnectionData info;         if (connectionSpec instanceof SampleConnectionData) {             SampleConnectionData sd = (SampleConnectionData)connectionSpec;             info = sd;         } else {             throw new ResourceException("ConnectionSpec object is of type " +                 connectionSpec.getClass().getName() + " not SampleConnectionData");         }         // normally we would check the username/password here         return (Connection)connectionManager.allocateConnection(managedConnectionFactory, info);     } } 

Container-Managed Sign-On with XML Mapping

Another option is to provide mappings between application users and resource users and let OC4J manage the rest. These mappings can be either be specified in oc4j-ra.xml or handled dynamically by a Java Authentication and Authorization Service (JAAS) login module.

To specify the mappings in oc4j-ra.xml , place a <principal-mapping-entries> element (with one or more mapping entries) inside the <security-config> element, as follows:

 <oc4j-connector-factories>     <connector-factory>        <security-config>           <principal-mapping-entries>              <default-mapping>                 <res-user>scott</res-user>                 <res-password>tiger</res-password>              </default-mapping>              <principal-mapping-entry>                 <initiating-user>jsmith</initiating-user>                 <res-user>admin</res-user>                 <res-password>cheetah</res-password>              </principal-mapping-entry>           </principal-mapping-entries>        </security-config>     </connector-factory> </oc4j-connector-factories> 

The <default-mapping> entry is optional. If present, it will be used for any user principal that doesn't match another mapping entry.

A <principal-mapping-entry> should be specified for every application user that will not use the default. In the preceding example, requests on behalf of the application user jsmith will authenticate to the resource as admin/cheetah . All other requests will authenticate as scott/tiger .

When using XML mapping, any references to the resource within EJB or web deployment descriptors should set res-auth to Container to make sure that the container is managing the user principals and roles.

Container-Managed Sign-On with a JAAS Login Module

The JAAS provides standard interfaces for managing authentication. Rather than embed credentials in a descriptor or handle them within the application, you can find or implement a JAAS login module to handle the mapping. This can be very useful in Single Sign-On (SSO) environments.

Note 

For more information on JAAS, see Chapter 7.

Once you have a working JAAS login module, use the <jaas-module> element inside / oc4j-connector-factories/connector-factory/security-config in oc4j-ra.xml to tell it which module to use. In the following example, the container will use the JAAS login module that's registered under the name KerberosLoginModule :

 <security-config>   <jaas-module>     <jaas-application-name>KerberosLoginModule</jaas-application-name>   </jaas-module> </security-config> 

Configuring Transactions

There are no Connector-level transaction settings. It's also worth noting that the Connector must be able to support transactions. The Connector may declare that it can support transactions, but not actually implement the internal transaction control methods . The Connector, for example, implements LocalTransaction interface, but doesn't actually perform any transaction processingthe transaction control methods are implemented only as stubs.

Configuring Logging

Logging for Connectors is disabled by default. To enable it, include the <log> element in /oc4j-connector-factories/connector-factory with a valid file path such as this:

 <log><file path="/var/log/oc4j/cicsadapter.log"></log> 

If the directory or the log file itself exists and is writable, OC4J will begin logging this Connector's activity.