bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search

Programming WebLogic Server J2EE Connectors

 Previous Next Contents Index View as PDF  

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

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:

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:

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:

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 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:

For more information on these tools, see "Deployment Tools Reference" in Deploying WebLogic Server Applications.

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.

You can modify deployment descriptors using the following tools:

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.

 

Back to Top Previous Next