connector-j2ee-engine.dtd (SAP Library

connector-j2ee-engine.dtd

Definition

A document type definition (DTD) used for creating XML documents to customize a resource adapter for Enterprise Information System (EIS) connectivity at deploy time.

Use

In the SAP J2EE Engine, you can deploy a resource adapter archive (RAR) that complies with the requirements of the J2EE Connector Architecture 1.0 standard.

In addition to the standard deployment descriptor – ra.xml, you can use this DTD to create an additional deployment descriptor for your resource adapter. It contains customization settings, which are applied at deployment time.

You can use the Structure link Deploy Tool to generate the additional deployment descriptor.

Structure

The connector-j2ee-engine.dtd has the following structure:

This graphic is explained in the accompanying text

The use of each tag is explained in detail as follows:

<!--

Connector-j2ee-engine is the root element for this deployment descriptor. It contains security information, information about the JNDI name and the alias(es) defined for the resource adapter, the driver for JDBC connectivity for this application, the declaration of specific properties (optional), loader references, as well as the definition of connection pool parameters (optional).

-->

<!ELEMENT connector-j2ee-engine (jndi-name?, alias*, authentication-type?, user-store?, identity-subject*, driver*, pool-params?, connector-group?, loader-references?, properties?)>

<!--

Jndi-name element defines the name used for binding the resource adapter in the naming. This name is used when you look up the adapter.

Used in: connector-j2ee-engine

Example: <jndi-name> myAdapter </jndi-name>

-->

<!ELEMENT jndi-name (#PCDATA)>

<!--

Alias element defines an alternative name for the resource adapter. It enables you to use the resource adapter from multiple applications.

Used in: connector-j2ee-engine

Example: <alias> myRA </alias>

-->

<!ELEMENT alias (#PCDATA)>

<!--

User-store element defines a userstore configuration that is used by the resource adapter to store authentication information.

Used in: connector-j2ee-engine

Example: <user-store> CONNECTOR </user-store>

-->

<!ELEMENT user-store (#PCDATA)>

<!--

Authentication-type element defines the mode used for authenticating resources. You can choose from the following options:

· Caller Impersonation – used when the credentials of the caller principal are directly passed to the EIS and used for authentication of the resource principal

· Credentials Mapping – used when the credentials of the caller principal are replaced by the credentials that are used for authentication to the EIS; in this case, you have to specify a userstore where the EIS credentials are stored.

· Configured Identity – used when all caller principals obtain a connection to the EIS using use the same pre-configured identity. You have to specify either a userstore that contains the identity, or a user name and a password for the configured identity.

· Principal Mapping – used when particular caller principals are mapped to an EIS principal. Only authorized caller principals can obtain a connection using a specific identity. You can either specify the userstore where this identity is stored, or enter the name and the password of the resource principal.

Used in: connector-j2ee-engine

Example: <authentication-type> Principal Mapping </authentication type>

-->

<!ELEMENT authentication-type (#PCDATA)>

<!--

Identity-subject element contains security information, which enables the authentication of a user (principal) to the EIS resources. The element defines an identity subject with the specified mapping of caller and resource principal data.

Used in: connector-j2ee-engine

Example:

<identity-subject>

<caller-principal>

<group-name>

administrators

</group-name>

<user-name>

Administrator

</user-name>

</caller-principal>

<resource-principal>

<user-name>

Guest

</user-name>

<user-password>

guest

</user-password>

</resource-principal>

<identity-subject>

-->

<!ELEMENT identity-subject (caller-principal?, resource-principal)>

<!--

Caller-principal element encapsulates information about the names of users or groups (or both) who are authorized to log on to the SAP J2EE Engine. This element is optional.

Used in: identity-subject

-->

<!ELEMENT caller-principal (group-name*, user-name*)>

<!--

Resource-principal element encapsulates authentication information about a user that is authorized to access particular resource in the EIS. The information includes username and user password.

Used in: identity-subject

-->

<!ELEMENT resource-principal (user-name, user-password)>

<!--

Group-name element defines the name of a group on the SAP J2EE Engine.

Used in: caller-principal

-->

<!ELEMENT group-name (#PCDATA)>

<!--

User-name element defines a valid name, under which a user is authorized to log on to the server and access resources.

Used in: caller-principal, resource-principal

-->

<!ELEMENT user-name (#PCDATA)>

<!--

User-password element defines a valid password used to authenticate the user to the EIS.

Used in: resource-principal

-->

<!ELEMENT user-password (#PCDATA)>

<!--

Driver element defines the driver that can be used by the connector to obtain a connection to a relational database. The system registers that the specified driver has been deployed with the current application and loads the driver with the application loader. The information in this element includes the driver class name and the archive file name.

Used in: connector-j2ee-engine

Example:

<driver-name>

myDriverSapDB

</driver-name>

<driver-class-name>

com.sap.dbtech.jdbc.DriverSapDB

</driver-class-name>

<file-name>

sapdbc.jar

</file-name>

</driver>

-->

<!ELEMENT driver (driver-name, driver-class-name, file-name*)>

<!--

Driver-name element specifies an optional name for the JDBC driver.

Used in: driver

-->

<!ELEMENT driver-name (#PCDATA)>

<!--

Driver-class-name element specifies the fully qualified Java name of the driver class.

Used in: driver

-->

<!ELEMENT driver-class-name (#PCDATA)>

<!--

File-name element defines the name of the driver archive file.

-->

<!ELEMENT file-name (#PCDATA)>

<!--

Pool-params element contains properties of the connection pool. This element is optional – you may choose not to use connection pooling.

Used in: connector-j2ee-engine

-->

<!ELEMENT pool-params (max-connections-number, max-time-to-wait-connection?, expiration-control?)>

<!--

Max-connections-number element defines the maximum number of connections to the EIS that can be stored in the connection pool.

Used in: pool-params

-->

<!ELEMENT max-connections-number (#PCDATA)>

<!--

Max-time-to-wait-connection element is used if the connection pool does not hold a connection that satisfies the client request – that is, its parameters differ from those required. This element defines the time (in seconds) for the system to wait before creating a new connection if no suitable connection is returned to the pool.

Used in: pool-params

-->

<!ELEMENT max-time-to-wait-connection (#PCDATA)>

<!--

Expiration-control element is used to manage the connection pool. It defines how long the connections may stay in the pool and how often the old connection objects are destroyed.

Used in: pool-params

-->

<!ELEMENT expiration-control (connection-lifetime, run-cleanup-thread)>

<!--

Connection-lifetime element defines how long a connection may be kept in the connection pool. Once the period specified (in seconds) has expired, the old connection is removed from the pool to be replaced by a newer one.

Used in: expiration-control

-->

<!ELEMENT connection-lifetime (#PCDATA)>

<!--

Run-cleanup-thread element defines how often the system runs a thread, which destroys all unused connection objects. The interval is specified in seconds.

Used in: expiration-control

-->

<!ELEMENT run-cleanup-thread (#PCDATA)>

<!--

Connector-group element defines the classloader for a standalone resource adapter. This tag is ignored if the adapter is deployed within an application.

If you set a connector group, the resource adapter is loaded by a classloader named connector:<connectorGroup>; otherwise, the classloader is connector:default.

Used in: connector-j2ee-engine

-->

<!ELEMENT connector-group (#PCDATA)>

<!--

Loader-references element is used when you deploy a standalone component. It defines a reference to the classloader that is used to load the resource adapter. For non-standalone components – that is, when the RAR file is deployed within a J2EE application that also contains other components, the loader reference is set to the application level, the resource adapter is loaded with the application loader, and this tag is ignored.

Used in: connector-j2ee-engine

-->

<!ELEMENT loader-references (loader-name+)>

<!--

Loader-name element specifies the name of the classloader that is used to load this resource adapter.

Used in: loader-reference

Example: <loader-name> connector:myAdapter <loader-name>

-->

<!ELEMENT loader-name (#PCDATA)>

<!--

Properties element encapsulates a set of properties that can be used for additional customization after resource adapter deployment.

Used in: connector-j2ee-engine

-->

<!ELEMENT properties (property+)>

<!--

Property element defines a single property with its name and value.

Used in: properties

-->

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

<!--

Property-name element defines the name of an additional property.

Used in: property

-->

<!ELEMENT property-name (#PCDATA)>

<!--

Property-value element defines the value of an additional property.

Used in: property

-->

<!ELEMENT property-value (#PCDATA)>