DTD for weblogic-ra.xml

<!--
XML DTD for Weblogic Specific Resource Adapter deployment descriptor 1.0
-->

<!-- NOTE: This DTD is provided as part of the Weblogic Connector BETA
offering and IS SUBJECT TO CHANGE.
-->

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

<!--
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 Desciptor 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 will result 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?)>


<!--
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:	1
-->

<!ELEMENT shrink-period-minutes (#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)>