Packaging and Deploying Resource Adapters

9 Packaging and Deploying Resource Adapters

To deploy a WebLogic resource adapter, you first package it in a resource adapter archive (RAR) file, and them deploy it in either an exploded directory format or as an archive file. There are requirements for creating the RAR file depending on several factors, such as whether the resource adapter is deployed standalone or with a Java EE application EAR, and also considerations regarding how you want to deploy it.

Deploying applications on WebLogic Server is covered in more detail in Deploying and Packaging from a Split Development Directory in 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). There are several factors to consider when packaging resources adapters, such as the packaging directory structure, dependencies on platform-specific native libraries, and more.

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 Java EE applications in the application server.
When a resource adapter RAR packaged within a Java EE application EAR is deployed, the resource adapter must be made available only to the Java EE 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 JSR 322: Java EE Connector Architecture 1.6 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 Developing Applications for Oracle WebLogic Server.

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 document for information about the ra.xml document type definition: http://xmlns.jcp.org/xml/ns/javaee/connector_1_7.xsd.
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 Schema for information on the contents of the weblogic-ra.xml file.
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

The deployment of a resource adapter is similar to the deployment of web applications, EJBs, and Enterprise Applications. As with these deployment units, you can deploy a resource adapter in an exploded directory format or as an archive file. WebLogic Server also provides a number of deployment options to choose from, including whether to use the production redeployment feature, which allows you to redeploy a new version of an application alongside an older version of the same application and thereby eliminate downtime.

Deployment Options

You can deploy a standalone 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 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 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 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 Connector Architecture 1.7. (Support for production redeployment of 1.0 resource adapters is not available.)
The resource adapter must implement the Suspendable interface (see Example 3-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 Deploying Applications to Oracle WebLogic Server.

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

WebLogic Server calls new.init(old, null) to inform the new resource adapter that it is replacing the old resource adapter.
WebLogic Server calls old.startVersioning(new, null) to inform the old resource adapter to start its production redeployment operation with the new resource adapter.
WebLogic Server calls new.start(extendedBootstrapContext). See Extended BootstrapContext.
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.
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.

Deploying a Resource Adapter Configured with Multiple Outbound Connection Pools

By default, when deploying a resource adapter that is configured with multiple outbound connection pools, the adapter deployment fails if a failure occurs in any connection pool. However, a deployment option is available that enables deployment to succeed, with the failed connection pools isolated from the healthy ones. This enables you to isolate, diagnose, and repair the failed connection pools and dynamically update the deployment without the need to redeploy the whole adapter.

To configure resource adapter deployment to succeed if a failure occurs with an outbound connection pool, you can do either of the following:

Using the WebLogic Server Administration Console, make sure the Deploy As A Whole flag is not checked. This option is available from the Resource Adapter > Configuration > General page. See Configure resource adapter properties in the Oracle WebLogic Server Administration Console Online Help.
Set the deploy-as-a-whole element in the weblogic-ra.xml file to false.