Programming WebLogic Resource Adapters

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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 Developing Applications with WebLogic Server.


Packaging Resource Adapters

For production and development purposes, BEA 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 Listing 9-1:

Listing 9-1 Resource Adapter Directory Structure

Packaging Considerations

The following are packaging requirements for resource adapters:

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 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, 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 a Split Development Directory Environment in Developing Applications with 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.
  6. Note: Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition at:
  7. Create a weblogic-ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.
  8. Note: Refer to weblogic-ra.xml Schema, for information on the contents of the weblogic-ra.xml file.
  9. 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:
  10. 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:

For information about these application deployment techniques, see Deploying Applications and Modules in Deploying Applications to 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 Deploying Applications to 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 Deploying Applications to 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.

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 Updating Applications in a Production Environment in Deploying Applications to 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.

  Back to Top       Previous  Next