Programming WebLogic Resource Adapters
The following sections in this appendix describe the deployment descriptor elements that can be defined in the WebLogic Server-specific deployment descriptor weblogic-ra.xml. The schema for weblogic-ra.xml
is http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd. If your resource adapter archive (RAR) does not contain a weblogic-ra.xml deployment descriptor, WebLogic Server automatically selects the default values of the deployment descriptor elements.
The weblogic-connector
element is the root element of the WebLogic-specific deployment descriptor for the deployed resource adapter. You can define the following elements within the weblogic-connector
element.
Specifies the directory where all the native libraries exist that are required by the resource adapter. |
||
Specifies the JNDI name for the resource adapter. The resource adapter bean is registered into the JNDI tree with this name. It is not a required element if no resource adapter bean is specified. It is not a functional element if a JNDI name is specified for a resource adapter without a resource adapter bean. |
||
As stated by the J2CA 1.5 Specification, if the resource adapter is packaged within an application (in other words, within an EAR), only components within the application should have access to the resource adapter. This element allows you to override this functionality. Note: This element does not apply for stand-alone resource adapters. When set to false, the resource adapter can only be accessed by clients that reside within the same application in which the resource adapter resides. Note: For version 1.0 resource adapters (supported in this release), the default value for this element is set to true. |
||
When set to |
||
This complex element is used to specify all the configurable elements for creating the Work Manager that will be used by the resource adapter bean. The work-manager element is imported from the weblogic-j2ee.xsd schema. The Work Manager dynamically adjusts the number of work threads to avoid deadlocks and achieve optimal throughput subject to concurrency constraints. It also meets objectives for response time goals, shares, and priorities. For subelements of work-manager, see work-manager. |
||
This complex element is used to specify all the security parameters for the operation of the resource adapter. See security for information on the security defaults that will be taken by the connector container. |
||
This complex element is used to override any properties that have been specified for the resource adapter bean in the ra.xml file. For subelements of properties, see properties. |
||
This complex element defines all of the admin objects in a resource adapter. As with the outbound-resource-adapter complex element, the admin-objects complex element has three hierarchical property levels that specify the configuration scope: 1. Global level—at this level, you specify parameters that apply to all admin objects in the resource adapter; you do so using the default-properties element. See default-properties. 2. Group level—at this level, you specify parameters that apply to all admin objects belonging to a particular admin object group specified in the ra.xml deployment descriptor; you do so using the admin-object-group element. The properties specified in the group override any parameters that are specified at the global level. See admin-object-group. 3. Instance level—Under each admin object group, you can use the admin-object-instance element to specify admin object instances. These correspond to the admin object instances for the resource adapter. You can specify properties at the instance level and override those properties provided in the group and global levels. See admin-object-instance. For admin-objects subelements, see admin-objects. |
||
This complex element is used to describe the outbound components of a resource adapter. As with the admin-objects complex element, this element has three hierarchical property levels that specify the configuration scope for defining outbound connection pools: 1. Global level—at this level, you specify parameters that apply to all outbound connection pools in the resource adapter using the default-connection-properties element. See default-connection-properties. 2. Group level—at this level, you specify parameters that apply to all outbound connections belonging to a particular connection factory specified in the ra.xml deployment descriptor using the connection-definition-group element. A one-to-one correspondence exists from a connection factory in ra.xml to a connection definition group in weblogic-ra.xml. The properties specified in a group override any parameters specified at the global level. See connection-definition-group. 3. The instance level—Under each connection definition group, you can specify connection instances. These correspond to the individual connection pools for the resource adapter. Parameters can be specified at this level too and these override those provided at the group and global levels. See connection-instance. For outbound-resource-adapter subelements, see outbound-resource-adapter. |
The work-manager element is a complex element that is used to specify all the configurable elements for creating the Work Manager that will be used by the resource adapter bean. The work-manager element is imported from the weblogic-j2ee.xsd schema. The following subelements can be configured in the work-manager element.
The security complex element contains default security information that can be configured for the connector container. For more information, see Configuring Security Identities for Resource Adapters.
Specifies the default secure ID to be used for calls into the resource adapter. If this value is not specified, the default is the anonymous identity, which is the same as no security identity. See default-principal-name for subelements of this element. |
||
Specifies the secure ID to be used for running various resource adapter management tasks, including startup, shutdown, testing, shrinking, and transaction management. If not specified, it defaults to the default-principal-name value. If default-principal-name is not specified, it defaults to the anonymous identity. See manage-as-principal-name for subelements of this element. |
||
Specifies the secure ID to be used by all calls from the connector container into the resource adapter code during connection requests. (This element currently applies only to outbound functions.) If not specified, it defaults to the default-principal-name value. If default-principal-name is not specified, it uses the identity of the requesting caller. See run-as-principal-name for subelements of this element. |
||
Specifies the secure ID to be used to run all work instances started by the resource adapter. If not specified, it defaults to the default-principal-name value. If default-principal-name is not specified, it uses the identity that was used to start the work. See run-work-as-principal-name for subelements of this element. |
The default-principal-name element contains the following subelements.
Specifies that the principal name should be used. This should match a defined WebLogic Server user name. |
The manage-as-principal-name element contains the following subelements.
Specifies that the principal name should be used. This should match a defined WebLogic Server user name. |
The run-as-principal-name element contains the following subelements.
Specifies that the principal name should be used. This should match a defined WebLogic Server user name. |
||
The run-work-as-principal-name element contains the following subelements.
Specifies that the principal name should be used. This should match a defined WebLogic Server user name. |
||
The properties
element, a subelement of weblogic-connector
, is a container for properties specified for the resource adapter bean in ra.xml. It holds one more or more property elements.
You define property elements within the properties
element as follows.
The admin-objects complex element defines all of the admin objects in the resource adapter. As with the outbound-resource-adapter complex element, the admin-objects complex element has three hierarchical property levels that you can specify.
The admin-objects
element is a sub-element of the weblogic-connector
element. You can define the following elements within the admin-objects
element.
Specifies the default properties that apply to all admin objects (at the global level) in the resource adapter. The default-properties element can contain one or more property elements, each holding a name and value pair. See properties. |
||
Specifies the default parameters that apply to all admin objects belonging to a particular admin object group specified in the ra.xml deployment descriptor. The properties specified in the group override any parameters that are specified at the global level. For admin-object-group subelements, see admin-object-group. |
The admin-object-group element is used to define an admin object group. At the group level, you specify parameters that apply to all admin objects belonging to a particular admin object group specified in the ra.xml deployment descriptor. The properties specified in the group override any parameters that are specified at the global level.
The admin-object-interface element (a subelement of the admin-object-group element) serves as a required unique element (a key) to each admin-object-group. There must be a one-to-one relationship between the weblogic-ra.xml admin-object-interface element and the ra.xml adminobject-interface element
The admin-object-group
element is a sub-element of the weblogic-connector
element. You can define the following elements within the admin-object-group
element.
The admin-object-interface element serves as a required unique element (a key) to each admin-object-group. There must be a one-to-one relationship between the weblogic-ra.xml admin-object-interface element and the ra.xml adminobject-interface element. |
||
Specifies all the default properties that apply to all admin objects in this admin object group. The default-properties element can contain one or more property elements, each holding a name and value pair. See properties. |
||
Specifies one or more admin object instances within the admin object group, corresponding to the admin object instances for the resource adapter. You can specify properties at the instance level and override those provided in the group and global levels. For subelements, see admin-object-instance. The default-properties element can contain one or more property elements, each holding a name and value pair. See properties. |
You can define the following subelements under admin-object-instance.
The admin object group that defines the reference name for the admin object instance. You can specify the reference name to be the JNDI name or resource link of the connection instance. If the JNDI name is specified (by specifying the jndi-name element), the connection pool is bound into a JNDI that clients outside the application can see. Note: In order for this to work, the enable-access-outside-app element must be set to true. For resource adapters that do not need to be externally visible to other applications, you would specify the resource-link value. |
||
Defines all the properties that apply to the admin object instance. The admin-object-properties element can contain one or more property elements, each holding a name and value pair. See properties. |
The outbound-resource-adapter
element is a sub-element of the weblogic-connector
element. You can define the following elements within the outbound-resource-adapter
element.
This complex element is used to specify the properties at an global level. At this level, the user is able to specify parameters that apply to all outbound connection pools in the resource adapter. For subelements, see default-connection-properties. |
||
This element is used to specify all the connection defintion groups. There must be a one-to-one correspondence relationship between the connection factories in the ra.xml deployment descriptor and the groups in the weblogic-ra.xml deployment descriptor. A group does not have to exist in the weblogic-ra.xml deployment descriptor for every connection factory in ra.xml. However, if a group exists, there must be at least one connection instance in the group. The properties specified in the group override any parameters that are specified at the global level using default-connection-properties. For subelements, see connection-definition-group. |
The default-connection-properties
element is a sub-element of the outbound-resource-adapter
element. You can define the following elements within the default-connection-properties
element.
Serves as the root element for providing connection pool-specific parameters for this connection factory. WebLogic Server uses these specifications to control the behavior of the maintained pool of ManagedConnections. This is an optional element. Failure to specify this element or any of its specific element items results in default values being assigned. Refer to the description of each individual element for the designated default value. For subelements, see pool-params. |
||
Contains parameters for configuring logging of the ManagedConnectionFactory and ManagedConnection objects of the resource adapter. For subelements, see logging. |
||
Specifies the level of transaction support for a particular Connection Factory. It provides the ability to override the transaction-support value specified in the The value of transaction-support must be one of the following: For related information, see Connection Management. |
||
The Note that |
||
A Boolean that specifies whether a particular connection factory supports re-authentication of an existing ManagedConnection instance. It provides the ability to override the |
||
The properties element includes one or more property elements, which define name and value subelements that apply to the default connections. |
||
Specifies whether to use container- or application-managed security. The values for this element can be one of Application or |
The pool-params
element is a sub-element of the default-connection-properties
element. You can define the following elements within the pool-params
element.
The logging
element is a sub-element of the default-connection-properties
element. You can define the following elements within the logging
element.
The connection-definition-group element is used to define a connection definition group. At the group level, you specify parameters that apply to all outbound connections belonging to a particular connection factory specified in the ra.xml deployment descriptor using the connection-definition-group element. A one-to-one correspondence exists from a connection factory in ra.xml to a connection definition group in weblogic-ra.xml. The properties specified in a group override any parameters specified at the global level.
The connection-factory-interface element (a subelement of the connection-definition-group element) serves as a required unique element (a key) to each connection-definition-group. There must be a one-to-one relationship between the weblogic-ra.xml connection-definition-interface element and the ra.xml connectiondefinition-interface element.
The connection-definition-group
element is a sub-element of the outbound-resource-adapter
element. You can define the following elements within the connection-definition-group
element.
Every connection definition group has a key (a required unique element). This key is the connection-factory-interface. The value specified for connection-factory-interface must be equal to the value specified for connection-factory-interface in ra.xml. |
||
This complex element is used to define properties for outbound connections at the group level. |
||
Under each connection definition group, the user can specify connection instances. These correspond to the individual connection pools for the resource adapter. Parameters can be specified at this level too and these override those provided in the group and global levels. This element specifies a description of the connection pool. (A connection instance is equivalent to a connection pool.) It is used to document the connection pool. See connection-instance. |
You can define the following subelements under connection-instance.
The connection definition group that defines the reference name for the connection instance. The reference name can be a JNDI name or a resource link. |
||
Defines all the properties that apply to the connection instance. The connection-properties element can contain one or more property elements, each holding a |