9 Packaging and Deploying Resource Adapters

The following sections describe how to package and deploy resource adapters:

Deploying applications on WebLogic Server is covered in more detail in "Deploying and Packaging from a Split Development Directory" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

Packaging Resource Adapters

For production and development purposes, Oracle recommends packaging your assembled resource adapter (RAR) as part of an enterprise application (EAR).

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 the same directory format, whether the resource adapter is packaged in an exploded directory format or as a RAR. A typical directory structure of a resource adapter is shown in Example 9-1:

Example 9-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 directory 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.

  • A resource adapter deployed in WebLogic Server supports the class-path entry in MANIFEST.MF to reference a class or resource such as a property.

  • 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.) Ensure that any dependencies of a resource adapter on platform-specific native libraries are resolved.

  • 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.)

  • 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. This specification-compliant behavior may be overridden if required.

Packaging Limitation

If you reload a standalone resource adapter without reloading the client that is using it, the client may cease to function properly. This limitation is due to the J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/) limitation of not providing a remotable interface.

Packaging Resource Adapter Archives (RARs)

After you stage one or more resource adapters in a directory, you package them in a Java Archive (JAR) with a .rar file extension.

Note:

Once you have assembled the resource adapter, Oracle 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 a Split Development Directory Environment" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

To stage and package a resource adapter:

  1. Create a temporary staging directory anywhere on your hard drive.

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

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

  4. Create a META-INF subdirectory in the staging directory.

  5. 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/xml/ns/j2ee/connector_1_5.xsd.
  6. Create a weblogic-ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

    Note:

    Refer to Appendix A, "weblogic-ra.xml Schema" for information on the contents of the weblogic-ra.xml file.
  7. 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 Configuring Resource Adapters: Main Steps.

Deploying Resource Adapters

Deployment of a resource adapter 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 any one of these tools:

  • WebLogic Server Administration Console

  • weblogic.Deployer tool

  • wldeploy Ant task

  • WebLogic Scripting Tool (WLST)

For information about these application deployment techniques, see "Deploying Applications and Modules with weblogic.deployer" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

You can use a deployment plan to deploy a resource adapter deployment. For a resource adapter, a WebLogic Server deployment plan is an optional XML document that resides outside of the RAR and configures the resource adapter for deployment to a specific WebLogic Server environment. A deployment plan works by setting deployment property values that would normally be defined in the resource adapter's deployment descriptors, or by overriding property values that are already defined in the deployment descriptors. For information on deployment plans, see "Configuring Applications for Production Deployment" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

You can also deploy a resource adapter using auto-deployment. This may be useful during development and early testing. For more information, see "Auto-Deploying Applications in Development Domains" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

Resource Adapter Deployment Names

When you deploy a resource adapter 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.

Production Redeployment

Using WebLogic Server's production redeployment feature, you can redeploy a new version of a WebLogic Server application alongside an older version of the same application. By default, WebLogic Server immediately routes new client requests to the new version of the application, while routing existing client connections to the older version. After all clients using the older application version complete their work, WebLogic Server retires the older application so that only the new application version is active.

Suspendable Interface and Production Redeployment

Typically, a resource adapter bean implements the javax.resource.spi.ResourceAdapter interface. This interface defines start() and stop() methods. This type of resource adapter is not eligible for production redeployment. Resource adapters connect to one or more EISes for incoming/outgoing communication. All communication is performed in a resource adapter-proprietary way with no knowledge of the application server. If on-the-fly production redeployment is attempted, the application server can only provide notifications to the resource adapter to manage the migration of connections from the existing resource adapter to a new instance. However, the resource adapter can implement the Suspendable interface, which provides the capability to allow resource adapters to participate in production redeployment. For information about implementing the Suspendable interface, see Suspending and Resuming Resource Adapter Activity.

Production Redeployment Requirements

All of the following requirements must be met by both the old and new version of the resource adapter in order for production redeployment to work; otherwise, the redeployment fails.

  • The resource adapter must be based on the J2CA 1.5 Specification. (Support for production redeployment of 1.0 resource adapters is not available.)

  • The resource adapter must implement the Suspendable interface (see Example 4-3).

  • The resource adapter must be packaged inside an enterprise application (EAR file). Production redeployment of standalone resource adapters is not supported.

  • The Suspendable.supportsVersioning() method must return true when invoked by WebLogic Server.

  • The enable-access-outside-app element in the weblogic-ra.xml descriptor must be set to false.

Production Redeployment Process

The following process assumes the older version of the resource adapter is deployed and running. It also assumes that the older version (named old) as well as the newer version (named new) of the resource adapter meet all of the requirements mentioned in Production Redeployment Requirements, as well as the application requirements described in "Redeploying Applications in a Production Environment" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

The following calls are made into the resource adapters during production redeployment:

  1. WebLogic Server calls new.init(old, null) to inform the new resource adapter that it is replacing the old resource adapter.

  2. WebLogic Server calls old.startVersioning(new, null) to inform the old resource adapter to start its production redeployment operation with the new resource adapter.

  3. WebLogic Server calls new.start(extendedBootstrapContext). See Extended BootstrapContext.

  4. When the old resource adapter is "finished" (meaning it has succeeded in migrating all clients and inbound connections to the new resource adapter), it calls (ExtendedBootstrapContext)bsCtx.complete(). This informs WebLogic Server that it is safe to undeploy the old resource adapter.

  5. When undeployment occurs, WebLogic Server calls old.stop() and production redeployment is complete.

The calls to new.init() and old.startVersioning() give the old and new resource adapters an opportunity to migrate inbound or outbound communications from the old to the new resource adapter. How this is done is up to the individual resource adapter developer.