Configuring Your Backend Database

D Configuring Your Backend Database

This appendix explains how to configure a backend database to use with a Jakarta Platform, Enterprise Edition server being tested against the Jakarta EE 8 CTS.

The topics included in this appendix are as follows:

Overview
The init.<database> Ant Target
Database Properties in ts.jte
Database DDL and DML Files
CMP Table Creation

D.1 Overview

All Jakarta Platform, Enterprise Edition servers tested against the Jakarta EE 8 CTS must be configured with a database and JDBC 4.1-compliant drivers. Note that the Jakarta Platform, Enterprise Edition CI, Eclipse GlassFish 5.1 includes the Apache Derby database.

To perform interoperability testing, you need to configure two Jakarta Platform, Enterprise Edition servers and two databases, one of which must be the Jakarta Platform, Enterprise Edition RI with the bundled Apache Derby database. See Jakarta Platform, Enterprise Edition Server Configuration Scenarios for more information.

For the purposes of Jakarta EE 8 CTS testing, all database configuration properties required by the CTS are made in the <TS_HOME>/bin/ts.jte file. The CTS init.<`database> Ant target uses the properties you set in `ts.jte to generate one or more SQL statement files that are in turn used create and populate database tables and configure procedures required by the CTS.

The database configuration process comprises four general steps:

Set database-related properties in the <TS_HOME>/bin/ts.jte file.
Configure your Jakarta Platform, Enterprise Edition server implementation for your database and for CTS.
Start your database.
Run the init.<database> Ant target to initialize your database for CTS.

The procedure for configuring your Jakarta Platform, Enterprise Edition server for your database is described in Configuring a Jakarta EE 8 Server. The final step, initializing your database for CTS by running `init.<`database> target, is explained more in the next section.

D.2 The init.<database> Ant Target

Before your Jakarta Platform, Enterprise Edition server database can be tested against the Jakarta EE 8 CTS, the database must be initialized for CTS by means of the Ant init.<`database> target. For example, the `init.javadb Ant task is used to initialize the Apache Derby database for CTS.

This Ant target references database properties in ts.jte file and database-specific DDL and DML files to generate SQL statement files that are read by the Jakarta EE 8 CTS when you start the test suite. The DDL and DML files are described later in this appendix, in Database DDL and DML Files.

The Jakarta EE 8 CTS includes the following database-specific Ant targets:

init.cloudscape
init.db2
init.oracle
init.oracleDD
init.oracleInet
init.derby
init.javadb
init.sybase
init.sybaseInet
init.mssqlserver
init.mssqlserverInet
init.mssqlserverDD

Each Ant target uses a database-specific JDBC driver to configure a backend for a specific database; for example, OracleInet/Oracle Inet driver; OracleDD/Oracle DataDirect driver. These targets are configured in the <TS_HOME>/xml/initdb.xml file.

D.3 Database Properties in ts.jte

Listed below are the names and descriptions for the database properties you need to set for CTS testing.

Note that some properties take the form property`.ri`. In all cases, properties with an .ri suffix are used for interoperability testing only. In such cases, the property value applies to the Jakarta Platform, Enterprise Edition VI server (the server you want to test) and the property`.ri` value applies to the Jakarta Platform, Enterprise Edition CI, Eclipse GlassFish 5.1 server. For example:

db.dml.file=VI_DML_filename
db.dml.file.ri=RI_DML_filename

The property`.ri` properties are only used in two-server configurations; that is, when you are performing interoperability tests.

Table D-1 ts.jte Database Properties

Property Description

Property	Description
database`.classes`	`CLASSPATH` to JDBC driver classes.
database`.dataSource`	DataSource driver.
database`.dbName`	Database Name.
database`.driver`	DriverManager driver.
database`.password`	User password configured.
database`.poolName`	Name of pool configured in the RI (do not change!).
database`.port`	Database Server port.
database`.properties`	Additional properties required by the defined data source for each driver configuration in `ts.jte`. You should not need to modify this property.
database`.server`	Database Server.
database`.url`	URL for the CTS database; the `dbName`, `server`, and `port` properties are automatically substituted in to build the correct URL. You should never need to modify this property.
database`.user`	User ID configured.
`create.cmp.tables`	When set to `false`, the application server is responsible for creating CMP tables at deployment of the EJB/EAR. When set to `true`, `init.`<datbase> creates the tables used by CMP EJBs. The SQL for the CMP tables are contained in <TS_HOME>/`database/sql/`database`.ddl.cmp.sql` and <TS_HOME>/`database/sql/`database`.ddl.interop.sql`.
`db.dml.file`	Tells init.`database which DML file to use for the VI database; for example, `db.dml.file=${javadb.dml.file}.
`db.dml.file.ri`	Tells init.`database which DML file to use for the RI database; for example, `db.dml.file=${javadb.dml.file}.
`jdbc.lib.class.path`	Used by the database`.classes` properties to point to the location of the JDBC drivers.
`jdbc.poolName`	Configures the connection pool that will be used in the CTS test run; for example, `jdbc.poolName=${javadb.poolName}`. Set this property when running against the RI if using a database other than Apache Derby.
`password1`	Password for the JDBC/DB1 resource; for example, `password1=${javadb.passwd}`.
`password2`	Password for the JDBC/DB2 resource; for example, `password2=${javadb.passwd}`.
`password3`	Password for the JDBC/DBTimer resource; for example, `password3=${javadb.passwd}`.
`user1`	User name for the JDBC/DB1 resource; for example, `user1=${javadb.user}`.
`user2`	User name for the JDBC/DB2 resource; for example, `user2=${javadb.user}`.
`user3`	User name for the JDBC/DBTimer resource; for example, `user3=${javadb.user}`.

database`.classes`

CLASSPATH to JDBC driver classes.

database`.dataSource`

DataSource driver.

database`.dbName`

Database Name.

database`.driver`

DriverManager driver.

database`.password`

User password configured.

database`.poolName`

Name of pool configured in the RI (do not change!).

database`.port`

Database Server port.

database`.properties`

Additional properties required by the defined data source for each driver configuration in ts.jte. You should not need to modify this property.

database`.server`

Database Server.

database`.url`

URL for the CTS database; the dbName, server, and port properties are automatically substituted in to build the correct URL. You should never need to modify this property.

database`.user`

User ID configured.

create.cmp.tables

When set to false, the application server is responsible for creating CMP tables at deployment of the EJB/EAR. When set to true, init.<datbase> creates the tables used by CMP EJBs. The SQL for the CMP tables are contained in <TS_HOME>/`database/sql/database.ddl.cmp.sql` and <TS_HOME>/`database/sql/database.ddl.interop.sql`.

db.dml.file

Tells init.`database which DML file to use for the VI database; for example, `db.dml.file=${javadb.dml.file}.

db.dml.file.ri

Tells init.`database which DML file to use for the RI database; for example, `db.dml.file=${javadb.dml.file}.

jdbc.lib.class.path

Used by the database`.classes` properties to point to the location of the JDBC drivers.

jdbc.poolName

Configures the connection pool that will be used in the CTS test run; for example, jdbc.poolName=${javadb.poolName}. Set this property when running against the RI if using a database other than Apache Derby.

password1

Password for the JDBC/DB1 resource; for example, password1=${javadb.passwd}.

password2

Password for the JDBC/DB2 resource; for example, password2=${javadb.passwd}.

password3

Password for the JDBC/DBTimer resource; for example, password3=${javadb.passwd}.

user1

User name for the JDBC/DB1 resource; for example, user1=${javadb.user}.

user2

User name for the JDBC/DB2 resource; for example, user2=${javadb.user}.

user3

User name for the JDBC/DBTimer resource; for example, user3=${javadb.user}.

D.4 Database DDL and DML Files

For each supported database type, the Jakarta EE 8 CTS includes a set of DDL and DML files in subdirectories off the <TS_HOME>/sql directory. The config.vi and config.ri targets use two ts.jte properties, db.dml.file and db.dml.file.ri (interop only), to determine the database type, and hence which database-specific DML files to copy as <TS_HOME>/bin/tssql.stmt and tssql.stmt.ri (for interop) files.

The tssql.stmt and tssql.stmt.ri files contain directives for configuring and populating database tables as required by the CTS tests, and for defining any required primary or foreign key constraints and database-specific conmand line terminators.

In addition to the database-specific DML files, the Jakarta EE 8 CTS includes database-specific DDL files, also in subdirectories off <TS_HOME>/sql. These DDL files are used by the `init.`database target to create and drop database tables and procedures required by the CTS.

The SQL statements in the tssql.stmt and tssql.stmt.ri files are read as requested by individual CTS tests, which use the statements to locate required DML files.

The DDL and DML files are as follows:

database`.ddl.sql`: DDL for BMP, Session Beans
database`.ddl.sprocs.sql`: DDL for creating stored procedures
database`.ddl.cmp.sql`: DDL for CMP Entity Beans
database`.ddl.interop.sql`: DDL for interop tests
database`.dml.sql`: DML used during test runs

Each DDL command in each <TS_HOME>/sql/`database is terminated with an ending delimiter. The delimiter for each database is defined in the `<TS_HOME>/bin/xml/initdb.xml file. If your configuration requires the use of a database other than the databases that initdb.xml currently supports, you may modify initdb.xml to include a target to configure the database that you are using.

An example of the syntax for a database target in initdb.xml is shown below:

<target name="init.sybase">
  <antcall target="configure.backend">
      <param name="db.driver" value="${sybase.driver}"/>
      <param name="db.url" value="${sybase.url}"/>
      <param name="db.user" value="${sybase.user}"/>
      <param name="db.password" value="${sybase.passwd}"/>
      <param name="db.classpath" value="${sybase.classes}"/>
      <param name="db.delimiter" value="!"/>
      <param name="db.name" value="sybase" />
  </antcall>
</target>

The database`.name` property should be added to your ts.jte file. The db.name property is the name of a subdirectory in <TS_HOME>/sql. After updating initdb.xml, you invoke the new target with:

ant -f <TS_HOME>/bin/xml/initdb.xml init.databasename

D.5 CMP Table Creation

If the application server under test does not provide an option to automatically create tables used by CMP Entity EJBs, the needed SQL is provided in <TS_HOME>/sql/`database/database.cmp.sql`.

Setting the ts.jte property create.cmp.tables=true instructs the init.`databasename target to create the tables defined in the `<TS_HOME>/sql/`database/database.cmp.sql` file.

If you set create.cmp.tables=false in the ts.jte file, it is expected that you will create the necessary CMP tables at deployment time.