weblogic-ra.xml Deployment Descriptor Elements

 

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

Note: If your resource adapter .rar does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you. For more information, see Automatic Generation of the weblogic-ra.xml File in Configuration.

• Manually Editing XML Deployment Files

• Using the Console Deployment Descriptor Editor to Edit Files

• weblogic-ra.xml DTD

• weblogic-ra. xml Element Hierarchy Diagram

• weblogic-ra.xml Element Descriptions

 

---

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 connector PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 Connector//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic600-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/wls600/dtd/weblogic600-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 the Console Deployment Descriptor Editor to Edit Files

This section describes the procedure for editing the following resource adapter deployment descriptors using the Administration Console Deployment Descriptor Editor:

• ra.xml

• weblogic-ra.xml

For detailed information about the elements in the resource adapter deployment descriptors, refer to Programming the WebLogic J2EE Connector Architecture.

To edit the resource adapter deployment descriptors, follow these steps:

1. Invoke the Administration Console in your browser using the following URL:

   http://host:port/console

   where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening.

2. Click to expand the Deployments node in the left pane.

3. Click to expand the Connectors node under the Deployments node.

4. Right-click the name of the resource adapter whose deployment descriptors you want to edit and choose Edit Connector Descriptor from the drop-down menu.

   The Administration Console window appears in a new browser. The left pane contains a tree structure that lists all the elements in the two resource adapter deployment descriptors and the right pane contains a form for the descriptive elements of the ra.xml file.

5. To edit, delete, or add elements in the resource adapter deployment descriptors, click to expand the node in the left pane that corresponds to the deployment descriptor file you want to edit, as described in the following list:

   • The RA node contains the elements of the ra.xml deployment descriptor.

   • The WebLogic RA node contains the elements of the weblogic-ra.xml deployment descriptor.

6. To edit an existing element in one of the resource adapter deployment descriptors, follow these steps:

   1. Navigate the tree in the left pane, clicking on parent elements until you find the element you want to edit.

   2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

   3. Edit the text in the form in the right pane.

   4. Click Apply.

7. To add a new element to one of the resource adapter deployment descriptors, follow these steps:

   1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to create.

   2. Right-click the element and chose Configure a New Element from the drop-down menu.

   3. Enter the element information in the form that appears in the right pane.

   4. Click Create.

8. To delete an existing element from one of the resource adapter deployment descriptors, follow these steps:

   1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to delete.

   2. Right-click the element and chose Delete Element from the drop-down menu.

   3. Click Yes to confirm that you want to delete the element.

9. Once you have made all your changes to the resource adapter deployment descriptors, click the root element of the tree in the left pane. The root element is the either the name of the resource adapter *.rar archive file or the display name of the resource adapter.

10. Click Validate if you want to ensure that the entries in the resource adapter deployment descriptors are valid.

11. Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server's memory.

 

---

weblogic-ra.xml DTD

Listing A-1 weblogic-ra.xml DTD

DTD for weblogic-ra.xml

<!--

XML DTD for Weblogic Specific Resource Adapter deployment 
descriptor 1.0

-->

<!--

This DTD defines the Weblogic specific deployment information for 
defining a deployable Resource Adapter Connection Factory. It 
provides for complete specification of all configurable Connection 
Factory parameters including Connection Pool parameters, Security 
parameters for Resource Principal Mapping and the ability to define 
values for configuration parameters which exist in the ra.xml 
deployment descriptor.

-->

Copyright (c) 2001 by BEA Systems, Inc. All Rights Reserved.

<!--

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

-->

<!ELEMENT weblogic-connection-factory-dd (connection-factory-name, 
description?, jndi-name, ra-link-ref?, native-libdir?, 
pool-params?, logging-enabled?, log-filename?, 
map-config-property*, security-principal-map?)>

<!--

The connection-factory-name element defines that logical name that 
will be associated with this specific deployment of the Resource 
Adapter and its corresponding Connection Factory.

The value of connection-factory-name can be used in other deployed 
Resource Adapters via the ra-link-ref element. This will allow 
multiple deployed Connection Factories to utilize a common deployed 
Resource Adapter, as well as share configuration specifications.

This is a required element.

-->

<!ELEMENT connection-factory-name (#PCDATA)>

<!--

The description element is used to provide text describing the 
parent element. The description element should include any 
information that the deployer wants to describe about the deployed 
Connection Factory.

This is an optional element.

-->

<!ELEMENT description (#PCDATA)>

<!--

The jndi-name element defines the name that will be used to bind 
the Connection Factory Object into the Weblogic JNDI Namespace. 
Client EJBs and Servlets will use this same JNDI in their defined 
Reference Descriptor elements of the weblogic specific deployment 
descriptors.

This is a required element.

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

The ra-link-ref element 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 results in this newly deployed Connection Factory sharing 
the Resource Adapter, which had 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.

This is an optional element.

-->

<!ELEMENT ra-link-ref (#PCDATA)>

<!--

The native-libdir element 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 runtime.

This is a required element IF native libraries are present.

-->

<!ELEMENT native-libdir (#PCDATA)>

<!--

The pool-params element is the root element for providing Connection 
Pool specific parameters for this Connection Factory.

Weblogic will use these specifications in controlling the behavior 
of the maintained pool of Managed Connections.

This is an optional element. 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.

-->

<!ELEMENT pool-params (initial-capacity?, max-capacity?, 
capacity-increment?, shrinking-enabled?, shrink-period-minutes?, 
connection-cleanup-frequency?, connection-duration-time?)>

<!--

The initial-capacity element identifies the initial number of 
managed connections, which the Weblogic Server will attempt to 
obtain during deployment.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value: 1

-->

<!ELEMENT initial-capacity (#PCDATA)>

<!--

The max-capacity element identifies the maximum number of managed 
connections, which the Weblogic Server will allow. Requests for 
newly allocated managed connections beyond this limit will result 
in a ResourceAllocationException being returned to the caller.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value: 10

-->

<!ELEMENT max-capacity (#PCDATA)>

<!--

The capacity-increment element identifies the number of additional 
managed connections, which the Weblogic Server will attempt to 
obtain during resizing of the maintained connection pool.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value: 1

-->

<!ELEMENT capacity-increment (#PCDATA)>

<!--

The shrinking-enabled element indicates whether or not the 
Connection Pool should have unused Managed Connections reclaimed as 
a means to control system resources.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Value Range:    true|false

Default Value: true

-->

<!ELEMENT shrinking-enabled (#PCDATA)>

<!--

The shrink-period-minutes element identifies the amount of time the 
Connection Pool Management will wait between attempts to reclaim 
unused Managed Connections.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value: 15

-->

<!ELEMENT shrink-period-minutes (#PCDATA)>

<!--

The connection-cleanup-frequency element identifies the amount of 
time (in seconds) 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.

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value:	-1

-->

<!ELEMENT connection-cleanup-frequency (#PCDATA)>

<!--

The connection-duration-time element identifies the amount of time 
(in seconds) a Connection handle 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. 

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Default Value:	-1

-->

<!ELEMENT connection-duration-time (#PCDATA)>

<!--

The logging-enabled element 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. 

This is an optional element.

Failure to specify this value will result in Weblogic using its 
defined default value.

Value Range:    true|false

Default Value: false

-->

<!ELEMENT logging-enabled (#PCDATA)>

<!--

The log-filename element specifies the name of the log file which 
output generated from either the ManagedConnectionFactory or a 
ManagedConnection are sent.

The full address of the filename is required.

This is an optional element.

-->

<!ELEMENT log-filename (#PCDATA)>

<!--

Each map-config-property element 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.

This is an optional element.

-->

<!ELEMENT map-config-property (map-config-property-name, 
map-config-property-value)>

<!ELEMENT map-config-property-name (#PCDATA)>

<!ELEMENT map-config-property-value (#PCDATA)>

<!--

Each security-principal-map element provides a mechanism to define 
appropriate Resource Principal values for Resource Adapter/EIS 
authorization processing, based upon the known Weblogic Runtime 
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.

-->

<!ELEMENT security-principal-map (map-entry*)>

<!ELEMENT map-entry (initiating-principal+, resource-principal)>

<!ELEMENT initiating-principal (#PCDATA)>

<!ELEMENT resource-principal (resource-username, 
resource-password)>

<!ELEMENT resource-username (#PCDATA)>

<!ELEMENT resource-password (#PCDATA)>

 

---

weblogic-ra. xml Element Hierarchy Diagram

The following diagram summarizes the structure of the weblogic-ra.xml deployment descriptor.

Listing A-2 weblogic-ra.xml Element Hierarchy

 

 

---

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 (required)—the root element of the Weblogic-specific deployment descriptor for the deployed resource adapter.

• 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 (required if native libraries 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.

• 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)—identifies the amount of time the connection pool manager will wait between attempts to reclaim unused managed connections.

  Failure to specify this value will result in WebLogic Server using its defined default value.

  Default Value: 15

• connection-cleanup-frequency (optional)—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

• connection-duration-time (optional)—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

• 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.

• 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 (optional)—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.

• map-entry—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.