data-sources.dtd (SAP Library - Developing Applications Using Java)

data-sources.dtd

Definition

A document type definition (DTD) used for producing XML files for the creation of DataSource objects. It contains parameters that the system uses to initialize a DataSource.

Use

You can register a DataSource for an application or a AS Java library by:

1. Creating a data-source.xml file based on this DTD,

2. Including the file in:

a. The META-INF directory of the application archive (EAR)

b. The ./server/descriptors directory of the library SDA.

You can also use the XML file based on this DTD to create a DataSource object with the make_data_source Shell command from DBPOOL command group.

Structure

The data-sources.dtd defines the following elements:

This graphic is explained in the accompanying text

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

<!--
Data-sources is the root element for this deployment descriptor. It contains information about the associated application and the DataSource object that is created.

-->

<!ELEMENT data-sources (application-name?, data-source+)>

<!--
Application-name element defines the application that is associated to the DataSource. We recommend that you use a separate DataSource for each application. This tag is ignored if the data-sources.xml is deployed together with the application.

Used in: data-sources
-->

<!ELEMENT application-name (#PCDATA)>

<!--
Data-source element contains the properties of the DataSource object. These include: name of used driver, name of DataSource object, alias (must be unique within the container), number of supported connections, isolation level information (optional), number of initial connections (optional), driver and connector properties.

Used in: data-sources

-->

<!ELEMENT data-source (description?, data-source-name, alias*, driver-name, init-connections?, max-connections?, max-time-to-wait-connection?, expiration-control?, isolation-level?, sql-engine, (jdbc-2.0 | jdbc-1.x))>

<!--
Description element contains a short description of a DataSource. This element is optional.

Used in: data-source

Example: <description> This is an example for a description of myDataSource. </description>
-->

<!ELEMENT description (#PCDATA)>

<!--
Data-source-name element specifies the name of the DataSource object to be created. The name must be unique.

Used in: data-source

Example: <data-source-name> myDataSource </data-source-name>
-->

<!ELEMENT data-source-name (#PCDATA)>

<!--
Alias element specifies a unique name used when referring to the particular DataSource object.

Used in: data-source

Example: <alias> myAlias </alias>
-->

<!ELEMENT alias (#PCDATA)>

<!--
Driver-name element provides the name of the JDBC driver used to create the DataSource object.

Used in: data-source

Example: <driver-name> myDriver </driver-name>
-->

<!ELEMENT driver-name (#PCDATA)>

<!--
Init-connections element specifies the number of initial connections created during startup of the DataSource.

Used in: data-source
-->

<!ELEMENT init-connections (#PCDATA)>

<!--
Max-connections element specifies the maximum number of connections the DataSource can create.

Used in: data-source
-->

<!ELEMENT max-connections (#PCDATA)>

<!--
Max-time-to-wait-connection element specifies the time to wait for a connection to become free if the max-connections number is reached.

Used in: data-source
-->

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

<!--
Expiration control element defines parameters for connection life control. These are connection lifetime and a period to run a cleanup thread.

Used in: data-source
-->

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

<!--
Connection-lifetime element specifies a period in seconds for which a connection can stay. The connection is closed after these seconds.

Used in: expiration-control
-->

<!ELEMENT connection-lifetime (#PCDATA)>

<!--
Run-cleanup-thread element specifies a period in seconds, after which the system runs a thread to clean up unused connections.

Used in: expiration-control

-->

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

<!--
Isolation-level element determines a transaction isolation level for the DataSource object. If you do not specify the isolation level, the system uses the default isolation level of the used driver.

Used in: data-source
-->

<!ELEMENT isolation-level (#PCDATA)>

<!--
Sql-engine element defines what type of connection the system should return.

Valid values:

● Open_SQL – SAP’s portable SQL

● Native_SQL

● Vendor_SQL

Used in: data-source
-->

<!ELEMENT sql-engine (#PCDATA)>

Use the following element and its sub-elements if the driver you are using is JDBC 2.0-compliant.

<!--

Use the JDBC-2.0 element and its sub-elements if the driver you are using supports XADataSource or PooledDataSource. You can choose whether to use a ConnectionPoolDataSource to obtain the connection directly from the driver, or a XADataSource that provides a connection handle using the DBPool Service. The information that this element contains includes: class name of CPDS or XADS object, DataSource object factory, and specific properties.

Used in: data-source

Example:

<jdbc-2.0>

<xads-class-name>oracle.jdbc.xa.client.OracleXADataSource</xads-class-name>

<property-name>serverName</property-name>

<property-value>Oracle</property-value>

</property>

<property-name>serverPort</property-name>

<property-value>1234</property-value>

</property>

</properties>

</jdbc-2.0>
-->

<!ELEMENT jdbc-2.0 ((xads-class-name | cpds-class-name), object-factory?, properties?)>

<!--
XADS-class-name element specifies the name of the XADataSource object class.

Used in: jdbc-2.0

Example: <xads-class-name> oracle.jdbc.xa.client.OracleXADataSource </xads-class-name>
-->

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

<!--
CPDS-class-name element specifies the name of the ConnectionPoolDataSource object class.

Used in: jdbc-2.0

Example: <cpds-class-name> oracle.jdbc.pool.OracleConnectionPoolDataSource </cpds-class-name>
-->

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

<!--
Object-factory element specifies the DataSource object factory – for example, oracle.jdbc.pool.OracleDataSourceFactory.

Used in: jdbc-2.0

Example: <object-factory> oracle.jdbc.pool.OracleDataSourceFactory </object-factory>
-->

<!ELEMENT object-factory (#PCDATA)>

<!—

Use JDBC-1.x element if the driver you are using is based on the JDBC Driver Manager. The information that this element contains includes: class name of the driver, driver URL, user name and password, and driver-specific properties (optional).

Used in: data-source

Example:

<jdbc-1.x>

<driver-class-name>com.sap.sql.jdbc.direct.DirectDriver</driver-class-name >

<url>jdbc:sap:sapdb://localhost/TST?timeout=0</url>

<user-name>Administrator</user-name>

<password encrypted=“false”>admin</password>

</jdbc-1.x>
-->

<!ELEMENT jdbc-1.x (driver-class-name, url, user-name, password+, properties?)>

<!--
Driver-class-name element specifies the name of the driver class.

Used in: jdbc-1.x
-->

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

<!--
URL element specifies the URL of the database server.

Used in: jdbc-1.x
-->

<!ELEMENT url (#PCDATA)>

<!--
User-name element specifies a valid username for the database server.

Used in: jdbc-1.x
-->

<!ELEMENT user-name (#PCDATA)>

<!--
Password element specifies a valid password for the specified user in the <user-name> tag.

Used in: jdbc-1.x
-->

<!ELEMENT password (#PCDATA)>

<!--
Deprecated.

This tag defines a “password encrypted” attribute for the password element. The legal values for the attribute are “true” and “false.” If you set it to “true,” encryption is applied on the password for security reasons.

Used in: password
-->

<!ATTLIST password encrypted CDATA #IMPLIED>

<!--
Properties element contains additional driver-specific properties. This element is optional.

Used in: jdbc-2.0, jdbc-1.x

-->

<!ELEMENT properties (property+)>

<!--
Property element describes a particular driver-specific property with its name and value.

Used in: properties
-->

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

<!--
Property-name element specifies the name of a particular driver-specific property.

Used in: property
-->

<!ELEMENT property-name (#PCDATA)>

<!--
Property-value element specifies the value of a particular driver-specific property.

Used in: property
-->

<!ELEMENT property-value (#PCDATA)>