Assembling and Deploying Resource Adapters

Resource adapters can be packaged and deployed in very much the same way as you would package and deploy web applications or EJB components. A resource adapter includes all the Java classes and interfaces that implement the required contracts and functionality. It also may use platform-specific libraries that enable it to talk to the EIS. All these files, along with any help files and documentation, are packaged into a JAR file, called the resource adapter archive (RAR). Just like a WAR file or an EJB JAR, a RAR file also packages XML deployment descriptors, which specify the deploy-time and runtime configuration settings for the resource adapter.

7.1.1 Packaging

A typical RAR includes the following components:

• One or more JARs that contain all the Java interfaces, implementation, and utility classes required by the resource adapter.
• Any platform-dependent libraries needed by the resource adapter.
• Help files and documentation.
• XML deployment descriptors (ra.xml and weblogic-ra.xml) that encapsulate metadata and various configuration settings for the resource adapter. The XML descriptor files must be placed in the META-INF directory.

Example 7-1 lists the contents of a typical RAR file.

Example 7-1. Contents of a resource adapter module (eis.rar)

/ra.jar
/cci.jar
/win.dll
/solaris.so
/Overview.html
/GettingStarted.html
/ReleaseNotes.html
/LICENSE.txt
/META-INF/ra.xml
/META-INF/weblogic-ra.xml

Here, ra.jar and cci.jar contain the Java classes and interfaces that implement the functionality and client contracts for the resource adapter, while win.dll and solaris.so hold the platform-dependent libraries. In addition, the RAR file includes the HTML documentation and licensing information.

The standard ra.xml descriptor file captures important metadata, licensing information, and configuration settings for the transaction levels and authentication levels supported by the resource adapter. The WebLogic-specific weblogic-ra.xml descriptor file captures information about the JNDI name to which the connection factory will be bound, and additional parameters for configuring the behavior of a pool of managed connections, detecting connection leaks, and logging.

A RAR file can be created very simply by placing the contents in a staging directory say, rardir and then using the jar tool that comes with your JDK to create the archive:

jar cvf eis.rar -C rardir .

This creates a RAR file that then can be deployed to WebLogic. If you would like to deploy an existing RAR to WebLogic, you should update the Java archive to include the WebLogic-specific XML descriptor:

jar uf eis.rar -C rardir META-INF/weblogic-ra.xml

If you don't include the WebLogic-specific deployment descriptor, WebLogic automatically will include one for you when you deploy the RAR. In that case, the descriptor file will hold just dummy values that you can edit. At the very least, you will need to supply the classname for the connection factory and the JNDI name to which the connector should be bound. Your RAR also may reference support classes, perhaps shared with other modules deployed together in an EAR, in which case the JAR should include the standard JAR manifest file /META-INF/MANIFEST.MF, and it should use the Class-Path entry to point to any of the shared JARs used by the resource adapter.

7.1.2 Deployment

A resource adapter can be deployed directly to WebLogic Server by placing it under the applications folder in a WebLogic domain. In this case, the "standalone" resource adapter can be shared by multiple J2EE applications deployed to the server. Alternatively, the adapter can be bundled as part of a J2EE application alongside other J2EE modules such as web applications and EJB JARs. This is most appropriate if the resource adapter will be used only by the other J2EE modules within an enterprise application. WebLogic allows you to deploy a resource adapter in three ways:

• You can use WebLogic's deployer tool to deploy a resource adapter and target it to one or more servers:

  java weblogic.Deployer -adminurl http://localhost:7001 
   -username system -password mypassword -name eis.rar 
   -activate -targets myserver -source myappseis.rar

  Here, the resource adapter eis.rar is being deployed to the target server myserver. If the server has been started in development mode, in which the auto-deploy feature is enabled, you simply can drop the RAR file under the applications folder of your WebLogic domain and the resource adapter will be deployed as a standalone J2EE connector.

• You can use the Administration Console to configure a new J2EE connector for deployment. Start up the Administration Console and then select Deployments/Connector Modules from the left pane. Then, select the "Deploy a New Connector Module" link from the right pane to deploy a new resource adapter. Choose a RAR file for deployment using the file browser at the bottom, then select the name for the J2EE connector, and target the component to one or more server instances. Once the component is deployed, you can use the Administration Console to redeploy or undeploy the resource adapter.
• You can bundle a resource adapter inside an EAR file that subsequently is deployed to WebLogic. To achieve this, you need to perform the following actions:
  1. Package the J2EE Connector archive inside the EAR file in the same way as you would package a web application, EJB component, or any other JAR.
  2. Modify the standard application-level deployment descriptor /META-INF/application.xml to include a reference to the RAR file:

      My Application
      
      
      mywebapp
      /
      
      
      ejb_foo.jar
      
      
      eis.rar
      
      ...
     

     Also ensure that the XML descriptor /META-INF/application.xml includes the following DTD reference:

  Once you've deployed the EAR file to WebLogic, the resource adapter will then be accessible to all web applications and EJB components within that J2EE application.

7.1.3 XML Deployment Descriptors

A resource adapter requires you to package the standard ra.xml descriptor file and the optional WebLogic-specific weblogic-ra.xml descriptor file. You can use these XML descriptors to specify metadata and adjust the runtime configuration settings for the resource adapter. The ra.xml descriptor file is defined in the JCA Specification from Sun Microsystems. It must be a valid XML document with the following DOCTYPE:

The ra.xml descriptor lets you specify the following:

• A name and description for the resource adapter.
• The version of the J2EE connector and the JCA version with which it is compliant.
• The name of the EIS vendor that developed the resource adapter.
• The type of the EIS supported.
• Licensing information and whether a license is needed to use the J2EE connector.
• Fully qualified names for the ConnectionFactory and Connection classes and interfaces needed by the resource adapter.
• The level of transaction support provided by the J2EE connector.
• The authentication mechanism supported by the J2EE connector.

WebLogic Server supports only resource adapters that implement the BasicPassword authentication mechanism. If the J2EE connector supports only the Kerbv5 authentication mechanism or uses the javax.resource.spi.security.GenericCredential credential interface, you cannot deploy the resource adapter to WebLogic Server.

• Whether the resource adapter can reauthenticate existing managed connections.
• A set of configurable properties for the ManagedConnectionFactory instance. Each property is defined in terms of name, an optional description, type, and an optional default value.

A resource adapter can support one of three transaction levels: NoTransaction, LocalTransaction, or XATransaction. The JCA framework also provides for a set of well-defined configurable properties for a ManagedConnectionFactory, all of type java.lang.String:

 ServerName
 PortNumber
 UserName
 Password
 ConnectionURL

These properties closely mimic the connection properties associated with a JDBC connection pool.

The weblogic-ra.xml descriptor file captures configuration settings specific to the runtime environment provided by WebLogic Server. As of WebLogic Server 8.1, the descriptor file must be a valid XML document conforming to the following DOCTYPE:

Using the weblogic-ra.xml descriptor file, you can specify the following:

• A logical name for the connection factory associated with the resource adapter.
• The JNDI name to which the connection factory is bound. EJBs and servlets can use this JNDI name to reference this resource adapter in their XML descriptors.
• The location of the folder where all native libraries will be copied during deployment.
• Configuration settings that describe the behavior of the pool of managed connections.
• Whether logging is enabled for the J2EE connector, and if so, the name of the log file to which log messages are written.
• Values for the configurable properties defined earlier in the config-entry element of the ra.xml descriptor file.

We'll take a closer look at the structure of this XML descriptor file in later sections. In the meantime, you can view and configure the important deployment descriptors using the Administration Console. Select the desired connector module from the left pane, and then choose the Configuration/Descriptor option. These options are available only if the connector is deployed in an exploded form. If it is deployed as a RAR file, you need to unpack and edit the XML files using either your favorite XML editor or WebLogic Builder.