Programming WebLogic Server J2EE Connectors

Packaging and Deploying Connectors

This chapter discusses packaging and deploying requirements for connectors and provides instructions for performing these tasks.

WebLogic Server application deployment is covered in more detail in Deploying WebLogic Server Applications. WebLogic Server application packaging is covered in more detail in Creating WebLogic Server Applications in Developing WebLogic Server Applications. This topics covered in this section discuss packaging and deployment procedures that are specific to connectors.

Packaging Connectors

For production and development purposes, BEA recommends packaging your assembled resource adapter (RAR) as part of an enterprise application (EAR). If you are packaging an existing resource adapter, you can take advantage of the split directory structure. This structure offers many benefits, which are discussed in in Creating WebLogic Server Applications in Developing WebLogic Server Applications. If you are building a resource adapter from scratch, you should still package your resource adapter in an EAR, but the split development directory structure is not currently supported in this case.

Packaging Directory Structure

A resource adapter is a WebLogic Server component contained in a resource adapter archive (RAR) within the applications/ directory. The deployment process begins with the RAR or a deployment directory, both of which contain the compiled resource adapter interfaces and implementation classes created by the resource adapter provider. Regardless of whether the compiled classes are stored in a RAR or a deployment directory, they must reside in subdirectories that match their Java package structures.

Resource adapters use a common directory format. This same format is used when a resource adapter is packaged in an exploded directory format as a RAR. A resource adapter is structured as in the following example:

Listing 5-1 Resource Adapter Directory Structure

/META-INF/ra.xml

/META-INF/weblogic-ra.xml

/META-INF/MANIFEST.MF (optional)

/images/ra.jpg

/readme.html

/eis.jar

/utilities.jar

/windows.dll

/unix.so

Packaging Considerations

The following are packaging requirements for resource adapters:

Deployment descriptors (ra.xml and weblogic-ra.xml) must be in a subdirectory called META-INF.
An optional MANIFEST.MF also resides in META-INF. A manifest file is automatically generated by the JAR tool and is always the first entry in the JAR file. By default, it is named META-INF/MANIFEST.MF. The manifest file is the place where any meta-information about the archive is stored. For more information, see http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/jar.html.
The resource adapter can contain multiple JARs that contain the Java classes and interfaces used by the resource adapter. (For example, eis.jar and utilities.jar)
The resource adapter can contain native libraries required by the resource adapter for interacting with the EIS. (For example, windows.dll and unix.so)
The resource adapter can include documentation and related files not directly used by the resource adapter. (For example, readme.html and /images/ra.jpg)
Ensure that any dependencies of a resource adapter on platform-specific native libraries are resolved.
When a standalone resource adapter RAR is deployed, the resource adapter must be made available to all J2EE applications in the application server.
When a resource adapter RAR packaged within a J2EE application EAR is deployed, the resource adapter must be made available only to the J2EE application with which it is packaged.
A resource adapter deployed in WebLogic Server supports the CLASSPATH entry in MANIFEST.MF to reference a class or resource such as a property.

For more information on packaging requirements, refer to chapter 10 of the J2EE Connector Specification, Version 1.0 Final Release (http://java.sun.com/j2ee/download.html#connectorspec).

Packaging Limitations

The following are WebLogic Server packaging limitations on resource adapters:

The WebLogic J2EE Connector Architecture does not support the javax.resource.spi.security.GenericCredential credential-interface or the Kerbv5 authentication-mechanism-type. Specification of either of these values for the <authentication-mechanism> in the ra.xml file for the resource adapter being deployed will result in a failed deployment.
The WebLogic J2EE Connector Architecture does not allow you to reload a standalone resource adapter without reloading the client that is using it. (This limitation is due to the J2EE Connector Specification, Version 1.0 limitation of not providing a remotable interface.)
The ConnectionPoolManager's getConnection(ManagedConnectionFactory mcf, ConnectionRequestInfo cxInfo) method throws an exception internal to WebLogic Server when it is unable to find a ConnectionPool associated with a given ManagedConnectionFactory. For more information, see Troubleshooting.

Packaging Connector Archives (RARs)

After you stage one or more resource adapters in a directory, you package them in a Java Archive (JAR). Before you package your resource adapters, be sure you read and understand the chapter entitled WebLogic Server Application Classloading" in Developing WebLogic Server Applications, which describes how WebLogic Server loads classes.

Note: Once you have assembled the resource adapter, BEA recommends that you package it as part of an enterprise application. This allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure. See Creating WebLogic Server Applications in Developing WebLogic Server Applications.

To stage and package a resource adapter:

Create a temporary staging directory anywhere on your hard drive.

Compile or copy the resource adapter Java classes into the staging directory.

Create a JAR to store the resource adapter Java classes. Add this JAR to the top level of the staging directory.

Create a META-INF subdirectory in the staging directory.

Create an ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

Note: Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition at: http://java.sun.com/dtd/connector_1_0.dtd

Create a weblogic-ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

Note: Refer to weblogic-ra.xml Deployment Descriptor Elements, for information on the weblogic-ra.xml document type definition.

When the resource adapter classes and deployment descriptors are set up in the staging directory, you can create the RAR with a JAR command such as:

jar cvf jar-file.rar -C staging-dir

This command creates a RAR that you can deploy on a WebLogic Server or package in an enterprise application archive (EAR).
The -C staging-dir option instructs the JAR command to change to the staging-dir directory so that the directory paths recorded in the JAR are relative to the directory where you staged the resource adapters.

For more information on this topic, see Creating and Modifying Resource Adapters: Main Steps.

Deploying Connectors

Deployment of a connector is similar to deployment of Web Applications, EJBs, and Enterprise Applications. Like these deployment units, you can deploy a resource adapter in an exploded directory format or as an archive file.

Deployment Options

You can deploy a stand-alone resource adapter (or a resource adapter packaged as part of an enterprise application):

Using the WebLogic Server Administration Console.
Using the weblogic.Deployer Utility.
Using auto-deployment. This is useful for testing purposes. For more information,

For more information on these tools, see Deployment Tools Reference in Deploying WebLogic Server Applications.

Deployment Descriptor

Also similar to Web Applications, EJBs, and Enterprise Applications, resource adapters use two deployment descriptors to define their operational parameters. The deployment descriptor ra.xml is defined by Sun Microsystems in the J2EE Connector Specification, Version 1.0 Final Release. The weblogic-ra.xml deployment descriptor is specific to WebLogic Server and defines operational parameters unique to WebLogic Server. For more information about the weblogic-ra.xml deployment descriptor, refer to weblogic-ra.xml Deployment Descriptor Elements.

You can modify deployment descriptors using the following tools:

WebLogic Builder. WebLogic Builder is a WebLogic Server tool for generating and editing deployment descriptors for J2EE applications. It can also deploy applications to single servers.For more information, see Deployment Tools Reference in Deploying WebLogic Server Applications.
An XML Editor with DTD validation, such as BEA XML Editor on dev2dev or XMLSpy. (An evaluation copy of XMLSpy is bundled with this version of WebLogic Server.) See BEA dev2dev Online http://dev2dev.bea.com/index.jsp.
Using the Administration Console Descriptor tab. The Descriptor tab has replaced the deprecated Deployment Descriptor Editor in the Administration Console. For more information on the Descriptor tab, see the WebLogic Server online help. Also refer to Dynamic Descriptor Updates.

Connector Deployment Names

When you deploy a connector archive (RAR) or deployment directory, you must specify a name for the deployment unit, for example, myResourceAdapter. This name provides a shorthand reference to the resource adapter deployment that you can later use to undeploy or update the resource adapter.

When you deploy a resource adapter, WebLogic Server implicitly assigns a deployment name that matches the path and filename of the RAR or deployment directory. You can use this assigned name to undeploy or update the resource adapter after the server has started.

The resource adapter deployment name remains active in WebLogic Server until the server is rebooted. Undeploying a resource adapter does not remove the associated deployment name; you can use the same deployment name to redeploy the resource adapter at a later time.