Skip Headers
Oracle® Fusion Middleware Programming Resource Adapters for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24971-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Creating and Configuring Resource Adapters

This chapter describes how to create and configure a WebLogic Server resource adapter and also how to prepare the resource adapter for deployment.

This chapter includes the following sections:

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:

  1. Write the Java code for the various classes required by resource adapter (ConnectionFactory, Connection, and so on) in accordance with JSR 322: Java EE Connector Architecture 1.6. These classes will be specified 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 1.6 adapters, you can embed metadata annotations in the resource adapter class files to specify deployment information, eliminating the need to create the ra.xml file manually. For more information, see Configuring the ra.xml File.

    Note:

    The WebLogic Server implementation of Connector Architecture 1.6 includes support for Contexts and Dependency Injection. This support has implications on the set of annotations that may be used in resource adapter component beans, which are beans that define special components managed by the Connector container and that have a special life cycle. For more information, see

    For more information about programming resource adapters, see Chapter 4, "Programming Tasks."

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

  3. 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 Java EE Connector Architecture specification.

      Note:

      Java EE Connector Architecture 1.6 no longer requires the ra.xml file to be created manually. Instead, deployment information can be specified in metadata annotations. See Configuring the ra.xml File.

    • 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 Appendix A, "weblogic-ra.xml Schema."

  4. 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 * 
    

    Optionally, you can include the Bean Validation configuration file, META-INF/validation.xml, inside the JAR file. WebLogic Server uses the Bean Validation configuration file to validate the resource adapter module.

  5. Deploy the resource adapter archive (RAR) file 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 Oracle WebLogic Server Administration Console Online Help. See also Appendix A, "weblogic-ra.xml Schema," for detailed information on the elements in the deployment descriptor.

  6. 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 Chapter 10, "Packaging and Deploying Resource Adapters." See also Deploying Applications to Oracle WebLogic Server 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.

  1. Create a temporary directory anywhere on your hard drive to stage the resource adapter:

    mkdir c:/stagedir
    
  2. 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
    
  3. 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 Appendix A, "weblogic-ra.xml Schema," for information on the XML schema that applies to weblogic-ra.xml.

  4. 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
    
  5. Create the resource adapter archive:

    jar cvf blackbox-notx.rar -C c:/stagedir
    
  6. Deploy the resource adapter to WebLogic Server. For more information about packaging and deploying the resource adapter, see Chapter 10, "Packaging and Deploying Resource Adapters," and Deploying Applications to Oracle WebLogic Server.

Configuring the ra.xml File

All resource adapters must be specified in an ra.xml deployment descriptor file. For 1.0 or 1.5 resource adapters, you must create this file manually. If you are creating a 1.6 resource adapter, you can optionally specify metadata annotations in the resource adapter classes, eliminating the need to create the ra.xml file manually. The following sections explain how to configure the ra.xml file:

For more information about creating a ra.xml file, you can also refer to JSR 322: Java EE Connector Architecture 1.6.

Creating the ra.xml File Manually

If your resource adapter does not already contain a ra.xml file, and you are creating a 1.0 or 1.5 resource adapter, 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.

Using Metadata Annotations to Specify Deployment Information

The Java EE Connector Architecture 1.6 no longer requires you to manually create a ra.xml file. Instead, metadata annotations can be included in resource adapter classes to provide the same functions that are specified in the ra.xml file.

If you choose to specify all deployment information in a ra.xml file, the Java EE Connector Architecture 1.6 includes the metadata-complete element, which you include in the ra.xml file and set to true. Setting the metadata-complete element to true causes all metadata annotations included in the resource adapter classes to be ignored. If the metadata-complete element is not specified, or is set to false, WebLogic Server merges the information specified in the annotations with the information specified in the ra.xml file at run time, and uses this merged information to deploy and manage the resource adapter.

For more information about deployment descriptors and annotations, see Chapter 18, "Metadata Annotations," of JSR 322: Java EE Connector Architecture 1.6. See also "Metadata Annotations" in The Java EE 6 Tutorial.

Resource Adapter XML Schema Definitions

The Java EE Connector Architecture 1.6 introduces changes to the ra.xml file schema, primarily to support ease-of-development features such as metadata annotations. For details about schema definition changes, see Section 20.7, "Resource Adapter XML Schema Definition," in JSR 322: Java EE Connector Architecture 1.6.

The schema for the ra-xml file for 1.0 and 1.5 resource adapters is http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd. For 1.6 adapters, the schema is http://java.sun.com/xml/ns/javaee/connector_1_6.xsd

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.

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.

Table 3-1 Schema Header

XML File Schema Header
ra.xml
<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/connector_1_6.xsd"
version="1.6">
weblogic-ra.xml
<?xml version = "1.3">
<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">

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:

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 run time 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 WebLogic Server Administration Console Online Help.

Dynamic Reconfigurable Configuration Properties

Dynamic reconfigurable configuration properties are described in Section 5.3.7.6 of JSR 322: Java EE Connector Architecture 1.6. For 1.6 resource adapters, WebLogic Server supports dynamic reconfigurable configuration properties for the following adapter component beans:

  • ResourceAdapter beans

  • ManagedConnectionFactory beans

  • Administered object beans

At run time, after you update the dynamically configurable properties on any of these adapter component beans, you must update the adapter to put changes into effect. Updating the adapter is a relatively lightweight operation during which WebLogic Server modifies the run-time bean instances without interfering with active connection pools or admin objects that do not have configuration updates. You do not need to update the adapter immediately. However, changes to properties on adapter component beans do not go into effect unless the beans are dynamically updated or the resource adapter is restarted.

The resource adapter should be designed carefully with regard to support for dynamic changes to its properties during run time. Depending on the services provided by the resource adapter, it might be critically important that some properties should never be reconfigured when the adapter is running; for example, the listen address and port number of a resource adapter used for the EIS connection (any reconfiguration of those properties should require the adapter to be shut down and restarted). WebLogic Server does not impose any requirements on an adapter component bean with regard to whether specific properties may or may not be designated as dynamically reconfigurable. It is entirely for the adapter developer to decide which adapter component beans support dynamic update and which do not.

Dynamic Configuration Parameters

For 1.6 adapters, WebLogic Server supports dynamic update on properties of Resource Adapter, ManagedConnectionFactory, and admin object beans. Using the Administration Console, you can modify the following configuration parameters on those beans 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 JSR 322: Java EE Connector Architecture 1.6.

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 Java EE Libraries and Optional Packages" in 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.

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

Bean Validation Configuration File

In its support of JSR 303: Bean Validation, WebLogic Server extends Java EE 6 by providing a module-level bean validation configuration file. WebLogic Server supports the optional use this file to validate a resource adapter module.

The bean validation configuration file can be specified for a resource adapter module regardless of whether the resource adapter is deployed independently (as a standalone RAR) or as part of an enterprise application (EAR). If no bean validation configuration file is specified for an adapter module, WebLogic Server uses a default bean validation configuration to validate the resource adapter module.

The bean validation configuration file is named validation.xml and is included among the deployment descriptors in the META-INF subdirectory of the RAR.

For more information about bean validation, see Bean Validation.

Long-Running Work Support

Section 11.7 of JSR 322: Java EE Connector Architecture 1.6 defines two standard hints to control the quality-of-service (QoS) characteristics afforded to it by the WorkManager:

For more information, see Configuring and Managing Long-Running Work.

Tooling Support

WebLogic Server supports the following tools, which can be used to help with resource adapter development and deployment: