JSR-94 Technology Compatibility Kit (TCK) Tutorial
Quick Start
Here are the procedures to run Drools with the JSR-94 TCK in as few steps as possible. If you desire a more detailed description of the steps, continue to read the rest of this tutorial.
- Download the JSR-94 TCK.
- Replace the Jess run_tck.xml TCK Ant build file with the Drools run_tck.xml TCK Ant build file.
- Replace the Jess tck_res_1.xml and tck_res_2.xml rule files in the lib directory with the Drools rule files tck_res_1.xml and tck_res_2.xml.
- Replace the Jess tck.conf TCK configuration file in the lib directory with the Drools tck.conf TCK configuration file.
- Install the Drools JAR files in the lib directory: drools-base-2.0-beta-17.jar, drools-core-2.0-beta-17.jar, drools-smf-2.0-beta-17.jar, drools-io-2.0-beta-17.jar, drools-java-2.0-beta-17.jar, and drools-jsr94-2.0-beta-17.jar.
- Install the additional dependent JAR files required by Drools in the lib directory: janino-2.0.5.jar and antlr-2.7.2.jar.
- Run the JSR-94 TCK with the command: ant -f run_tck.xml.
- View the results of the JSR-94 TCK at: reports/index.html.
A Note about Jess and the JSR-94 Reference Implementation (RI)
It is important to note that the JSR-94 Reference Implementation (RI) provided in the JSR-94 Specification download is based on Jess, another rule engine, like Drools, written in Java. Note: a significant difference between Jess and Drools is the license terms under which the two rule engines can be used (Drools License, Jess License). The TCK files provided in the JSR-94 Specification download are pre-configured to run the TCK against Jess and the TCK documentation has instructions specifically about how to run the TCK with the Jess RI. Further details about Jess and the JSR-94 Specification can be found in TheServerSide.com online article "Jess and the javax.rules API".
This tutorial focuses solely on how to run the JSR-94 TCK with Drools instead of Jess.
Downloading the Technology Compatibility Kit (TCK)
The Technology Compatibility Kit (TCK) for JSR-94 (the Java Rule Engine API) is available officially available as part of the full JSR-94 Specification download from the Java Community Process website. However, at the time of this writing (28-July-2004) only version 1.0 is available from there. The latest version, v1.1, is only available at this time from this location: http://www.javarules.org/jsr94/jsr94-1.1.zip. It is this v1.1 TCK that was used for this document.
The next two paragraphs in this section are being left here for historical reasons:
At the time of this writing (25-July-2004) the latest JSR-94 download is located on the Proposed Final Draft download page. Be sure you are looking at the "Proposed Final Draft" download page (dated 29 Oct, 2003) and not the "Public Review" download page (dated 12 Aug, 2002).
Click the "Download" button to "download the Specification"; read and accept the license and click the "Continue" button. This should bring you to the actual Download page where there is only one file available to download: "Specification, English (jreng-1_0-pfd-spec-api.zip, 4.18 MB)". Click that text to download the specification.
You should now be in possession of the JSR-94 specification in the form of a file named jreng-1_0-pfd-spec-api.zip jsr94-1.1.zip. Unzip this file to produce a directory entitled jsr94-1.0 jsr94-1.1 which contains the entire JSR-94 specification, including the Technology Compatibility Kit (TCK)._
Feel free to peruse the documentation included in the specification package, most of which is located in the docs directory; however, the following tutorial will walk you through the process of configuring the JSR-94 TCK to run with Drools, so you should be able to safely skip reading any of the documentation provided in the JSR-94 TCK if you are so inclined.
Replacing the TCK Ant Build File
The JSR-94 TCK comes with an Ant build file named run_tck.xml and located in the root directory of the JSR-94 distribution which is used to run the TCK tests against the provided Jess RI JAR files. This file needs to be replaced with a similar Ant build file configured to run with the Drool JAR files. A replacement Ant build file has been provided in the Drools source code repository. Simply download this Drools run_tck.xml file and copy it over the run_tck.xml file provided in the JSR-94 Specification.
Replacing the TCK Rule Files
The JSR-94 TCK comes with two rule execution sets contained in the files tck_res_1.xml and tck_res_2.xml located in the lib directory which are written in a rule language Jess understands. These two files need to be replaced with similar rule execution sets written in Drools rule language. Replacement rule execution sets have been provided in the Drools source code repository. Simply download the Drools rule execution sets named tck_res_1.xml and tck_res_2.xml and copy them over the tck_res_1.xml and tck_res_2.xml files provided in the JSR-94 Specification.
Replacing the TCK Configuration File
The JSR-94 TCK comes with a configuration file named tck.conf and located in the lib directory which is configured to run the TCK tests against the Jess RI. This file needs to be replaced with a similar file configured to run with the Drools JSR-94 implementation. A replacement configuration file has been provided in the Drools source code repository. Simply download this Drools tck.conf file and copy it over the tck.conf file provided in the JSR-94 Specification.
Installing the Drools JAR Files
The Drools run_tck.xml and tck.conf files that you copied in previous steps rely on the appropriate set of Drools distribution JAR files to be located in the lib directory. Simply download the following Drools JAR files and place them all in the lib directory:
Installing the Additional Dependent JAR Files
In addition to the Drools distribution JAR files, the following set of ancillary JAR files will also need to be copied into the lib directory of the JSR-94 Specification:
Running the JSR-94 TCK
With the Drools run_tck.xml, tck_res_1.xml, tck_res_2.xml, and tck.conf files all in place along with the required Drools distribution JAR files and ancillary JAR files, you are ready to execute the JSR-94 TCK test suite. To start the testing process, simple go to the root JSR-94 Specification directory and type the command:
- ant -f run_tck.xml
Assuming the JSR-94 TCK has been configured correctly to run Drools, you should see output resembling the following:
[jsr94-1.1]% ant -f run_tck.xml
Buildfile: run_tck.xml
tck.run:
init:
[echo] JSR 94 API -- 1.1
[echo] Copyright 2004 by Java Community Process
[mkdir] Created dir: /Users/dab/dev/jsr94-1.1/reports
tck.run.tests:
[junit] Running org.jcp.jsr94.tck.ApiSignatureTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.819 sec
[junit] Running org.jcp.jsr94.tck.ConfigurationExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.347 sec
[junit] Running org.jcp.jsr94.tck.HandleTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.075 sec
[junit] Running org.jcp.jsr94.tck.InvalidHandleExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.36 sec
[junit] Running org.jcp.jsr94.tck.InvalidRuleSessionExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.361 sec
[junit] Running org.jcp.jsr94.tck.ObjectFilterTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.468 sec
[junit] Running org.jcp.jsr94.tck.RuleExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.357 sec
[junit] Running org.jcp.jsr94.tck.RuleExecutionExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.359 sec
[junit] Running org.jcp.jsr94.tck.RuleExecutionSetMetadataTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.069 sec
[junit] Running org.jcp.jsr94.tck.RuleExecutionSetNotFoundExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.357 sec
[junit] Running org.jcp.jsr94.tck.RuleRuntimeTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.083 sec
[junit] Running org.jcp.jsr94.tck.RuleServiceProviderManagerTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.503 sec
[junit] Running org.jcp.jsr94.tck.RuleServiceProviderTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.491 sec
[junit] Running org.jcp.jsr94.tck.RuleSessionCreateExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.363 sec
[junit] Running org.jcp.jsr94.tck.RuleSessionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.083 sec
[junit] Running org.jcp.jsr94.tck.RuleSessionTypeUnsupportedExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.393 sec
[junit] Running org.jcp.jsr94.tck.StatefulRuleSessionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.593 sec
[junit] Running org.jcp.jsr94.tck.StatelessRuleSessionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.507 sec
[junit] Running org.jcp.jsr94.tck.admin.LocalRuleExecutionSetProviderTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.083 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleAdministrationExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.368 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleAdministratorTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.011 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleExecutionSetCreateExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.353 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleExecutionSetDeregistrationExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.435 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleExecutionSetProviderTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.13 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleExecutionSetRegisterExceptionTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.374 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleExecutionSetTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.029 sec
[junit] Running org.jcp.jsr94.tck.admin.RuleTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.013 sec
[junit] Running org.jcp.jsr94.tck.ClassLoaderTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.504 sec
tck.run.report:
[junitreport] Transform time: 4379ms
BUILD SUCCESSFUL
Total time: 51 seconds
Viewing the Results
The final results of the JSR-94 TCK test suite is captured in the reports directory. Open up the index.html file in the reports directory to see the results of the entire TCK test run.
Failed Tests - TCK v1.1
At the time of this writing (28-July-2004), Drools version 2.0 beta 17 successfully passes every JSR-94 TCK v1.1 test.
According to clause 2.1(b) of the JSR-94 TCK License, since Drools now "passes, in accordance with the documentation (including the TCK Users Guide, if any), the most current TCK applicable to the latest version of the JCP Specification," Drools may now "market" and "promote" itself "as being compatible, compliant, conformant [and] otherwise consistent with the JCP Specification."
Failed Tests - TCK v1.0 (Historical Information)
This section describes the one test failure with the 1.0 version of the TCK. This section is being kept here for historical purposes, and because the 1.1 version of the TCK has not yet been officially released to the jcp.org website.
At the time of this writing (25-July-2004), Drools version 2.0 beta 16 successfully passes every test except one, the org.jcp.jsr94.tck.admin.RuleExecutionSetProviderTest.testRuleExecutionSetProvider() test.
The failure appears to be due to the way org.jcp.jsr94.tck.util.TestCaseUtil.getRuleExecutionSetDocumentElement() parses the Drools rule XML file.
Drools rule XML files rely on the use of XML namespaces. For example, a typical Drools rule XML file starts with:
<rule-set
xmlns="http://drools.org/rules"
xmlns:java="http://drools.org/semantics/java">
The XML namespaces provide information to Drools that is critical for its proper operation. Unfortunately, the DocumentBuilder created by TestCaseUtil.getRuleExecutionSetDocumentElement() is not XML namespace aware and therefore the created DOM Element produced from parsing the Drools XML file is missing that critical information.
A simple solution to this is to add the line "dbf.setNamespaceAware(true)" to the TestCaseUtil.getRuleExecutionSetDocumentElement() method immediately following the call to "DocumentBuilderFactory.newInstance()".
This information constitutes what the JSR-94 TCK PDF document calls a "challenge to the TCK", which it says must be submitted to the Maintenance Lead. The Drools development team is currently in communication with the JSR-94 Specification team to resolve this one remaining issue, which is all that currently prevents Drools from being considered as a fully compliant JSR-94 implementation.
