Programming WebLogic Resource Adapters

      

weblogic-ra.xml Schema

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.

 


weblogic-connector

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.

Table 9-1 weblogic-connector subelements
Element Required/
Optional
Description
native-libdir Required if native libraries are present. Directory where all the native libraries exist that are required by the resource adapter.
jndi-name Required only if a resource adapter bean is specified. 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.
enable-access-outside-app Optional 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.

This element does not apply for stand-alone resource adapters.

Default Value: false 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.

For version 1.0 resource adapters (supported in this release), the default value for this element is set to true. enable-global-access-to-
classes Optional When set to true (default), the resource adapter allows global access to its classes. work-manager Optional 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. security Optional 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. properties Optional 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. admin-objects Optional 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. outbound-resource-adapter Optional 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.

 


work-manager

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.

Table 9-2 work-manager subelements
Element Required
Optional
Description
name Required Name of the Work Manager. The J2CA 1.5 Specification describes how a resource adapter can submit work threads to the application server. These work threads are managed by the WebLogic Server Work Manager. 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.
response-time-request-class
fair-share-request-class
context-request-class
request-class-name
Optional A work-manager element can include one and only one of the following four elements: response-time-request-class—Defines the response time request class for the application. Response time is defined with attribute goal-ms in milliseconds. The increment is ((goal - T) Cr)/R, where T is the average thread use time, R the arrival rate, and Cr a coefficient to prioritize response time goals over fair shares. fair-share-request-class—Defines the fair share request class. Fair share is defined with attribute percentage of default share. Therefore, the default is 100. The increment is Cf/(P R T), where P is the percentage, R the arrival rate, T the average thread use time, and Cf a coefficient for fair shares to prioritize them lower than response time goals. context-request-class—Defines the context class. Context is defined with multiple cases mapping contextual information, like current user or its role, cookie, or work area fields to named service classes. request-class-name—Defines the request class name.
min-threads-constraint min-threads-constraint-name Optional You can choose between the following two elements: min-threads-constraint—Used to guarantee a number of threads the server allocates to requests of the constrained work set to avoid deadlocks. The default is zero. A min-threads value of one is useful, for example, for a replication update request, which is called synchronously from a peer. min-threads-constraint-name—Defines a name for the min-threads-constraint element.
max-threads-constraint max-threads-constraint-name Optional You can choose between the following two elements: max-threads-constraint—Limits the number of concurrent threads executing requests from the constrained work set. The default is unlimited. For example, consider a constraint defined with maximum threads of 10 and shared by 3 entry points. The scheduling logic ensures that not more than 10 threads are executing requests from the three entry points combined. max-threads-constraint-name—Defines a name for the max-threads-constraint element.
capacity capacity-name Optional You can choose between the following two elements: capacity—Constraints can be defined and applied to sets of entry points, called constrained work sets. The server starts rejecting requests only when the capacity is reached. The default is zero. Note that the capacity includes all requests, queued or executing, from the constrained work set. This constraint is primarily intended for subsystems like JMS, which do their own flow control. This constraint is independent of the global queue threshold. capacity-name—Defines a name for the capacity element.

 


security

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.

Table 9-3 security subelements
Element Required
Optional
Description
default-principal-name Optional 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.
manage-as-principal-name Optional 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.
run-as-principal-name Optional 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.
run-work-as-principal-name Optional 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.

 

default-principal-name

The default-principal-name element contains the following subelements.

Table 9-4 default-principal-name subelements
Element Required
Optional
Description
use-anonymous-identity Required The anonymous identity should be used.
principal-name Required The principal name should be used. This should match a defined WebLogic Server user name.

 

manage-as-principal-name

The manage-as-principal-name element contains the following subelements.

Table 9-5 manage-as-principal-name subelements
Element Required
Optional
Description
use-anonymous-identity Required The anonymous identity should be used.
principal-name Required The principal name should be used. This should match a defined WebLogic Server user name.

 

run-as-principal-name

The run-as-principal-name element contains the following subelements.

Table 9-6 run-as-principal-name subelements
Element Required
Optional
Description
use-anonymous-identity Required The anonymous identity should be used.
principal-name Required The principal name should be used. This should match a defined WebLogic Server user name.
use-caller-identity Required The caller's identity should be used.

 

run-work-as-principal-name

The run-work-as-principal-name element contains the following subelements.

Table 9-7 run-work-as-principal-name subelements
Element Required
Optional
Description
use-anonymous-identity Required The anonymous identity should be used.
principal-name Required The principal name should be used. This should match a defined WebLogic Server user name.
use-caller-identity Required The caller's identity should be used.

 


properties

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.

Table 9-8 properties subelements
Element Required
Optional
Description
property Required The property element is used to override a property that has been specified for the resource adapter bean in the ra.xml file. It holds two subelements: name—Specifies the same name as the config-property-name element (a subelement of config-property in the ra.xml deployment descriptor). Setting this parameter causes the associated config-property-value element in ra.xml to be overridden. This is a required element. value—Specifies the value that overrides config-property-value element (a subelement of config-property in the ra.xml deployment descriptor). This is an optional element.

 


admin-objects

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.

Table 9-9 admin-objects subelements
Element Required
Optional
Description
default-properties Optional 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.
admin-object-group One or more 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.

 

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.

Table 9-10 admin-object-group
Element Required
Optional
Description
admin-object-interface Required 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.
default-properties Optional 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.
admin-object-instance One or more 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.

admin-object-instance

You can define the following subelements under admin-object-instance.

Table 9-11 admin-object-instance subelements
Element Required
Optional
Description
jndi-name / resource-link Required 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.

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. admin-object-properties Optional 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.

 


outbound-resource-adapter

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.

Table 9-12 outbound-resource-adapter subelements
Element Required
Optional
Description
default-connection-properties Optional 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.
connection-definition-group One or more This element is used to specify all the connection definition 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.

 

default-connection-properties

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.

Table 9-13 default-connection-properties subelements
Element Required
Optional
Description
pool-params Optional 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.
logging Optional Contains parameters for configuring logging of the ManagedConnectionFactory and ManagedConnection objects of the resource adapter. For subelements, see logging.
transaction-support Optional Level of transaction support for a particular Connection Factory. It provides the ability to override the transaction-support value specified in the ra.xml deployment descriptor that is intended to be the default value for all Connection Factories of the resource adapter. The value of transaction-support must be one of the following: NoTransaction LocalTransaction XATransaction For related information, see Connection Management.
authentication-mechanism Optional The authentication-mechanism element specifies an authentication mechanism supported by a particular Connection Factory in the resource adapter. It provides the ability to override the authentication-mechanism value specified in the ra.xml deployment descriptor that is intended to be the default value for all Connection Factories of the resource adapter. Note that BasicPassword mechanism type should support the javax.resource.spi.security.PasswordCredential interface.
reauthentication-support Optional A Boolean that specifies whether a particular connection factory supports re-authentication of an existing ManagedConnection instance. It provides the ability to override the reauthentication-support value specified in the ra.xml deployment descriptor that is intended to be the default value for all Connection Factories of the resource adapter.
properties Optional The properties element includes one or more property elements, which define name and value subelements that apply to the default connections.
res-auth Optional Whether to use container- or application-managed security. The values for this element can be one of Application or Container. The default value is Container.

pool-params

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.

Table 9-14 pool-params subelements
Element Required
Optional
Description
initial-capacity Optional Specifies the initial number of ManagedConnections, which WebLogic Server attempts to create during deployment. Default Value: 1
max-capacity Optional Specifies the maximum number of ManagedConnections, which WebLogic Server will allow. Requests for newly allocated ManagedConnections beyond this limit results in a ResourceAllocationException being returned to the caller. Default Value: 10
capacity-increment Optional Specifies the maximum number of additional ManagedConnections that WebLogic Server attempts to create during resizing of the maintained connection pool. Default Value: 1
shrinking-enabled Optional Whether unused ManagedConnections will be destroyed and removed from the connection pool as a means to control system resources. Default Value: true
shrink-frequency-seconds Optional Specifies the amount of time (in seconds) the Connection Pool Management waits between attempts to destroy unused ManagedConnections. Default Value: 900 seconds
highest-num-waiters Optional Specifies the maximum number of threads that can concurrently block waiting to reserve a connection from the pool. Default Value: 0
highest-num-unavailable Optional Specifies the maximum number of ManagedConnections in the pool that can be made unavailable to the application for purposes such as refreshing the connection. Note that in cases like the backend system being unavailable, this specified value could be exceeded due to factors outside the pool's control. Default Value: 0
connection-creation-retry-frequency-seconds Optional The periodicity of retry attempts by the pool to create connections. Default Value: 0
connection-reserve-timeout-seconds Optional Sets 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-seconds Optional The frequency with which connections in the pool are tested. Default Value: 0
test-connections-on-create Optional Enables the testing of newly created connections. Default Value: false
test-connections-on-release Optional Enables testing of connections when they are being released back into the pool. Default Value: false
test-connections-on-reserve Optional Enables testing of connections when they are being reserved. Default Value: false
profile-harvest-frequency-seconds Optional Specifies how frequently the profile for the connection pool is being harvested.
ignore-in-use-connections-enabled Optional When the connection pool is being shut down, this element is used to specify whether it is acceptable to ignore connections that are in use at that time.
match-connections-supported Optional Indicates whether 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. Default Value: true

logging

The logging element is a sub-element of the default-connection-properties element. You can define the following elements within the logging element.

Table 9-15 logging subelements
Element Required
Optional
Description
log-filename Optional 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.
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. Default Value: false
rotation-type Optional Sets the file rotation type. Possible values are bySize, byName, none bySize—When the log file reaches the size that you specify in file-size-limit, the server renames the file as FileName.n. byName—At each time interval that you specify in file-time-span, the server renames the file as FileName.n. After the server renames a file, subsequent messages accumulate in a new file with the name that you specified in log-filename. none—Messages accumulate in a single file. You must erase the contents of the file if the log size becomes unwieldy. Default Value: bySize
number-of-files-limited Optional Whether to limit the number of files that this server instance creates to store old log messages. (Requires that you specify a rotation-type of bySize). After the server reaches this limit, it overwrites the oldest file. If you do not enable this option, the server creates new files indefinitely and clean up these files as you require. If you enable number-of-files-limited by setting it to true, the server refers to your rotationType variable to determine how to rotate the log file. Rotate means that you override your existing file instead of creating a new file. If you specify false for number-of-files-limited, the server creates numerous log files rather than overriding the same one. Default Value: false
file-count Optional The maximum number of log files that the server creates when it rotates the log. This number does not include the file that the server uses to store current messages. (Requires that you enable number-of-files-limited.) Default Value: 7
file-size-limit Optional The size that triggers the server to move log messages to a separate file. (Requires that you specify a rotation-type of bySize.) After the log file reaches the specified minimum size, the next time the server checks the file size, it will rename the current log file as FileName.n and create a new one to store subsequent messages. Default Value: 500
rotate-log-on-startup Optional Whether a server rotates its log file during its startup cycle. Default Value: true
log-file-rotation-dir Optional Directory path where the rotated log files will be stored.
rotation-time Optional The start time for a time-based rotation sequence of the log file, in the format k:mm, where k is 1-24. (Requires that you specify a rotation-type of byTime.) At the specified time, the server renames the current log file. Thereafter, the server renames the log file at an interval that you specify in file-time-span. If the specified time has already past, then the server starts its file rotation immediately. By default, the rotation cycle begins immediately.
file-time-span Optional The interval (in hours) at which the server saves old log messages to another file. (Requires that you specify a rotation-type of byTime.) Default Value: 24

 

connection-definition-group

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.

Table 9-16 connection-definition-group subelements
Element Required
Optional
Description
connection-factory-interface 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.
default-connection-properties This complex element is used to define properties for outbound connections at the group level. See default-connection-properties.
connection-instance 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.

connection-instance

You can define the following subelements under connection-instance.

Table 9-17 connection-instance subelements
Element Required
Optional
Description
description Optional Description of the connection instance.
jndi-name resource-link Required 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.
connection-properties Optional Defines all the properties that apply to the connection instance. The connection-properties element can contain one or more property elements, each holding a name and value pair. See properties.