Packaging and Deploying Resource Adapters

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

• Packaging Resource Adapters

• Deploying Resource Adapters

 

---

Packaging Resource Adapters

The file format for a packaged resource adapter module defines the contract between a resource adapter provider and deployer. A packaged resource adapter includes the following elements:

• Java classes and interfaces that are required for the implementation of both the Connector Architecture contracts and the functionality of the resource adapter

• Utility Java classes for the resource adapter

• Platform-dependent native libraries required by the resource adapter

• Help files and documentation

• Descriptive meta information that ties the above elements together

This section discusses resource adapter packaging guidelines, requirements and limitations, and provides instructions for packaging resource adapters.

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 7-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 Resource Adapters 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 J2EE Applications, which describes how WebLogic Server loads classes.

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/dtd/connector_1_0.dtd

6. 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.

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 Modifying 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 resource adapter:

• Using the command line weblogic.Deployer tool. (This method replaces the earlier weblogic.deploy utility, which has been deprecated.).

• Using the graphical user interface of the WebLogic Server Administration Console.

• As part of an Enterprise Application (EAR) file.

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.

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.

Using the weblogic.Deployer Utility

The weblogic.Deployer utility is new in WebLogic Server 7.0 and replaces the earlier weblogic.deploy utility, which has been deprecated. This section describes how to use the weblogic.Deployer utility to perform the following tasks:

• Deploy a Connector or its components

• Redeploy parts of a Connector or its components

• Deactivate or unprepare a Connector or its components

• Remove a Connector

• Cancel a pending deployment task

• List all deployment tasks

For information and instructions on deploying a Connector using the weblogic.Deployer utility, see "WebLogic Deployment" in Developing WebLogic Server J2EE Applications.

Using the Administration Console

This section discusses resource adapter deployment tasks using the Administration Console. Using the Administration Console, you can perform the following deployment tasks:

• Configure Resource Adapters (Connectors) for Deployment

• Deploy Resource Adapters (Connectors)

• View Deployed Resource Adapters (Connectors)

• Undeploy Resource Adapters (Connectors)

• Update Deployed Resource Adapters (Connectors)

For information and instructions on deploying a Connector using the WebLogic Server Administration Console, see "WebLogic Deployment" in Developing WebLogic Server J2EE Applications.

Including a Resource Adapter in an Enterprise Application Archive (EAR)

As part of the J2EE Platform Specification, Version 1.3 Final Release, it is possible to include a resource adapter archive (RAR) inside an enterprise application archive (EAR) and then deploy the application in WebLogic Server.

To deploy an enterprise application that contains a resource adapter archive:

1. Place the RAR inside the EAR just as you would a Web Application Archive (WAR) or JAR.

2. Create a valid application.xml and place it in the META-INF directory of the EAR.

   Note the following when creating an application.xml:

   The application deployment descriptor must contain the new <connector> element to identify the resource adapter archive within the EAR. For example:

	<connector>RevisedBlackBoxNoTx.rar</connector>

Because the <connector> element is a new addition to the J2EE Platform Specification, Version 1.3, the application.xml file must contain the following DOCTYPE entry to identify it as a J2EE Platform Specification, Version 1.3 deployment descriptor.

Listing 7-2 DOCTYPE Entry

<!DOCTYPE application PUBLIC `-//Sun Microsystems, Inc.//DTD

J2EE Application 1.3//EN'

	`http://java.sun.com/dtd/application_1_3.dtd'>

If you do not use this DOCTYPE entry, the resource adapter will not be deployed.

The following listing is an example of an application.xml file.

Listing 7-3 application.xml File

<application>

	<display-name> ConnectorSampleearApp </display-name>

	<module>

		<connector>RevisedBlackBoxNoTx.rar</connector>

	</module>

	<module>

		<ejb>ejb_basic_beanManaged.jar</ejb>

	</module>

</application>

3. Deploy the Enterprise Application in WebLogic Server.

   For general information about deployment of Enterprise Applications, see "Enterprise Applications" in "Understanding WebLogic Server Applications."