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

Print-friendly Version

Contents

Introduction
Support
Conformance
Steps to Install and Run the Tests
Unix
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 it's 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

    jdbc-tests@eng.sun.com

We cannot respond to all queries but will attempt to provide an FAQ to answer the common questions.

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

    jdbc@eng.sun.com

Vendors wishing to buy support may do so by licensing the J2EE Platform. Please visit the following page for details:

    http://java.sun.com/nav/business/?frontpage-business
 

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@eng.sun.com
 

Steps to Install and Run the Tests

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

The version make-3.79.1 builds on both Unix and Win32 platforms.
 

Unix

Unzip the 'jdbccts.zip' file:

    unzip jdbccts.zip

The version of GNU Make used to test this distribution on Solaris 2.7 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>.
 

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

    setenv CTS_HOME /local/jdbccts

Change the current directory to the install directory:

    cd $CTS_HOME/install

and run the setup script:

    ./setup

Set the following environment variable to the appropriate values for your system:

    setenv J2EE_HOME /local/j2sdkee1.2.1
    setenv JAVA_HOME /local/jdk1.3

Set the following environment variable:

    setenv NO_JAVATEST Y

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
    servletServerHost=localhost
    servletServerPort=8000

Add the following JAR files to the J2EE classpath (in $J2EE_HOME/bin/userconfig.sh) separated by a colon:

    $CTS_HOME/lib/harness.jar
    $CTS_HOME/lib/moo.jar
    $CTS_HOME/lib/util.jar

Also add the JAR file(s) of the JDBC driver that you are using to the J2EE classpath. The environment variable 'LOCAL_CLASSES' should also be set to include the JAR file(s) of the JDBC driver that you are using.

Add the data sources 'jdbc/DB1' and 'jdbc/DB2' ($J2EE_HOME/config/default.properties). The following example shows how the data source names are defined for the Cloudscape database that is included in the J2EE Reference Implementation:

    jdbc.drivers=COM.cloudscape.core.RmiJdbcDriver
    ...
    jdbc.datasources=jdbc/DB1|jdbc:cloudscape:rmi:CloudscapeDB;create=true|jdbc
/DB2|jdbc:cloudscape:rmi:CloudscapeDB;create=true
 

With the application server and database running, start the tests:

    cd $CTS_HOME/tests/jdbc/ee
    gnumake jdbc-tests
 

Windows

Note in the following instructions that the slashes '/' are forward slashes even though they follow a dos style drive letter specification, 'd:'.

Download the 'jdbccts.zip' file.

Unzip the 'jdbccts.zip' file:

    unzip jdbccts.zip

The version of GNU Make used to test this distribution on Windows NT 4.0 is shown below:

    [C:/] gnumake -version
    GNU Make version 3.79.1, by Richard Stallman and Roland McGrath.
    Built for Windows32
    Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 2000
          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>.

All of the following configuration should be done in a MKS shell.

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

    export CTS_HOME=d:/local/jdbccts

Change the current directory to the install directory:

    cd $CTS_HOME/install

and run the setup script. In order to do this you must rename the file 'setup' to 'setup.sh' as, by default, 'setup.bat' will be run if 'setup' and 'setup.bat' are both present:

    mv setup setup.sh
    ./setup.sh

Set the following environment variable to the appropriate values for your system:

    export J2EE_HOME=d:/local/j2sdkee1.2.1
    export JAVA_HOME=d:/local/jdk1.3

Set the following environment variable:

    export NO_JAVATEST=Y

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
    servletServerHost=localhost
    servletServerPort=8000

Add the following JAR files to the J2EE classpath (in $J2EE_HOME/bin/userconfig.sh) separated by a semi-colon:

    d:/j2sdkee1.2.1/lib/harness.jar
    d:/j2sdkee1.2.1/lib/moo.jar
    d:/j2sdkee1.2.1/lib/util.jar

Also add the JAR file(s) of the JDBC driver that you are using to the J2EE classpath. The environment variable 'LOCAL_CLASSES' should also be set to include the JAR file(s) of the JDBC driver that you are using.

Add the data sources 'jdbc/DB1' and 'jdbc/DB2' ($J2EE_HOME/config/default.properties). The following example shows how the data source names are defined for the Cloudscape database that is included in the J2EE Reference Implementation:

    jdbc.drivers=COM.cloudscape.core.RmiJdbcDriver
    ...
    jdbc.datasources=jdbc/DB1|jdbc:cloudscape:rmi:CloudscapeDB;create=true|jdbc
/DB2|jdbc:cloudscape:rmi:CloudscapeDB;create=true
 

With the application server and database running, start the tests:

    cd $CTS_HOME/tests/jdbc/ee
    gnumake 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 'runclient'
    undeploy.out - output from the makefile target 'undeploy'

As each set of tests is run, the output is appended to:

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

When the all of the tests have been run, this file contains a complete log of the test run.
 

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

    $CTS_HOME/bin/ctssql.stmt

This file can be edited to modify the SQL that the tests use.