Programming WebLogic Resource Adapters

Creating and Configuring Resource Adapters

The following sections describe how to create and configure a WebLogic Server resource adapter:

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. You will specify these classes in the ra.xml file. For example:

<managedconnectionfactory-class>com.sun.connector.blackbox.LocalTxManagedConnectionFactory</managedconnectionfactory-class>
<connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
<connectionfactory-impl-class>com.sun.connector.blackbox.JdbcDataSource</connectionfactory-impl-class>
<connection-interface>java.sql.Connection</connection-interface>
<connection-impl-class>com.sun.connector.blackbox.JdbcConnection</connection-impl-class>

For more information, see Programming Tasks.

Compile the Java code for the interfaces and implementation into class files, using a standard compiler.

Create the resource adapter's deployment descriptors. A WebLogic resource adapter uses two deployment descriptor files:

ra.xml describes the resource adapter-related attributes type and its deployment properties using the standard XML schema specified by the J2CA 1.5 Specification.
weblogic-ra.xml adds additional WebLogic Server-specific deployment information, including connection and connection pool properties, security identities, Work Manager properties, and logging.

For detailed information about creating WebLogic Server-specific deployment descriptors for resource adapters, refer to Configuring the weblogic-ra.xml File and weblogic-ra.xml Schema.

Package the Java classes into a Java archive (JAR) file with a .rar extension.

Create a staging directory anywhere on your hard drive. Place the JAR file in the staging directory and the deployment descriptors in a subdirectory called META-INF.
Then create the resource adapter archive by executing a jar command similar to the following in the staging directory: jar cvf myRAR.rar *

Deploy the resource adapter archive file (RAR) on WebLogic Server in a test environment and test it.

During testing, you may need to edit the resource adapter deployment descriptors. You can do this using the WebLogic Server Administration Console or manually using an XML editor or a text editor. For more information about editing deployment descriptors, see Configuring the weblogic-ra.xml File and Configure resource adapter properties in the Administration console online help. See also weblogic-ra.xml Schema for detailed information on the elements in the deployment descriptor.

Deploy the RAR resource adapter archive file on WebLogic Server or include it in an enterprise archive (EAR) file to be deployed as part of an enterprise application.

For information about these steps, see Packaging and Deploying Resource Adapters. See also Deploying WebLogic Server Applications for detailed information about deploying components and applications in general.

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 a temporary directory anywhere on your hard drive to stage the resource adapter:

	mkdir c:/stagedir

Extract the contents of the resource adapter archive:

	cd c:/stagedir

	jar xf blackbox-notx.rar

The staging directory should now contain the following:

A JAR file containing Java classes that implement the resource adapter
A META-INF directory containing the Manifest.mf and ra.xml files

Execute these commands to see these files:

	c:/stagedir> ls

		blackbox-notx.rar

		META-INF

	c:/stagedir> ls META-INF

		Manifest.mf

		ra.xml

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.

For more information, see Configuring the weblogic-ra.xml File and also refer to weblogic-ra.xml Schema, for information on the XML schema that applies to weblogic-ra.xml.

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:

cp weblogic-ra.xml c:/stagedir/META-INF

c:/stagedir> ls META-INF

   Manifest.mf

   ra.xml

   weblogic-ra.xml

Create the resource adapter archive:

	jar cvf blackbox-notx.rar -C c:/stagedir

Deploy the resource adapter to WebLogic Server. For more information about packaging and deploying the resource adapter, see Packaging and Deploying Resource Adapters and Deploying Applications to WebLogic Server.

Configuring the ra.xml File

If your resource adapter does not already contain an 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 an ra.xml file, refer to the J2CA 1.5 Specification.

Configuring the weblogic-ra.xml File

In addition to supporting features of the standard resource adapter configuration ra.xml file, BEA 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 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.
Whether WebLogic Server attempts to reclaim unused ManagedConnections to save system resources.
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 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.

Table 3-1 Schema Headers for ra.xml and weblogic-ra.xml

XML File	Schema Header
`ra.xml`	<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5">
`weblogic-ra.xml`	<?xml version = "1.0"> <weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">

XML File

Schema Header

ra.xml

<?xml version="1.0" encoding="UTF-8"?>

<connector xmlns="http://java.sun.com/xml/ns/j2ee"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee

http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"

version="1.5">

weblogic-ra.xml

<?xml version = "1.0">

<weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">

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. It is located at: http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd
weblogic-ra.xsd contains the schema used for creating weblogic-ra.xml, which defines resource adapter properties used for deployment to WebLogic Server. This schema is located at http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd.

Note: 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 console help.

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.

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 J2EE libraries feature. However, the Link-Ref mechanism is still supported in this release for 1.0 resource adapters. For more information on J2EE libraries, see Creating Shared J2EE Libraries and Optional Packages in Developing Applications with 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.

For further instructions on editing the weblogic-ra.xml file, see weblogic-ra.xml Schema.