|
|
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.
For production and development purposes, BEA recommends packaging your assembled resource adapter (RAR) as part of an enterprise application (EAR).
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:
/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
The following are packaging requirements for resource adapters:
ra.xml and weblogic-ra.xml) must be in a directory called META-INF. 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.class-path entry in MANIFEST.MF to reference a class or resource such as a property.eis.jar and utilities.jar.) Ensure that any dependencies of a resource adapter on platform-specific native libraries are resolved.windows.dll and unix.so.)readme.html and /images/ra.jpg.)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.
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:
META-INF subdirectory in the staging directory.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 |
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. |
jar cvfjar-file.rar -Cstaging-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.
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.
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.
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.
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.
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.
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.
Suspendable interface (see Listing 4-3).Suspendable.supportsVersioning() method must return true when invoked by WebLogic Server.weblogic-ra.xml descriptor must be set to false.
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:
new.init(old, null) to inform the new resource adapter that it is replacing the old resource adapter.old.startVersioning(new, null) to inform the old resource adapter to start its production redeployment operation with the new resource adapter.new.start(extendedBootstrapContext). See Extended BootstrapContext.(ExtendedBootstrapContext)bsCtx.complete(). This informs WebLogic Server that it is safe to undeploy the old resource adapter.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.
|
