Installing and Running the JDBC[tm] API Test Suite 1.3.1

Print-friendly Version

Contents

Introduction
Support
Conformance
Steps to Install and Run the Tests
Solaris/Linux
Windows
Test Output
Excluded Tests
Customization of SQL Statements

Introduction

The JDBC^TM API test suite contains tests useful for testing a driver based on JDBC technology ("JDBC driver") for its conformance to the requirements of the Java^TM 2 Platform Enterprise Edition (J2EE^TM). This test suite is intended to assist driver vendors in preparing their drivers for certification in a J2EE compatible configuration using the J2EE Compatibility Test Suite. We have attempted to make the JDBC API Test Suite comprehensive enough that it covers the JDBC requirements tested by the J2EE CTS.

Support

The tests provided in the JDBC API Test Suite are provided as is. The team at Sun working on the JDBC API does not have the resources to help with running these tests. Questions, comments and feedback regarding this test suite should be sent to the following alias:

jdbc-tests@sun.com

Questions regarding all other aspects of the JDBC Specification and API should continue to be sent to:

jdbc@sun.com

/logos/

Conformance

The JDBC API test suite is provided solely for the purpose of evaluating the compatibility of JDBC drivers that are intended to run on the Java 2 Enterprise Edition Platform. Running the tests does not allow any public claims of conformance to be made. (see License)

Programs are available for vendors who wish to certify a JDBC driver as compliant with the J2EE platform. Please contact Sun's Java Software Division marketing department at the following email address for further details:

jdbc-certification@sun.com

Steps to Install and Run the Tests

The tests are run using GNU Make. GNU Make can be downloaded from the following location:

ftp://ftp.gnu.org/pub/gnu/make

The version of GNU Make used to test this distribution on Solaris 2.8 is shown below:

% gnumake --version
GNU Make version 3.78.1, by Richard Stallman and Roland McGrath.
Built for sparc-sun-solaris2.6
Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99
Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

Report bugs to <bug-make@gnu.org>.

[C:/] gnumake --version
GNU Make version 3.78.1, by Richard Stallman and Roland McGrath.
Built for Windows32
Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99
Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

Report bugs to <bug-make@gnu.org>.

% cp gnumake gmake

OR

[C:/] cp gnumake.exe gmake.exe

http://java.sun.com/products/

Solaris/Linux

Download the 'jdbccts-1_3_1.zip' file.

Unzip the 'jdbccts-1_3_1.zip' file:

% unzip jdbccts-1_3_1.zip

% setenv CTS_HOME /local/jdbccts

% cd $CTS_HOME/install

% ./setup

% setenv J2EE_HOME /local/j2sdkee1.3.1
% setenv JAVA_HOME /local/jdk1.3.1

% setenv NO_JAVATEST Y

• CTS.JTE

Edit the file '$CTS_HOME/bin/cts.jte' and provide values for the following properties. The values shown below show the values that should be used when running against the J2EE platform Reference Implementation:

webServerHost=localhost
webServerPort=8000

• CTS_ENV

Edit the file '$CTS_HOME/bin/cts_env' and provide values for the following property:

JAVA_HOME=/local/jdk1.3.1

Additionally,  provide the values for the following properties:

# Settings for Vendor J2EE Implementation
J2EE_HOME=/local/j2sdkee1.3.1
ORB_HOST=localhost
ORB_PORT=1050
LOCAL_CLASSES=

# Settings for Sun RI J2EE Implementation
J2EE_HOME_RI=/local/j2sdkee1.3.1
ORB_HOST_RI=localhost
ORB_PORT_RI=1050
LOCAL_CLASSES_RI=${J2EE_HOME_RI}/lib/cloudscape/RmiJdbc.jar:${J2EE_HOME_RI}/lib/cloudscape/cloudclient.jar

Note: The 'LOCAL_CLASSES' property should include details of the JDBC driver under test with the JDBC^TM 1.3.1 API Test Suite.
 
• USER_CONFIG.SH

Edit the file '$J2EE_HOME/bin/userconfig.sh' and add the following jar file to the J2EE RI classpath.

J2EE_CLASSPATH=$CTS_HOME/lib/j2eects.jar
export J2EE_CLASSPATH

Also add the JAR file(s) of the JDBC driver that you are using to the J2EE classpath.

First add the JDBC Driver name

% $J2EE_HOME/bin/j2eeadmin -addJdbcDriver com.cloudscape.core.JDBCDriver

% $J2EE_HOME/bin/j2eeadmin -addJdbcDataSource jdbc/DB1 jdbc:cloudscape:rmi:CloudscapeDB;create=true

Detailed instructions on adding additional JDBC drivers and data sources to the J2EE Reference Implementation are available at:

http://java.sun.com/j2ee/sdk_1.3/techdocs/release/ConfigGuide.html#12442

% setenv PATH $CTS_HOME/bin:${PATH}

% initdb

[-U <username>]
[-P <password>]
[-S <url>]
[-p <path>]
[-d jdbcDriver]

% cd $CTS_HOME/tests/jdbc/ee
% ctsmake jdbc-tests

Note: If errors occur in deployment of all tests to the J2EE application server, ensure the '$CTS_HOME/tmp' directory has read permissions for all groups.

chmod 755 $CTS_HOME/tmp

Windows

Running the tests on the Windows platform requires that you use the MKS Unix Toolkit. The test suite has been successfully run using the MKS Unix Toolkit 6.1a and MKS Unix Toolkit 6.2.

Note the following instructions that the slashes '/' are forward slashes even though they allow for a DOS style driver letter specification 'C:'

Download the 'jdbccts-1_3_1.zip' file.

Unzip the 'jdbccts-1_3_1.zip' file:

[C:/] unzip jdbccts-1_3_1.zip

Set the CTS_HOME environment variable to the directory where you have unzipped the 'jdbccts-1_3_1.zip' file:

[C:/] export CTS_HOME=d:/local/jdbccts

[C:/] cd $CTS_HOME/install

[C:/] mv setup.bat setup.win32.bat
C:/] ./setup.win32.bat

[C:/] export CTS_HOME=c:/local/jdbccts
[C:/] export J2EE_HOME=c:/local/j2sdkee1.3.1
[C:/] export JAVA_HOME=c://local/jdk1.3.1

[C:/] export NO_JAVATEST=Y

• CTS.JTE

Edit the file '$CTS_HOME/bin/cts.jte' and provide values for the following properties. The values shown below show the values that should be used when running against the J2EE platform Reference Implementation:

webServerHost=localhost
webServerPort=8000

• CTS_ENV

Edit the file '$CTS_HOME/bin/cts_env' and provide values for the following property:

JAVA_HOME=/local/jdk1.3.1

Additionally,  provide the values for the following properties:

# Settings for Vendor J2EE Implementation
J2EE_HOME=/local/j2sdkee1.3.1
ORB_HOST=localhost
ORB_PORT=1050
LOCAL_CLASSES=

# Settings for Sun RI J2EE Implementation
J2EE_HOME_RI=/local/j2sdkee1.3.1
ORB_HOST_RI=localhost
ORB_PORT_RI=1050
LOCAL_CLASSES_RI=${J2EE_HOME_RI}/lib/cloudscape/RmiJdbc.jar:${J2EE_HOME_RI}/lib/cloudscape/cloudclient.jar

Note: The 'LOCAL_CLASSES' property should include details of the JDBC driver under test with the JDBC^TM 1.3.1 API Test Suite.
 
• USER_CONFIG.SH

Edit the file '$J2EE_HOME/bin/userconfig.bat' and add the following jar file to the J2EE RI classpath.

J2EE_CLASSPATH=$CTS_HOME/lib/j2eects.jar
export J2EE_CLASSPATH

Also add the JAR file(s) of the JDBC driver that you are using to the J2EE classpath.
 
• EXECUTE.MK

Edit the file '$CTS_HOME/build/execute.mk' and make the following change on line 39. Remove the quotes from the CPATH variable.'

TOOL_NO_JAVATEST=$(JAVA) $(NO_JT_SYSTEM_PROPERTIES) -classpath $(CPATH) com.sun.cts.util.PrepareJDBCDeploy

First, add the JDBC Driver name:

% $J2EE_HOME/bin/j2eeadmin -addJdbcDriver com.cloudscape.core.JDBCDriver

% $J2EE_HOME/bin/j2eeadmin -addJdbcDataSource jdbc/DB1 jdbc:cloudscape:rmi:CloudscapeDB;create=true

Detailed instructions on adding additional JDBC drivers and data sources to the J2EE Reference Implementation are available at:

http://java.sun.com/j2ee/sdk_1.3/techdocs/release/ConfigGuide.html#12442

[C:/] export PATH=$CTS_HOME/bin:${PATH}

[C:/] initdb

[-U <username>]
[-P <password>]
[-S <url>]
[-p <path>]
[-d jdbcDriver]

[C:/] cd $CTS_HOME/tests/jdbc/ee
[C:/] ctsmake jdbc-tests

Test Output

While the tests are being run, log files are produced in each test sub-directory:

build.out - output from the makefile target 'build'
deploy.out - output from the makefile target 'deploy'
run.out - output from the makefile target 'jdbc-tests'
undeploy.out - output from the makefile target 'undeploy'

 $CTS_HOME/tests/jdbc/ee/jdbc-tests.log

Excluded Tests

The JDBC API test suite contains a list of excluded tests ("the exclude list"). Tests on the exclude list are not run by the test harness. Tests on the exclude list may become required in future versions of the test suite.
 

Customization of SQL Statements

The SQL statements that are executed by the tests may need to be customized for certain DBMSs. Two customized DDL files ('ctssql.ddl.cloudscape', 'ctssql.ddl.oracle') are provided as sample customizations. If vendors wish to provide their own customization the following property in '$CTS_HOME/bin/cts_env' must also be edited.

DDLFILE=${CTS_HOME}/bin/ctssql.ddl.cloudscape