Creating and Configuring Resource Adapters: Main Steps

This section describes how to create a new WebLogic resource adapter. The next section, Modifying an Existing Resource Adapter, describes how to take an existing resource adapter and prepare it for deployment on WebLogic Server.

To create a new WebLogic resource adapter, you must create the classes for the particular resource adapter (ConnectionFactory, Connection, and so on), write the resource adapter's deployment descriptors, and then package everything into an archive file to be deployed to WebLogic Server.

The following are the main steps for creating a resource adapter:

Write the Java code for the various classes required by resource adapter (ConnectionFactory, Connection, and so on) in accordance with the J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/). You will specify these classes in the ra.xml file. For example:

Modifying an Existing Resource Adapter

In some cases, you may already have a resource adapter available for deployment to WebLogic Server. This section describes how to take an existing resource adapter that is packaged in a RAR file and modify it for deployment to WebLogic Server. This involves adding the weblogic-ra.xml deployment descriptor and repackaging the resource adapter. The following procedure supposes you have an existing resource adapter packaged in a RAR file named blackbox-notx.rar.

Create the weblogic-ra.xml file. This file is the WebLogic-specific deployment descriptor for resource adapters. In this file, you specify parameters for connection factories, connection pools, and security settings.

Copy the weblogic-ra.xml file into the temporary directory's META-INF subdirectory. The META-INF directory is located in the temporary directory where you extracted the RAR file or in the directory containing a resource adapter in exploded directory format. Use the following command:

Configuring the ra.xml File

If your resource adapter does not already contain a ra.xml file, you must manually create or edit an existing one to set the necessary deployment properties for the resource adapter. You can use a text editor or XML editor to edit the properties. For information on creating a ra.xml file, refer to the J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/).

Configuring the weblogic-ra.xml File

In addition to supporting features of the standard resource adapter configuration ra.xml file, WebLogic Server defines an additional deployment descriptor file, the weblogic-ra.xml file. This file contains parameters that are specific to configuring and deploying resource adapters in WebLogic Server. This functionality is consistent with the equivalent weblogic-*.xml extensions for EJBs and Web applications in WebLogic Server, which also add WebLogic-specific deployment descriptors to the deployable archive. The basic RAR or deployment directory can be deployed to WebLogic Server without a weblogic-ra.xml file. If a resource adapter is deployed in WebLogic Server without a weblogic-ra.xml file, a template weblogic-ra.xml file populated with default element values is automatically added to the resource adapter archive. However, this automatically generated weblogic-ra.xml file is not persisted to the RAR; the RAR remains unchanged.

The following summarizes the most significant features you can configure in the weblogic-ra.xml deployment descriptor file.

Descriptive text about the connection factory.

JNDI name bound to a connection factory. (Resource adapters developed based on the J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/) are bound in the JNDI as objects independently of their ConnectionFactory objects.)

Reference to a separately deployed connection factory that contains resource adapter components that can be shared with the current resource adapter.

Connection pool parameters that set the following behavior:

Initial number of ManagedConnections that WebLogic Server attempts to allocate at deployment time.

Maximum number of ManagedConnections that WebLogic Server allows to be allocated at any one time.

Number of ManagedConnections that WebLogic Server attempts to allocate when filling a request for a new connection.

The time WebLogic Server waits between attempts to reclaim unused ManagedConnections.

Logging properties to configure WebLogic Server logging for the ManagedConnectionFactory or ManagedConnection.

Transaction support levels (XA, local, or no transaction support).

Principal names to use as security identities.

For detailed information about configuring the weblogic-ra.xml deployment descriptor file, see the reference information in Appendix A, "weblogic-ra.xml Schema." See also the configuration information in the following sections:

Editing Resource Adapter Deployment Descriptors

To define or make changes to the XML descriptors used in the WebLogic Server resource adapter archive, you must define or edit the XML elements in the weblogic-ra.xml and ra.xml deployment descriptor files. You can edit the deployment descriptor files with any plain text editor. However, to avoid introducing errors, use a tool designed for XML editing.You can also edit most elements of the files using the WebLogic Administration Console.

Editing Considerations

To edit XML elements manually:

If you use an ASCII text editor, make sure that it does not reformat the XML or insert additional characters that could invalidate the file.

Use the correct case for file and directory names, even if your operating system ignores the case.

To use the default value for an optional element, you can either omit the entire element definition or specify a blank value. For example: <max-config-property></max-config-property>

Schema Header Information

When editing or creating XML deployment files, it is critical to include the correct schema header for each deployment file. The header refers to the location and version of the schema for the deployment descriptor.

Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the schema, so your host server need not have access to the Internet. However, you must still include this <?xml version...> element in your ra.xml file, and have it reference the external URL because the version of the schema contained in this element is used to identify the version of this deployment descriptor.

Table 3-1 shows the entire schema headers for the ra.xml and weblogic-ra.xml files.

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc):

SAXException: This document may not have the identifier 'identifier_name'

Conforming Deployment Descriptor Files to Schema

The contents and arrangement of elements in your deployment descriptor files must conform to the schema for each file you use. The following links provide the public schema locations for deployment descriptor files used with WebLogic Server:

connector_1_5.xsd contains the schema for the standard ra.xml deployment file, required for all resource adapters. This schema is maintained as part of the J2CA 1.5 Specification and is located at http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd.

Your browser might not display the contents of files having the .xsd extension. In that case, to view the schema contents in your browser, save the links as text files and view them with a text editor.

Dynamic Descriptor Updates: Console Configuration Tabs

You can use the Administration Console to view, modify, and (when necessary) persist deployment descriptor elements. Some descriptor element changes take place dynamically at runtime without requiring the resource adapter to be redeployed. Other descriptor elements require redeployment after changes are made. To use the Administration Console to configure a resource adapter, open Deployments and click the name of the deployed resource adapter. Use the Configuration tab to change the configuration of the resource adapter and the other tabs to control, test, or monitor the resource adapter. For information about using the Administration Console, see "Configure resource adapter properties" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.

Dynamic Configuration Parameters

Using the Administration Console, you can modify the following configuration parameters dynamically, without requiring the resource adapter to be redeployed:

Edit the adapter JNDI name

Create and delete outbound connection pools

Edit the connection pool JNDI name

Create and delete admin objects

Edit admin object JNDI names.

Dynamic Pool Parameters

Using the Administration Console, you can modify the following weblogic-ra.xml pool parameters dynamically, without requiring the resource adapter to be redeployed:

initial-capacity

max-capacity

capacity-increment

shrink-frequency-seconds

highest-num-waiters

highest-num-unavailable

connection-creation-retry-frequency-seconds

connection-reserve-timeout-seconds

test-frequency-seconds

Dynamic Logging Parameters

Using the Administration Console, you can modify the following weblogic-ra.xml logging parameters dynamically, without requiring the resource adapter to be redeployed:

log-filename

file-count

file-size-limit

log-file-rotation-dir

rotation-time

file-time-span

Automatic Generation of the weblogic-ra.xml File

A resource adapter archive (RAR) deployed on WebLogic Server must include a weblogic-ra.xml deployment descriptor file in addition to the ra.xml deployment descriptor file specified in the J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/).

If a resource adapter is deployed in WebLogic Server without a weblogic-ra.xml file, a template weblogic-ra.xml file populated with default element values is automatically added to the resource adapter archive. However, this automatically generated weblogic-ra.xml file is not persisted to the RAR; the RAR remains unchanged. WebLogic Server instead generates internal data structures that correspond to default information in the weblogic-ra.xml file.

For a 1.0 resource adapter that is a single connection factory definition, the JNDI name will be eis/ModuleName. For example, if the RAR is named MySpecialRA.rar, the JNDI name of the connection factory will be eis/MySpecialRA.

For a 1.5 resource adapter with a ResourceAdapter bean class specified, the JNDI name of the bean would be MySpecialRA. Each connection factory would also have a corresponding instance created with a JNDI name of eis/ModuleName, eis/ModuleName_1, eis/ModuleName_2, and so on.

(Deprecated) Configuring the Link-Ref Mechanism

The Link-Ref mechanism was introduced in the 8.1 release of WebLogic Server to enable the deployment of a single base adapter whose code could be shared by multiple logical adapters with various configuration properties. For 1.5 resource adapters in the current release, the Link-Ref mechanism is deprecated and is replaced by the new Java EE libraries feature. However, the Link-Ref mechanism is still supported in this release for 1.0 resource adapters. For more information on Java EE libraries, see "Creating Shared J2EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server. To use the Link-Ref mechanism, use the <ra-link-ref> element in your resource adapter's weblogic-ra.xml file.

The deprecated and optional <ra-link-ref> element allows you to associate multiple deployed resource adapters with a single deployed resource adapter. In other words, it allows you to link (reuse) resources already configured in a base resource adapter to another resource adapter, modifying only a subset of attributes. The <ra-link-ref> element enables you to avoid - where possible - duplicating resources (such as classes, JARs, image files, and so on). Any values defined in the base resource adapter deployment are inherited by the linked resource adapter, unless otherwise specified in the <ra-link-ref> element.

If you use the optional <ra-link-ref> element, you must provide either all or none of the values in the <pool-params> element. The <pool-params> element values are not partially inherited by the linked resource adapter from the base resource adapter.

Do one of the following:

Assign the <max-capacity> element the value of 0 (zero). This allows the linked resource adapter to inherit its <pool-params> element values from the base resource adapter.

Assign the <max-capacity> element any value other than 0 (zero). The linked resource adapter will inherit no values from the base resource adapter. If you choose this option, you must specify all of the <pool-params> element values for the linked resource adapter.