BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | J2EE Connector Architecture | Previous Topic | Next Topic | Contents | View as PDF

Resource Adapter Deployment

The following sections explain how to deploy, undeploy, and update the deployment of configured resource adapters to WebLogic Server:

- Resource Adapter Deployment Overview

- Using the Administration Console

- Using the Applications Directory

- Using weblogic.deploy

- Including a Resource Adapter in an Enterprise Application (.ear file)

Resource Adapter Deployment Overview

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:

- Dynamically using command line or through the Administration Console

- Automatically while WebLogic Server is running by copying the archive file or exploded directory into the applications directory of a WebLogic Server domain

- As part of an Enterprise Application, which is deployed in an archive file called an .ear

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, Proposed Final Draft 2. 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 .rar file 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 file 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, because you may later re-use that name to deploy the resource adapter.

Using the Administration Console

This section discusses resource adapter deployment tasks using the Administration Console.

Deploying Resource Adapters Using the Administration Console

To deploy a resource adapter using the WebLogic Server Administration Console:

1. Start WebLogic Server.

2. Open the Administration Console.

3. Open the Domain you will be working in.

4. Under Deployments, select Connectors in the left panel. The Connector Deployments table displays in the right pane showing all the deployed Connectors (Resource Adapters).

5. Select Configure a new Connector Component...

6. Enter the following information:

   - Name—modify the default name of the connector component as needed.

   - URI Path—enter the full path of the resource adapter .rar file or a directory containing the resource adapter exploded directory format. For example: c:\myaps\components\myResourceAdapter.rar

   - Deployed—indicate whether the Resource Adapter .rar file should be deployed when created.

7. Select the Create button.

8. Note that the new resource adapter now appears in the Deployments table in the right pane.

Viewing Deployed Resource Adapters Using the Administration Console

To view a deployed resource adapter in the Administration Console:

1. In the Administration Console under Deployments, select Connectors (Resource Adapters) in the left panel.

2. View a list of deployed Connectors in the Connector Deployments table in the right pane.

Undeploying Deployed Resource Adapters Using the Administration Console

To undeploy a deployed resource adapter from the WebLogic Server Administration Console:

1. In the Administration Console under Deployments, select Connectors (Resource Adapters) in the left panel.

2. In the Connector Deployments table, select the connector to undeploy.

3. Under the Configuration tab, de-select the Deployed checkbox.

4. Click Apply.

Undeploying a resource adapter does not remove the resource adapter name from WebLogic Server. The resource adapter remains undeployed for the duration of the Server session, as long as you do not change it once it has been undeployed. You cannot re-use the deployment name with the deploy argument until you reboot the server. You can re-use the deployment name to update the deployment, as described in the following section.

Updating Deployed Resource Adapters Using the Administration Console

When you update the contents of the resource adapter .rar file or deployment directory that has been deployed to WebLogic Server, those updates are not reflected in WebLogic Server until:

- You reboot the server (if the .rar or directory is to be automatically deployed)

  or

- You update the resource adapter deployment using the WebLogic Server Administration Console

From the WebLogic Server Administration Console:

1. In the Administration Console under Deployments, select Connectors (Resource Adapters) in the left panel.

2. In the Connector Deployments table, select the connector to update.

3. Update the Connector Name and Deployed status as needed.

4. Click Apply.

Using the Applications Directory

You can deploy a resource adapter automatically while WebLogic Server is running. The /applications directory is monitored during runtime of the WebLogic Server and detects if a new .rar is added (causing deployment) or if an existing .rar is removed (causing undeployment).

To deploy a resource adapter using the applications directory:

1. Copy the .rar archive or the exploded directory containing a resource adapter to the applications directory of a domain.

   For example, after copying a resource adapter called myResourceAdapter in exploded format, your WebLogic Server installation looks like this (not all the files for a resource adapter are shown here):

   Listing 4-1 myResourceAdapter

   >     \---beaHome

   >     	\---wlserver6.x

   >     		\---config

   >     			\---mydomain

   >     				\---applications

   >     					\---myResourceAdapter

   >     						eis.jar

   >     						readme.html

   >     						unix.so

   >     						utilities.jar

   >     						windows.dll

   >     						\---META-INF

   >     							ra.xml

   >     							weblogic-ra.xml

   After copying a .rar file, your WebLogic Server installation looks like this:

   Listing 4-2 rar File

   >     	\---beaHome

   >     		\---wlserver6.x

   >     			\---config

   >     				\---mydomain

   >     					\---applications

   >     						myResourceAdapter.rar

2. Start WebLogic Server. When you boot WebLogic Server, it automatically attempts to deploy the specified resource adapter .rar file or deployment directory.

3. Launch the Administration Console.

4. In the right pane, click Resource Adapter Deployments.

5. Verify that the resource adapter is listed and that the Deployed box is selected.

Using weblogic.deploy

To deploy a resource adapter .rar file or deployment directory that has not been deployed to WebLogic Server, use the following command:

>     	% java weblogic.deploy -port port_number -host host_name

>     	deploy password name source

where:

- name is the string containing the name you want to assign to this resource adapter deployment unit.

- password is the password for the WebLogic Server system account.

- source is the full path and filename of the resource adapter .rar file you want to deploy, or the full path of the resource adapter deployment directory.

Viewing Deployed Resource Adapters Using weblogic.deploy

To view resource adapters that are deployed on a local WebLogic Server, from the command line enter the following:

>     	% java weblogic.deploy list password

where password is the password for the WebLogic Server System account.

To list deployed resource adapters on a remote server, from the command line enter the following:

>     	% java weblogic.deploy -port port_number -host host_name

>     	list password

Undeploying Deployed Resource Adapters Using weblogic.deploy

Undeploying a resource adapter does not remove the deployment name associated with the resource adapter .rar file or deployment directory. The deployment name remains in the server to allow for later updates of the resource adapter.

To undeploy a deployed resource adapter from the command line, you need only reference the assigned deployment unit name, as in:

>     	%java weblogic.deploy -port 7001 -host localhost undeploy

>     	password myResourceAdapter

>     Undeploying a resource adapter does not remove the resource adapter name from
>     WebLogic Server. The resource adapter will remain undeployed for the duration of the
>     Server session, as long as you do not change it once it has been undeployed. You
>     cannot re-use the deployment name with the deploy argument until you reboot the
>     server. You can re-use the deployment name to update the deployment, as described in
>     Updating Deployed Resource Adapters Using weblogic.deploy.

Updating Deployed Resource Adapters Using weblogic.deploy

When you update the contents of the resource adapter .rar file or deployment directory that has been deployed to WebLogic Server, those updates are not reflected in WebLogic Server until:

- You reboot the server (if the .rar or directory is to be automatically deployed) or

- You update the resource adapter deployment using the WebLogic Server Administration Console

To update or redeploy the resource adapter from the command line, use the update argument and specify the active resource adapter deployment name:

>     	%java weblogic.deploy -port 7001 -host localhost update

>     	password myResourceAdapter

Including a Resource Adapter in an Enterprise Application (.ear file)

As part of the J2EE Platform Specification, Version 1.3, Proposed Final Draft 3, it is now possible to include a resource adapter archive (.rar) file 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 file inside the .ear archive just as you would a .war or .jar archive.

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

   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 archive. 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 4-3 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 4-4 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."

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.