Skip navigation.

Programming WebLogic Resource Adapters

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

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.

Element

Required/
Optional

Description

native-libdir

Required if native libraries are present.

Specifies the 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.

Note: 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.

Note: 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.

Element

Required
Optional

Description

name

Required

Specifies the 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.

Element

Required
Optional

Description

default-principal-name

Optional

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.

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.

Element

Required
Optional

Description

use-anonymous-identity

Required

Specifies that the anonymous identity should be used.

principal-name

Required

Specifies that 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.

Element

Required
Optional

Description

use-anonymous-identity

Required

Specifies that the anonymous identity should be used.

principal-name

Required

Specifies that 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.

Element

Required
Optional

Description

use-anonymous-identity

Required

Specifies that the anonymous identity should be used.

principal-name

Required

Specifies that the principal name should be used. This should match a defined WebLogic Server user name.

use-caller-identity

Required

Specifies that the caller's identity should be used.

run-work-as-principal-name

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

Element

Required
Optional

Description

use-anonymous-identity

Required

Specifies that the anonymous identity should be used.

principal-name

Required

Specifies that the principal name should be used. This should match a defined WebLogic Server user name.

use-caller-identity

Required

Specifies that 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.

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.

Element

Required
Optional

Description

default-properties

Optional

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.

admin-object-group

One or More

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.

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.

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.

The default-properties element can contain one or more property elements, each holding a name and value pair. See properties.

admin-object-instance

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

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.

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.

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.

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

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.

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

Specifies the 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

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

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

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

Element

Required
Optional

Description

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.

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 when the size is unwieldy.

Default Value: bySize

number-of-files-limited

Optional

Specifies 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 you must 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

Specifies whether a server rotates its log file during its startup cycle.

Default Value: true

log-file-rotation-dir

Optional

Specifies the 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.

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.

Element

Required
Optional

Description

description

Optional

Specifies a 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.

 

Skip navigation bar  Back to Top Previous Next