| <!--
|
| Licensed to the Apache Software Foundation (ASF) under one or more
|
| contributor license agreements. See the NOTICE file distributed with
|
| this work for additional information regarding copyright ownership.
|
| The ASF licenses this file to You under the Apache License, Version 2.0
|
| (the "License"); you may not use this file except in compliance with
|
| the License. You may obtain a copy of the License at
|
|
|
| http://www.apache.org/licenses/LICENSE-2.0
|
|
|
| Unless required by applicable law or agreed to in writing, software
|
| distributed under the License is distributed on an "AS IS" BASIS,
|
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
| See the License for the specific language governing permissions and
|
| limitations under the License.
|
| -->
|
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
| <html>
|
| <head>
|
| <meta http-equiv="CONTENT-TYPE" content="text/html; charset=UTF-8">
|
| <title>JDO 3.0 Technology Compatibility Kit Run Rules</title>
|
| <style>
|
| <!--
|
| @page { size: 8.5in 11in }
|
| -->
|
| </style>
|
| </head>
|
| <body dir="LTR" lang="en-US">
|
| <h1 align="CENTER">Running the JDO 3.0 Technology Compatibility Kit</h1>
|
| <p align="CENTER"><br>
|
| <br>
|
| </p>
|
| <p align="CENTER">29-Oct-2011</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Overview</font></font></p>
|
| <p>In order to demonstrate compliance with the Java Data Objects
|
| specification, an implementation must successfully run all of the
|
| TCK
|
| tests that are not on the "excluded" list. The
|
| implementation is hereinafter referred to as the IUT
|
| (Implementation
|
| Under Test).</p>
|
| <p>The results must be posted on a publicly accessible web site for
|
| examination by the public. The posting includes the output of the
|
| test run, which consists of multiple log files containing
|
| configuration information and test results. For an example of the
|
| required posting, please see <a
|
| href="http://db.apache.org/jdo/tck/final">http://db.apache.org/jdo/tck/final</a>.</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Prerequisites</font></font></p>
|
| <p>In order to run the TCK, you must install maven 1.1.x.
|
| M<font face="Times New Roman, serif">aven
|
| </font><a href="http://maven.apache.org/maven-1.x/"><font
|
| face="Times New Roman, serif"><font color="#000000">http://maven.apache.org/maven-1.x/
|
| </font></font></a><font face="Times New Roman, serif">is the</font>
|
| driver of the test programs. Note that Maven 2 is not supported.</p>
|
| <p>You must test the IUT on all configurations that the IUT
|
| supports.
|
| This includes different hardware and operating systems, different
|
| versions of Java, and different datastores. The TCK supports Java
|
| versions 1.5 to 1.6. </p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Installation</font></font></p>
|
| <p>Download the zip file from the distribution location. Unpack the
|
| zip
|
| file into a directory of your choice. In this directory you will
|
| find: </p>
|
| <ul>
|
| <ul>
|
| <li>
|
| <p>README.html </p>
|
| </li>
|
| <li>
|
| <p>maven configuration files project.properties and
|
| project.xml (common project definition for all Apache JDO
|
| projects including the TCK). These files must not be
|
| changed.</p>
|
| </li>
|
| <li>
|
| <p style="margin-bottom: 0.2in" align="LEFT">lib - this
|
| directory contains a directory ext that should contain jar
|
| fi<font face="Times New Roman, serif">les <font
|
| color="#000000">fscontext.jar and providerutil.jar </font>us</font>ed |
|
|
| by the JNDI tests. <font face="Times New Roman, serif"><font
|
| color="#000000">The jar files can be found at </font></font><a
|
| href="http://java.sun.com/products/jndi/downloads/index.html"><font
|
| face="Times New Roman, serif"><font color="#000000">http://java.sun.com/products/jndi/downloads/index.html</font></font></a><font
|
| face="Times New Roman, serif"><font color="#000000">.
|
| Choose "File System Service Provider, 1.2 Beta 3" from
|
| the "Download JNDI 1.2.1 & More" page. Unzip the
|
| archive and install them into the lib/ext directory. It
|
| is permitted to use a different JNDI implementation; see
|
| the README.txt for information on how to configure a
|
| different JNDI implementation.</font></font></p>
|
| </li>
|
| <li>
|
| <p>the TCK directory, which has a release-specific name (e.g.
|
| jdo-tck-3.0) and contains:</p>
|
| <ul>
|
| <li>
|
| <p>maven.xml, project.properties, project.xml - the maven
|
| definition of the project. These files must not be
|
| modified.</p>
|
| </li>
|
| <li>
|
| <p>build.properties - the maven definition for the IUT.
|
| This file may be modified to change any of the IUT
|
| properties needed.</p>
|
| </li>
|
| <li>
|
| <p>this RunRules.html</p>
|
| </li>
|
| <li>
|
| <p>assertions - contains the assertions file identifying
|
| the assertions tested by the tests. This is for
|
| reference.</p>
|
| </li>
|
| <li>
|
| <p>target - this directory contains artifacts of compiling
|
| and running the tests. It does not exist in the
|
| distribution and will be created by the maven build
|
| script.</p>
|
| </li>
|
| <li>
|
| <p>iut_jars - this directory is where the JDO
|
| implementation jars are installed. It is empty in the
|
| distribution. To use the maven target runtck.iut
|
| (required for an implementation to prove compliance),
|
| copy the JDO implementation jar files into this
|
| directory. Alternatively, update the build.properties
|
| file in the TCK directory to refer to an existing
|
| location of the IUT jar files.</p>
|
| </li>
|
| <li>
|
| <p>src - this directory contains the test configuration
|
| files and directories:</p>
|
| <ul>
|
| <li>
|
| <p>testdata - this directory contains data
|
| (represented as .xml files) loaded into the
|
| datastore for tests. These files must not be
|
| modified.</p>
|
| </li>
|
| <li>
|
| <p>sql - this directory contains DDL to define the
|
| tables used in the tests. The files distributed must
|
| not be modified. Files may be created for databases
|
| for which the DDL for the database under test is not
|
| provided. </p>
|
| </li>
|
| <li>
|
| <p>jdo - this directory contains .jdo metadata files
|
| for the persistent classes used in the tests. These
|
| files must not be modified.</p>
|
| </li>
|
| <li>
|
| <p>orm - this directory contains .orm metadata files
|
| to map the persistent classes to the sql tables.
|
| These files must not be modified except to add
|
| DDL-generation information (which is not used by the
|
| TCK).</p>
|
| </li>
|
| <li>
|
| <p>java - this directory contains the source code to
|
| the TCK tests. These files must not be modified.</p>
|
| </li>
|
| <li>
|
| <p>conf - this directory contains the configuration
|
| information for the test runs. The files
|
| iut-pmf.properties, iut-jdoconfig.xml, and
|
| iut-persistence.xml in this directory must be
|
| changed to provide properties for the IUT
|
| persistence manager factory. The file
|
| jndi.properties may be changed to use a different
|
| jndi provider. Other files must not be modified,
|
| except to put a successfully challenged test case
|
| into the trunk/tck20/test/conf/exclude.list. Please
|
| see below.</p>
|
| </li>
|
| </ul>
|
| </li>
|
| </ul>
|
| </li>
|
| </ul>
|
| </ul>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Modifying
|
| the Configuration</font></font></p>
|
| <p>The Implementation Under Test (IUT) can be installed into the
|
| iut_jars directory in the TCK directory. Any .jar files in this
|
| directory are added to the class path used to run the tests.</p>
|
| <p>There are properties in the build.properties file in the TCK
|
| directory that must be changed to configure the IUT execution and
|
| enhancement (optional) environment. These properties begin with
|
| iut.runtck and iut.enhancer. </p>
|
| <p>There is are three properties files that must be modified to be
|
| IUT-specific, all located in the TCK src/conf directory. The
|
| iut-pmf.properties file contains information used to construct the
|
| PersistenceManagerFactory used in the tests. iut-jdoconfig.xml and
|
| iut-persistence.xml also contain PersistenceManagerFactory
|
| properties
|
| used only in tests in the
|
| org.apache.jdo.tck.api.persistencemanagerfactory.config package.
|
| </p>
|
| <p>SQL DDL files are provided for the sql table definitions. The
|
| existing files must not be changed, but files may be added in the
|
| directory in order to provide DDL for additional databases
|
| supported
|
| by the JDO implementation under test.</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Running
|
| the Tests</font></font></p>
|
| <p>From the installation directory, change to the TCK directory.
|
| From
|
| the TCK directory, call "maven build" which will build the
|
| jar files used in the tests, create the Derby database, install
|
| the
|
| schema into the Derby database, and run the TCK on the Reference
|
| Implementation. Success indicates that the TCK was installed
|
| correctly.</p>
|
| <p>Then call "maven runtck.iut" to run the tests on the
|
| Implementation Under Test. This will produce console output plus a
|
| directory in the TCK/target/logs directory whose name contains the
|
| date/time the tests were started. This directory contains the
|
| output
|
| of the tests. This is the directory to be published.</p>
|
| <p>Some of the TCK tests require the implementation to support up to
|
| 20 instances of PersistenceManager with open transactions
|
| simultaneously.</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Debugging
|
| the IUT while Running TCK tests</font></font></p>
|
| <p>Execute "maven help" in the TCK directory in order to
|
| get information on running the TCK tests with a debugger. In
|
| particular, properties jdo.tck.cleanupaftertest, jdo.tck.cfglist,
|
| jdo.tck.identitytypes, and jdo.tck.dblist may be useful.</p>
|
| <p>If you make a change to the IUT enhancer while debugging the TCK
|
| tests (for implementations that use an enhancer) you must remove
|
| the
|
| target/classes directory before continuing in order to make sure
|
| that
|
| the classes are re-enhanced by the changed code.</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">Publishing
|
| the Results of the TCK Tests</font></font></p>
|
| <p>With a successful test run, the log directory with the results of
|
| the tests must be published on a publicly-available web site. The
|
| unmodified directory is the self-certification of the successful
|
| TCK
|
| test run.</p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid"><font
|
| face="Albany, sans-serif"><font size="4">First
|
| Level TCK Appeals Process</font></font></p>
|
| <p style="margin-top: 0.17in; page-break-after: avoid" align="LEFT">If |
| any
|
| test does not pass on the JDO implementation under test, this may
|
| be due to an error in the implementation or in the TCK test. If
|
| you
|
| believe that the failure is due to an error in the TCK test, you
|
| may
|
| challenge the test. To do so, send email to: <a
|
| href="mailto:jdo-dev@db.apache.org">jdo-dev@db.apache.org</a>
|
| with a subject line containing "CHALLENGE" and the name of
|
| the test program, e.g.
|
| org.apache.jdo.tck.api.persistencemanager.ThreadSafe.java; and the
|
| body of the email containing the details of the challenge.</p>
|
| <p>The Maintenance Lead will respond within 15 working days with a
|
| decision on whether there is an error in the test case. If the
|
| issue
|
| is found by the Maintenance Lead to be due to an error in the test
|
| case, the Maintenance Lead might patch the erroneous test or add
|
| the test
|
| to the exclude list.
|
| The user can obtain the TCK updates by checking out the latest
|
| minor version branch.
|
| If a fix is not provided within 15 working days of the receipt of
|
| the challenge,
|
| then the user may put the test into the TCK file
|
| src/conf/exclude.list and
|
| it will not be run as part of the TCK.</p>
|
| <p>Decisions of the Maintenance Lead may be appealed to the full
|
| expert group. A vote of the full expert group will be conducted by
|
| the Maintenance Lead, and a majority of votes cast will decide the
|
| issue. The Maintenance Lead has one vote, as does each member of
|
| the
|
| expert group at the time of the vote.</p>
|
| </body>
|
| </html>
|
