Programming WebLogic Resource Adapters
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 (
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.
For more information, see Programming Tasks.
ra.xmldescribes the resource adapter-related attributes type and its deployment properties using the standard XML schema specified by the J2CA 1.5 Specification.
weblogic-ra.xmladds additional WebLogic Server-specific deployment information, including connection and connection pool properties, security identities, Work Manager properties, and logging.
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.
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.
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.
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.
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.
ManagedConnectionsthat WebLogic Server attempts to allocate at deployment time.
ManagedConnectionsthat WebLogic Server allows to be allocated at any one time.
ManagedConnectionsthat WebLogic Server attempts to allocate when filling a request for a new connection.
ManagedConnectionsto save system resources.
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:
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.
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.
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.xsdcontains the schema for the standard
ra.xmldeployment 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.xsdcontains 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.
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.
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
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
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
_2, and so on.
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.
For further instructions on editing the weblogic-ra.xml file, see weblogic-ra.xml Schema.