1. Install J2EE Reference Implementation (RI)
A J2EE RI installation is required by CTS so it has to be installed before the CTS installation. Use the j2eeri-1_4_1-fcs-bin-b05-windows-04_mar_2004.zip reference implementation bundle available on cvs.jboss.com in the j2ee14-tck-dist CVS module.
export CVSROOT=:ext:email@example.com:/home/cvs cvs co j2ee14-tck-dist
1.1 Unzip the J2EE RI archive
Unzip the J2EE RI bundle in a directory at your convenience. The unzip process will create a j2eeri-1_4_1 sub-directory.
1.2 Set J2EE_HOME
Define the J2EE_HOME environment variable to contain the path to the J2EE RI installation directory just created at the previous step.
If you extracted J2EE RI in C:\work, then your J2EE_HOME should be C:\work\j2eeri-1_4_1.
1.3 Set JAVA_HOME
Set the JAVA_HOME environment variable (if it is not already set) to point to your JDK directory.
JBoss 5.0 with EJB3 support needs Java 5 to run. Otherwise, you can also use Java 4.
1.4 Initialize J2EE RI
Set up the J2EE RI by executing the following ant target
cd $J2EE_HOME ./lib/ant/bin/ant -buildfile ./setup.xml setup
If you get a port error when running the setup target, you can modify your setup.xml, but if you do that, it is important to remember to apply the same modifications to the $TS_HOME/bin/ts.jte CTS configuration file, later.
1.5 Start/stop J2EE RI
cd $J2EE_HOME/bin ./asadmin.bat start-domain
The command can be run with cygwin. The output generated by start-up should look similar to:
$ ./asadmin.bat start-domain Starting Domain domain1, please wait. Log redirected to C:\work\tck\j2eeri-1_4_1\domains\domain1\logs\server.log. Domain domain1 started.
After you make sure the RI starts and there are no errors in the logs, stop it, as it needs to be down during the CTS installation procedure.
cd $J2EE_HOME/bin ./asadmin.bat stop-domain
2. Install CTS
Use the CTS bundle available on cvs.jboss.com as part of the j2ee14-tck-dist CVS module. The file that contains the bundle is j2eetck-1_4_1-fcs-bin-b09-08_apr_2004.zip
When installing CTS in a Windows environment, J2SE, CTS and J2EE RI must be installed on the same drive. For more details, see CTS User Guide, page 22.
2.1 Unzip the CTS archive
Unzip j2eetck-1_4_1-fcs-bin-b09-08_apr_2004.zip in a directory at your convenience. The unzip process will create a j2eetck sub-directory.
If you need access to documentation, unzip j2eetck-1_4_1-fcs-doc-b09-08_apr_2004.zip inside the newly created j2eetck directory. The unzip process will create a j2eetck/docs sub-directory containing the TCK user guides.
2.2 Set TS_HOME
Define the TS_HOME environment variable to contain the path to the J2EE CTS installation directory just created at the previous step.
If you extracted the CTS zip file in C:\work, then your TS_HOME should be C:\work\j2eetck.
3. Install JBoss as target Vendor Implementation
3.1 Prepare the JBoss instance to be tested
Either build a JBoss instance from source or install a pre-built bundle. In the end, it is important to have access to a fully functional JBoss installation, containing at least the 'default' and 'all' configurations.
On Windows, it is necessary to deal with the 255 character path limitation, so it is a good idea to copy the JBoss installation that you are preparing for testing into a directory whose absolute path is as short as possible. Failure to do so may result in TCK servlet test misbehavior, usually materialized in ClassNotFoundExceptions.
Using C:\jb5 as home of the JBoss test instance proved to work fine.
3.2 Set JBOSS_HOME
Define the JBOSS_HOME environment variable to contain the path to the home directory of the JBoss instance that will be used for testing (the directory containing bin, client, docs, lib and server sub-directories)
Provided that you followed the advice given to you at the previous step, your JBOSS_HOME should be C:\jb5.
3.3 Check out JBoss TCK modifications
Check out the module containing TCK modifications from the JBoss internal repository in a directory at your convenience:
export CVSROOT=:ext:firstname.lastname@example.org:/home/cvs cvs co j2eetck-mods
3.4 Set TCK_MODS_HOME
Define the TCK_MODS_HOME environment variable to contain the path to the j2eetck-mods directory just created at the previous step.
If you checked out the TCK modification module into C:\work, then your TCK_MODS_HOME should be C:\work\j2eetck-mods.
3.5 Apply JBoss TCK modifications to CTS
J2EE_HOME, TS_HOME and JBOSS_HOME must be correctly set when you run the script that applies JBoss modifications to CTS.
From $TCK_MODS_HOME run ant as specified below:
cd $TCK_MODS_HOME ant -Dj2ee.server=jboss
This step does the following:
Copies $TCK_MODS_HOME/bin/ts-jboss.jte over $TS_HOME/bin/ts.jte and hard codes the value of the JBOSS_HOME environment variable as j2ee.home inside.
Builds the JBoss TCK porting jars and copies the artifacts (for example jboss-porting.jar) under $TS_HOME/jboss.
Copies $TCK_MODS_HOME/bin/ts-top-level-build.xml over $TS_HOME/build.xml.
Copies $TCK_MODS_HOME/bin/xml/j2ee_jboss.xml over $TS_HOME/bin/xml/j2ee_vi.xml.
Copies $TCK_MODS_HOME/bin/xml/jboss-cts.xml in $TS_HOME/bin/xml, to be used by j2ee_vi.xml.
Copies $TCK_MODS_HOME/bin/conf/ over $TS_HOME/bin/deploy/ inside $TS_HOME/jboss. These are configuration files and deployment archives to be used to overwrite the corresponding files from a standard JBoss configuration, when it will be converted to a CTS-ready configuration.
3.6 Set JBOSS_MESSAGING_HOME (Only needed when testing JBoss Messaging)
This step should be only executed if you want to start the test JBoss instance with a JBoss Messaging JMS provider installed. If you want to execute a standard CTS run with the (still) default JBossMQ provider, skip this step. This is just a temporary procedure that will be dropped as soon as JBoss Messaging becomes the default JBoss JMS provider.
Define the JBOSS_MESSAGING_HOME environment variable to contain the path to JBoss Messaging development directory.
If your JBoss head development directory is C: work\jboss-head\jms, then your JBOSS_MESSAGING_HOME should be C:\work\jboss-head\jms.
3.7 Apply JBoss Messaging-specific modifications (Only needed when testing JBoss Messaging)
This step should be executed only if you want to start the test JBoss instance with a JBoss Messaging JMS provider installed. If you want to execute a standard CTS run with the (still) default JBossMQ provider, skip this step. This is just a temporary procedure that will be dropped as soon as JBoss Messaging becomes the default JBoss JMS provider.
From $JBOSS_MESSAGING_HOME/src/cts run ant without arguments. However, before actually doing it, review what changes are applied at this step:
The script copies $JBOSS_MESSAGING_HOME/src/cts/bin/xml/j2ee_jboss_messaging.xml over $TS_HOME/bin/xml/j2ee_vi.xml.
Before actually applying the change, and if you haven't updated j2eetck-mods in a while, it is a good idea to diff j2ee_vi.xml and j2ee_jboss_messaging.xml and make sure they are still compatible.
The script copies $JBOSS_MESSAGING_HOME/src/cts/bin/xml/jboss-cts.xml over $TS_HOME/bin/xml/jboss-cts.xml.
Before actually applying the change, and if you haven't updated j2eetck-mods in a while, it is a good idea to diff those jboss-cts.xml files and make sure they are still compatible. Also make sure that $JBOSS_MESSAGING_HOME/src/cts/conf contains valid files.
Modifies $TS_HOME/bin/ts.jte by replacing the name of the tested server configuration with cts-messaging, and adjusting some properties (jboss.jms.destination.manager.object.name, jboss.client.classpath) with Messaging-specific values.
Modify $JBOSS_MESSAGING_HOME/src/cts/build.xml and insert the actual value of jboss.client.classpath from $TS_HOME/bin/ts.jte in the regexp. TODO: replace with a more elegant solution.
After checking if changes are still relevant, apply them:
cd $JBOSS_MESSAGING_HOME/src/cts ant
3.8 Customize ts.jte
Customize $TS_HOME/bin/ts.jte. Properties you may want to change:
mailuser - set it to your mail address
mailhost - set it to your mail host
3.9 Install JBoss as target Vendor Implementation
Make sure JBoss is not running.
From a non-cygwin terminal, unset the ANT_HOME environment property and run the configuration script:
cd %TS_HOME%\bin set ANT_HOME= tsant config.vi
This step creates a custom $JBOSS_HOME/server/cts (or $JBOSS_HOME/server/cts-messaging if you executed the previous JBoss Messaging-specific steps). The ant script responsible with actually creating the configuration is $TS_HOME/bin/xml/jboss-cts.xml
To reverse the process, if needed, you can use
3.10 Initialize the PointBase database
Copy the license files in $J2EE_HOME/pointbase/tools/serveroption, if they are not already there:
cp $J2EE_HOME/pointbase/lib/*.lic $J2EE_HOME/pointbase/tools/serveroption
In a new non-cygwin console, run the PointBase server start script:
cd $J2EE_HOME\pointbase\tools\serveroption .\startserver.bat
From a different non-cygwin console initialize the database:
cd %TS_HOME%\bin set ANT_HOME= tsant init.pointbase
3.11 Deploy latest Messaging archive (Only needed when testing JBoss Messaging)
This step should be only executed if you want to start the test JBoss instance with a JBoss Messaging JMS provider installed.
cd $JBOSS_MESSAGING_HOME ./build.sh clean ./build.sh cts-deploy
3.12 Start the JBoss server instance
Start the JBoss server instance using the cts configuration (or cts-messaging if you want to test the Messaging implementation).
cd $JBOSS_HOME/bin ./run.sh -c <cts|cts-messaging>
3.13 Run CTS
For details on how to run CTS, go to JBossMessagingTCKUse
3.14 Debug CTS
For details on how to debug CTS, go to JBossMessagingTCKDebugging