Programming WebLogic Server J2EE Connectors

weblogic-ra.xml Deployment Descriptor Elements

The following sections provide a complete reference for the WebLogic Server-specific XML deployment descriptor properties used in the WebLogic Server resource adapter archive and an explanation of how to edit the XML deployment descriptor. Use these sections if you need to refer to the deployment descriptor used for resource adapters.

If your resource adapter archive (RAR) does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you.

Manually Editing XML Deployment Files

To define or make changes to the XML deployment descriptors used in the WebLogic Server resource adapter archive, you must manually define or edit the XML elements in the weblogic-ra.xml file.

Basic Conventions

To manually edit XML elements:

Make sure that you use an ASCII text editor that 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>

DOCTYPE Header Information

When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.

The header refers to the location and version of the Document Type Definition (DTD) file for the deployment descriptor. Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the Internet. However, you must still include this <!DOCTYPE...> element in your ra.xml file, and have it reference the external URL because the version of the DTD contained in this element is used to identify the version of this deployment descriptor.

The entire DOCTYPE headers for the ra.xml and weblogic-ra.xml files are as follows:

XML File	DOCTYPE header
`ra.xml`	`<!DOCTYPE connector PUBLIC`'`-//Sun Microsystems, Inc.//DTD Connector 1.0//EN`' 'http://java.sun.com/dtd/connector_1_0.dtd'`>`
`weblogic-ra.xml`	`<!DOCTYPE weblogic-connection-factory-dd PUBLIC` "`-//BEA Systems, Inc.//DTD WebLogic 8.1.0 Connector//EN`" "http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd">

XML File

DOCTYPE header

ra.xml

<!DOCTYPE connector PUBLIC'-//Sun Microsystems, Inc.//DTD Connector 1.0//EN'
'http://java.sun.com/dtd/connector_1_0.dtd'>

weblogic-ra.xml

<!DOCTYPE weblogic-connection-factory-dd PUBLIC

"-//BEA Systems, Inc.//DTD WebLogic 8.1.0 Connector//EN" "http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd">

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'

identifier_name generally includes the invalid text from the PUBLIC element.

Document Type Definitions (DTDs) for Validation

The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server utilities ignore the DTDs embedded within the DOCTYPE header of XML deployment files, and instead use the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.

The following links provide the public DTD locations for XML deployment files used with WebLogic Server:

connector_1_0.dtd contains the DTD for the standard ra.xml deployment file, required for all resource adapters. This DTD is maintained as part of the J2EE Connector Specification, Version 1.0; refer to this specification for information about the elements used in the connector_1_0.dtd (http://java.sun.com/j2ee/download.html#connectorspec).
weblogic-ra.dtd contains the DTD used for creating weblogic-ra.xml, which defines resource adapter properties used for deployment to WebLogic Server. This file is located at http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd

Note: Most browsers do not display the contents of files having the .dtd extension. To view the DTD file contents in your browser, save the links as text files and view them with a text editor.

Using WebLogic Builder to Edit Deployment Descriptors

WebLogic Builder provides a visual environment for editing an application's deployment descriptor XML files. You can view these XML files as you visually edit them in WebLogic Builder, but you won't need to make textual edits to the XML files.

Use WebLogic Builder for the following development tasks:

Generate deployment descriptor files for a J2EE module
Edit a module's deployment descriptor files
View deployment descriptor files
Compile and validate deployment descriptor files
Deploy a module to a server

For instructions on using WebLogic Builder, refer to the WebLogic Builder documentation.

Dynamic Descriptor Updates

This release of WebLogic Server has deprecated the Administration Console Deployment Descriptor Editor. A new Descriptor tab in the Administration Console has replaced it. Using the Descriptor tab, you can view, modify, and persist deployment descriptor elements to the descriptor file within the resource adapter in the same manner that they were persisted using the Deployment Descriptor Editor.

However, these descriptor elements takes place dynamically at runtime without requiring the resource adapter to be redeployed. The descriptor elelements contained in the Descriptor tab are limited to only those descriptor elements that may be dynamically changed at runtime. These include the following weblogic-ra.xml elements:

initial-capacity
max-capacity
capacity-increment
shrinking-enabled
shrink-frequency-seconds
highest-num-unavailable
highest-num-waiters
inactive-connection-timeout-seconds
connection-reserve-timeout-seconds
test-frequency-seconds
connection-creation-retry-frequency-seconds

weblogic-ra.xml Element Descriptions

The following sections describe each of the elements that can be defined in the weblogic-ra.xml file.

weblogic-connection-factory-dd

The weblogic-connection-factory-dd element is the root element of the WebLogic-specific deployment descriptor for the deployed resource adapter.

The following table describes the elements you can define within a weblogic-connection-factory-dd element.

Element	Required Optional	Description
`<connection-factory-name>`	Required	Defines the logical name that will be associated with this specific deployment of the resource adapter and its corresponding connection factory. The value of this element can be used in other deployed resource adapters through the ra-link-ref element, allowing multiple deployed Connection Factories to utilize a common deployed resource adapter, as well as share configuration specifications.
`<description>`	Optional	Provides text describing the parent element. This element should include any information that the deployer wants to describe about the deployed Connection Factory.
<jndi-name>	Required	Defines the name that will be used to bind the Connection Factory Object into the WebLogic JNDI Namespace. Client EJBs and Servlets use the same JNDI in their defined Reference Descriptor elements of the WebLogic-specific deployment descriptors.
<ra-link-ref>	Optional	Allows for the logical association of multiple deployed connection factories with a single deployed resource adapter. The specification of the optional ra-link-ref element with a value identifying a separately deployed connection factory will result in this newly deployed connection factory sharing the resource adapter that has been deployed with the referenced connection factory. In addition, any values defined in the referred connection factories deployment will be inherited by this newly deployed connection factory unless specified.
<native-libdir>	Optional Required if native libraries are present.	Identifies the directory location to be used for all native libraries present in this resource adapter deployment. As part of deployment processing, all encountered native libraries will be copied to the location specified. It is the responsibility of the administrator to perform the necessary platform actions such that these libraries will be found during WebLogic Server run time.
<pool-params>	Optional	The root element for providing connection pool-specific parameters for this connection factory. WebLogic Server uses these specifications in controlling the behavior of the maintained pool of managed connections. Failure to specify this element or any of its specific element items will result in default values being assigned. Refer to the description of each individual element for the designated default value. For more information on the elements of <pool-params>, refer to pool-params
<logging-enabled>	Optional	Indicates whether or not the log writer is set for either the ManagedConnectionFactory or ManagedConnection. If this element is set to true, output generated from either the ManagedConnectionFactory or ManagedConnection will be sent to the file specified by the log-filename element. Failure to specify this value will result in WebLogic Server using its defined default value. Value Range: true \| false Default Value: false
<log-filename>	Optional	Specifies the name of the log file from which output generated from the ManagedConnectionFactory or a ManagedConnection is sent. The full address of the filename is required.
<map-config-property>	Optional, Zero or More	Identifies a configuration property name and value that corresponds to an ra.xml config-entry element with the corresponding config-property-name. At deployment time, all values present in a map-config-property specification will be set on the ManagedConnectionFactory. Values specified via a map-config-property will supersede any default value that may have been specified in the corresponding ra.xml config-entry element. For more information on the elements of <map-config-property>, refer to map-config-property.
<security-principal-map>	Optional	This is a deprecated element. Provides a mechanism to define appropriate resource-principal values for resource adapter and EIS authorization processing, based upon the known WebLogic run time initiating-principal. This map allows for the specification of a defined set of initiating principals and the corresponding resource principal's username and password that should be used when allocating managed connections and connection handles. A default resource-principal can be defined for the connection factory via the map. By specifying an initiating-principal value of `*' and a corresponding resource-principal, the defined resource-principal will be utilized whenever the current identity is not matched elsewhere in the map. This is an optional element, however, it must be specified in some form if container managed sign-on is supported by the resource adapter and used by any client. In addition, the deployment-time population of the connection pool with managed connections will be attempted using the defined `default' resource principal if one is specified. For more information on the elements of <security-principal-map>, refer to security-principal-map.

pool-params

The following table describes the elements you can define within a pool-params element.

Element	Required Optional	Description
`<initial-capacity>`	Optional	Identifies the initial number of managed connections, which WebLogic Server attempts to obtain during deployment. Failure to specify this value will result in WebLogic Server using its defined default value. Default Value: 1
`<max-capacity>`	Optional	Identifies the maximum number of managed connections, which WebLogic Server will allow. Requests for newly allocated managed connections beyond this limit results in a ResourceAllocationException being returned to the caller. Failure to specify this value will result in WebLogic Server using its defined default value. Default Value: 10
<capacity-increment>	Optional	Identifies the maximum number of additional managed connections that WebLogic Server attempts to obtain during resizing of the maintained connection pool. Failure to specify this value will result in WebLogic Server using its defined default value. Default Value: 1
<shrinking-enabled>	Optional	Indicates whether or not the connection pool should have unused managed connections reclaimed as a means to control system resources. Failure to specify this value will result in WebLogic Server using its defined default value. Value Range: true \| false Default Value: true
<shrink-period-minutes>	Optional	This is a deprecated element. It has been replaced by the shrink-frequency-seconds element. Identifies the amount of time the connection pool manager will wait between attempts to reclaim unused managed connections. Default Value: 15
<connection-cleanup-frequency>	Optional	This is a deprecated element. Identifies the amount of time the connection pool management will wait between attempts to destroy connection handles which have exceeded their usage duration. This element, used in conjunction with connection-duration-time, prevents connection leaks when an application may have not closed a connection after completing usage. Failure to specify this value will result in Weblogic using its defined default value. Default Value: -1 Note: The connection-cleanup-frequency element is a deprecated element. If you currently have this parameter in your configuration, you will still be able use deployment functions. However, this element will have no effect on the configuration.
<connection-duration-time>	Optional	This is a deprecated element. Identifies the amount of time a connection can be active. This element, used in conjunction with connection-cleanup-frequency, prevents leaks when an application may have not closed a connection after completing usage. Failure to specify this value will result in Weblogic using its defined default value. Default Value: -1 Note: The connection-duration-time element is a deprecated element. If you currently have this parameter in your configuration, you will still be able use deployment functions. However, this element will have no effect on the configuration.
<connection-maxidle-time>	Optional	This is a deprecated element. It has been replaced by the inactive-connection-timeout-seconds element. Identifies the amount of time (in seconds) a connection handle can remain idle. This element prevents leaks when an application may have not closed a connection after completing usage. Idle connections will only be terminated in the case where the connection pool becomes full, and a new connection request is about to fail because of this. Default Value: 0
<connection-profiling-enabled>	Optional	Indicates whether or not the connection pool should store the call stacks of where each connection is allocated. If enabled this information can be viewed on active connections through the Console. Also, the stacks for Leaked and Idle connections will be available if this is enabled and can help debug components that fail to close connections. Failure to specify this value will result in Weblogic using its defined default value. Value Range: true \| false Default Value: false
<shrink-frequency-seconds>	Optional	Indentifies the amount of time (in seconds) Connection Pool Management will wait between attempts to reclaim unused Managed Connections. Failure to specify this value will result in Weblogic using its defined default value. Default Value: 900 seconds
<inactive-connection-timeout-seconds>	Optional	Identifies the amount of time (in seconds) a Connection handle can remain inactive. This element prevents leaks when an Application may have not closed a connection after completing usage. Inactive connections will be terminated as soon as they are detected. Failure to specify this value will result in Weblogic using its defined default value. Default Value: 0
<highest-num-waiters>	Optional	The maximum number of waiters that can concurrently block waiting to reserve a connection from the pool. Default Value: 0
<highest-num-unavailable>	Optional	The maximum number of physical connections (Managed Connections) in the pool that can be made unavailable (to the application) for purposes such as refreshing a connection. Note that in cases such as the backend system being unavailable, the specified value might be exceeded due to factors outside of the control of the pool. Default Value: 0
<connection-creation-retry-frequency-seconds>	Optional	The periodicity of retry attempts by the pool to establish connections. Default Value: 0
<connection-reserve-timeout-seconds>	Optional	The number of seconds after which the call to reserve a connection from the pool will timeout. Default Value: -1 (do not block when reserving resources)
<test-frequency-settings>	Optional	The periodicity at which connections in the pool are tested. Default Value: 0
<match-connections-supported>	Optional	Indicates whether or not the resource adapter supports the ManagedConnectionFactory.matchManagedConnections() method. If the resource adapter does not support this method (always returns null for this method), then WebLogic Server bypasses this method call during a connection request. Value Range: true\|false Default Value: true

map-config-property

The following table describes the elements you can define within a map-config-property element.

Element	Required Optional	Description
`<map-config-property-name>`	Optional	Identifies a name that corresponds to an ra.xml config-entry element with the corresponding config-property-name.
`<map-config-property-value>`	Optional	Identifies a value that corresponds to an ra.xml config-entry element with the corresponding config-property-name.

security-principal-map

The following table describes the elements you can define within a security-principal-map element.

Element	Required Optional	Description
`<map-entry>`	Optional	Identifies an entry in the security-principal-map. initiating-principal (optional, zero or more) resource-principal (optional)—can be defined for the connection factory via the security-principal-map. By specifying an initiating-principal value of `*' and a corresponding resource-principal, the defined resource-principal will be utilized whenever the current identity is not matched elsewhere in the map. resource-username (optional)—username identified with the resource-principal. Used when allocating managed connections and connection handles. resource-password (optional)—password identified with the resource-principal. Used when allocating managed connections and connection handles.

Element

Required
Optional

Description

<map-entry>

Optional

Identifies an entry in the security-principal-map.

initiating-principal (optional, zero or more)
resource-principal (optional)—can be defined for the connection factory via the security-principal-map. By specifying an initiating-principal value of `*' and a corresponding resource-principal, the defined resource-principal will be utilized whenever the current identity is not matched elsewhere in the map.

resource-username (optional)—username identified with the resource-principal. Used when allocating managed connections and connection handles.
resource-password (optional)—password identified with the resource-principal. Used when allocating managed connections and connection handles.