2 Creating and Configuring Resource Adapters
To create and configure a WebLogic Server resource adapter and prepare it for deployment, you perform several tasks that include creating the resource adapter classes and configuring the deployment descriptors, and may also include specifying metadata annotations, preparing the bean validation configuration file, setting up health status monitoring of standalone and embedded resource adapters, and more.
Creating and Configuring Resource Adapters: Main Steps
To create a new WebLogic resource adapter, you must create the classes for the particular resource adapter, 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:
Modifying an Existing Resource Adapter
weblogic-ra.xml
deployment descriptor and repackaging the resource adapter.
The follow example shows the steps for modifying an existing resource adapter packaged in a RAR file named blackbox-notx.rar
.
Configuring the ra.xml File
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 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 Java Platform, Enterprise Edition: The Java EE 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 and 1.7 adapters, the schema is at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/index.html
.
Configuring the weblogic-ra.xml File
ra.xml
file, WebLogic Server defines an additional deployment descriptor file, weblogic-ra.xml
. 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 JSR 322: Java EE Connector Architecture 1.6 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
orManagedConnection
. -
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 Server 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 xmlns.jcp.org
, 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 2-1 shows the entire schema headers for the ra.xml
and weblogic-ra.xml
files.
Table 2-1 Schema Header
XML File | Schema Header |
---|---|
ra.xml |
|
weblogic-ra.xml |
|
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_7.xsd
contains the schema for the standardra.xml
deployment file, required for all resource adapters. This schema is maintained as part of JSR 322: Java EE Connector Architecture 1.7 and is located at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/index.html#8. -
weblogic-ra.xsd
contains the schema used for creatingweblogic-ra.xml
, which defines resource adapter properties used for deployment to WebLogic Server. This schema is located athttp://xmlns.oracle.com/weblogic/weblogic-connector/1.5/weblogic-connector.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 WebLogic Server 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 WebLogic Server 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 WebLogic Server 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 WebLogic Server 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 WebLogic Server 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 WebLogic Server 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 of0
(zero). This allows the linked resource adapter to inherit itspool-params
element values from the base resource adapter. -
Assign the
max-capacity
element any value other than0
(zero). The linked resource adapter will inherit no values from the base resource adapter. If you choose this option, you must specify all of thepool-params
element values for the linked resource adapter.
For further instructions on editing the weblogic-ra.xml
file, see weblogic-ra.xml Schema.
Bean Validation Configuration File
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
WorkManager
. These hints are:
-
Work
Name Hint — Names aWork
instance and is used as part of the thread name assigned to a long-running Work instance. -
Long-running
Work
instance Hint — Performs the same function as the WebLogic Server extension annotation @LongRunning, which allows you to schedule aWork
instance in a separate thread and that also facilitates the control and monitoring capabilities of long-running Work instances.WebLogic Server allows you to configure a limit on the number of long-running
Work
instances that can be submitted by a resource adapter to be executed concurrently. The default limit is 10. You can change the limit to higher value, but you need to exercise care not to overburden system resources.This limit can be specified either by using the
max-concurrent-long-running-requests
element in theweblogic-ra.xml
file or by settingConnectorWorkManagerRuntimeMBean.ActiveLongRunningRequests
attribute, which is exposed in the WebLogic Server Administration Console. TheConnectorWorkManagerRuntimeMBean
includes getter and setter methods on theActiveLongRunningRequests
andCompletedLongRunningRequests
attributes that allow you to configure and monitor information about long-runningWork
instances.
For more information, see Configuring and Managing Long-Running Work.
Tooling Support
WebLogic Server supports two tools, weblogic.appmerge
and appc
, which you can use to help with resource adapter development and deployment.
-
weblogic.appmerge
Performs validation checks metadata annotations. When used with the
-writeInferredDescriptors
option,weblogic.appmerge
generates a mergedra.xml
that combines deployment information specified in annotations with the contents of any pre-existingra.xml
file.Note:
After you run the
weblogic.appmerge
tool, make sure themetadata-complete
element in the mergedra.xml
is set totrue
. This prevents the deployer from processing annotations again, which improves overall deployment performance and reduces deployment time.See Using weblogic.appmerge to Merge Libraries in Developing Applications for Oracle WebLogic Server.
-
appc
Performs extensive validation checks on annotations, bean classes,
ra.xml
,weblogic-ra.xml
, and the resource adapter deployment plan (weblogic.appmerge
validates annotations only).The
appc
tool also:-
Provides extensive reports that include both warnings and errors.
-
Is particularly useful for validating a resource adapter and ensuring that its configuration is correct without having to deploy it.
See appc Reference in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
-
Monitoring Resource Adapter Health
false
, the adapter deployment can succeed even if one or more outbound connection pool failures occur. You can use the health monitoring feature to detect connection pool failures and repair them without needing to redeploy the adapter.
The following sections explain how resource adapter health status monitoring is available in WebLogic Server:
Obtaining Resource Adapter Health State
To support health monitoring in both standalone and embedded resource adapters, WebLogic Server provides the following MBean attributes, whose values can be obtained using the WebLogic Server Administration Console, WLST, or JMX:
-
ConnectorComponentRuntimeMBean.HealthState
— Returns the overall health state of either a standalone or embedded resource adapter. If an outbound connection pool has a deployment failure, the health state of the resource adapter is HEALTH_CRITICAL. -
ApplicationRuntimeMBean.OverallHealthState
— Returns the aggregated health state of the application, including that of the embedded components that report health. If an embedded resource adapter contains a failed outbound connection pool, the health state of that connection pool is reflected in the overall health of the application. -
ConnectorConnectionPoolRuntimeMBean.HealthState
— Returns health state of the individual outbound connection pool in a resource adapter.
Deployment Requirements for Monitoring Health
To deploy a resource adapter that is configured with multiple outbound connection pools so that a failed connection pool does not cause the whole adapter deployment to fail, you must set the deploy-as-a-whole
element in the weblogic-ra.xml
file to false
. (By default, this element is set to true
.) For information about setting this deployment option, see Deploying a Resource Adapter Configured with Multiple Outbound Connection Pools.