| <!-- |
| 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 2 TCK README</TITLE> |
| </HEAD> |
| <BODY LANG="en-US" DIR="LTR"> |
| <H1>The JDO 2 Technology Compatibility Kit</H1> |
| <UL> |
| <LI><a href="#overview">Overview</a></LI> |
| <!-- For minor release change documentation |
| <LI><a href="#changes">Changes since the last release</a></LI> |
| --> |
| <LI><a href="#prereqs">Prerequisites</a> |
| <UL> |
| <LI><a href="#maven">Maven</a></LI> |
| <LI><a href="#jndi">JNDI Implementation</a></LI> |
| </UL> |
| </LI> |
| <LI><a href="#building">Building the TCK from source</a></LI> |
| <LI><a href="#running">Running the TCK</a> |
| <UL> |
| <LI><a href="#goals">Custom Goals</a></LI> |
| <LI><a href="#cli">Command Line Options</a></LI> |
| <LI><a href="#files">Files</a></LI> |
| <LI><a href="#examples">Examples</a></LI> |
| </UL></LI> |
| </UL> |
| <a name="overview"></a> |
| <H2>Overview of the JDO 2 Technology Compatibility Kit</H2> |
| <p> |
| The JDO 2 project includes the JDO 2 TCK and its dependencies: |
| </p> |
| <UL> |
| <LI>api2 contains source to build jdo2-api-2.2.jar, which defines the JDO API version 2.2 for Java 1.5 and later.</LI> |
| <LI>api2-legacy contains source to build jdo2-api-legacy-2.2.jar, which defines the JDO API version 2.2 for Java 1.4 and earlier.</LI> |
| <LI>core20 contains the JDO2 core, including utility and metadata model classes</LI> |
| <LI>enhancer20 contains the utility classes used for verifying enhanced files</LI> |
| <LI>tck2 contains the JDO 2.2 Technology Compatibility Kit for Java 1.5 and later.</LI> |
| <LI>tck2-legacy contains the JDO 2.2 Technology Compatibility Kit for Java 1.4 and earlier.</LI> |
| </UL> |
| <p> |
| JDO releases may be downloaded from <a href="http://db.apache.org/jdo/downloads.html">the Apache JDO downloads page</a>. Minor updates of releases are only available as source from the Subversion repository. Follow the instructions <a href="#building">below</a> to build the TCK from source. |
| <p> |
| For complete rules for certifying a JDO implementation, |
| see RunRules.html in the top level tck2 or tck2-legacy project directory. |
| </p> |
| <!-- When creating a new minor release branch, list changes from the major release here |
| |
| <a name="changes"></a> |
| <h2>Changes since the Major Release</h2> |
| <p> |
| </p> |
| |
| --> |
| <a name="prereqs"></a> |
| <h2>Prerequisites</h2> |
| <p> |
| You must install the software listed in the following sections |
| to successfully run the TCK. |
| Other dependencies, such as the reference implementation, DataNucleus, |
| and the Apache Derby database, are downloaded automatically by maven. |
| Note that Apache JDO uses the apache commons logging package for logging. |
| </p> |
| <a name="maven"></a> |
| <h3>Maven</h3> |
| <p> |
| You must have Maven version 1.0.1, 1.0.2, or 1.1 to build the projects |
| from source and to execute the TCK. You can download maven from |
| http://maven.apache.org/start/download.html |
| </p><p> |
| Note that maven uses the user.home system property for the location |
| of the maven local repostitory: ${user.home}/.maven/repository. |
| Under Windows this system property is C:\Documents and Settings\<i>user</i> |
| no matter what the HOME variable is set to. As a workaround you may set the |
| system property by adding -Duser.home=%HOME% to the environment variable |
| MAVEN_OPTS. |
| </p> <p> |
| Mevenide is a nice maven plugin for IDEs available from http://mevenide.codehaus.org. |
| In Netbeans, after you install the plugin, you can open an |
| existing maven project by File -> Open Project -> Open Project Folder. |
| Navigate to a directory including a maven project (e.g. api2) and choose this |
| directory. Netbeans will create a project folder. If you right-click the Maven |
| project you can examine the contents of the project.xml (see Properties) or |
| execute goals. |
| </p> |
| <a name="jndi"></a> |
| <h3>JNDI implementation (fscontext.jar and providerutil.jar)</h3> |
| <p> |
| The JNDI test cases in tck2 need a JNDI implementation. |
| The TCK is configured to use Sun's JNDI implementation. |
| To use your own implementation, put the implementation |
| jar files into lib/ext and update jndi.properties in the TCK directory |
| src/conf. To download Sun's implementation, go to |
| http://java.sun.com/products/jndi/downloads/index.html, |
| click the Download button at 'Download JNDI 1.2.1 & More', accept a license |
| agreement, download 'File System Service Provider, 1.2 Beta 3' and then unpack |
| the downloaded zip. It includes the jars fscontext.jar and providerutil.jar. |
| </p> |
| <a name="building"></a> |
| <h2>Building the TCK from Source</h2> |
| For instructions for checking out the JDO source, see the Apache JDO <a href="http://db.apache.org/jdo/svn.html">source code</a> page. |
| To build the TCK dependencies, change to the top level directory of the branch you are working in (or trunk if you are using the latest unreleased code) and run |
| <pre> |
| maven tck2.default |
| </pre> |
| Then change to the tck2 or tck2-legacy directory and run |
| <pre> |
| maven build |
| </pre> |
| When execution completes, you are ready to run the TCK. |
| <p> |
| <a name="running"></a> |
| <h2>Running the TCK</h2> |
| <p> |
| In the tck2 project, run "maven build" to build the tck. This will |
| compile, enhance, install the schemas, and run all the tests on the RI on all |
| supported databases and identitytypes. |
| </p> |
| <p> |
| You may use the following custom goals and command line options |
| with the tck2 project: |
| </p> |
| <a name="goals"></a> |
| <h3>Custom Goals</h3> |
| <DL> |
| <DT>help |
| <DD>displays help text describing custom goals and options |
| <DT>runtck.jdori |
| <DD>runs the TCK on the JDO Reference Implementation |
| <DT>runtck.iut |
| <DD>runs the TCK on the implementation under test |
| <DT>installSchema |
| <DD>installs the database schema |
| <DT>enhance.jdori |
| <DD>enhances the class files using the JDO RI enhancer |
| <DT>enhance.iut |
| <DD>enhances the class files using the implementation under test's enhancer |
| <DT>debugtck.jdori |
| <DD>waits for a debugger to attach and then runs the TCK on the JDO RI |
| <DT>debugtck.iut |
| <DD>waits for a debugger to attach and then runs the TCK on the implementation under test |
| <DT>cleanClasses |
| <DD>deletes classes and enhanced classes |
| </DL> |
| |
| <a name="cli"></a> |
| <h3>Command Line Options</h3> |
| <DL> |
| <DT>-Djdo.tck.cfglist=<i>configuration file list</i><DD>Overrides the definition of jdo.tck.cfglist found in tck2/src/conf/configuration.list by supplying one or more space-separated test configuration files. Test configuration files typically have the .conf extension. To run a single test, create a .conf file (copy an existing file) and put the test into the jdo.tck.classes property. |
| <DT>-Djdo.tck.dblist=<i>database list</i><DD>Overrides the property value in project.properties by supplying one or more space-separated database names |
| <DT>-Djdo.tck.identitytypes=<i>identity type list</i><DD>Overrides the property value in project.properties by supplying one or more space-separated identity types (applicationidentity or datastoreidentity) to use for this run. |
| <DT>-Djdo.tck.cleanupaftertest=<i>boolean</i><DD>When false, data is retained in the database after the test. This allows inspection of data after test is run. Default is true. |
| <DT>-Djdo.tck.debug.port=<i>port number</i><DD>Sets the port number the JVM should listen for a debugger on. Default is 8787. |
| <DT>-Djdo.tck.debug.jvmargs=<i>args</i><DD>Sets the "-Xdebug ..." arguments to allow you to supply your own debug directives. |
| </DL> |
| <a name="files"></a> |
| <h3>Files</h3> |
| <p>Maven looks for the following configuration files in src/conf: |
| <UL> |
| <LI>configurations.list |
| <br>A list of files. Each file listed is a test configuration file.</LI> |
| <LI>test configuration files (*.conf) |
| <br>Each of these files sets values for |
| <DL> |
| <DT>jdo.tck.testdescription |
| <DD>An optional string describing the purpose of these tests |
| <DT>jdo.tck.classes |
| <DD>A list of one or more test classes (required) |
| <DT>jdo.tck.testdata |
| <DD>The fully qualified file name of the xml test data file(optional) |
| <DT>jdo.tck.standarddata |
| <DD>The fully qualified file name of the xml test data file(optional) |
| <DT>jdo.tck.mapping |
| <DD>The file designator that maven.xml uses to build a javax.jdo.option.Mapping value and corresponding schema name (required) |
| </DL></LI> |
| <LI>exclude.list |
| <br>A list of test classes NOT to execute during a TCK test run</LI> |
| </UL> |
| <a name="examples"></a> |
| <h3>Examples</h3> |
| <DL> |
| <DT>maven -Djdo.tck.identitytypes=datastoreidentity installSchema |
| <DD>Installs the database schema for datastore identity for all supported databases |
| |
| <DT>maven -Djdo.tck.cfglist="alltests.conf cfg1.conf" runtck.jdori |
| <DD>Runs the test configurations specified in alltests.conf and cfg1.conf on the JDORI, using all supported identity types and databases. |
| |
| <DT>maven -Djdo.tck.cfglist=detach.conf debugtck.jdori |
| <DD>Runs the test detach.conf configuration, waiting for a debugger to attach on the default port |
| |
| <DT>maven -Djdo.tck.cfglist=detach.conf -Djdo.tck.debug.port=9343 debugtck.jdori |
| <DD>Runs the test detach.conf configuration, waiting for a debugger to attach on port 9343 |
| </DL> |
| <p> |
| Note: |
| </p> |
| <UL> |
| <LI type="none">By default, the database schema is NOT installed when the custom goals runtck.iut and runtck.jdori are run.</LI> |
| <LI type="none">maven build installs the database schema and runs the TCK on the JDO Reference Implementation.</LI> |
| <LI type="none">Enhancement is always done before running the TCK when the enhanced classes are not up to date.</LI> |
| </UL> |
| |
| </BODY> |
| </HTML> |
| |