JSR95 (Activity Service) Technology Compatability Kit (TCK) User Guide


Table of Contents

How to install, configure and run the tests
Running the tests using the supplied test harness
Testing Requirements
Integration with the JavaTest harness
Test Framework description
Debugging test cases
Test Syntax
Appeals Process
JSR-095 Technology Compatibility Kit License Agreement

How to install, configure and run the tests

The test harness that is supplied as part of the TCK is intended to be executed on the Windows platform. This execution can be controlled by the supplied command batch (.bat) files. Alternatively, if the JavaTest test harness is available, the tests may be executed from this environment.

The TCK is packaged in a single zip file, jsr95_tck.zip. Unzip this file to a suitable directory. The contents of this file include:

readme.tck.txt
A text file containing basic instructions.
jsr95tck.html
This document.
jsr95test.html
Test specification document, describing each test and the specification assertions upon which they are based.
jsr95ut.jar
A jar file containing source java files and compiled class files for the test harness/framework in the com.ibm.activity.unittest and com.ibm.activity.hls packages.
jsr95bld_tck.bat
A command file that may be used to rebuild jsr95ut.jar.
setenv.bat
A configuration file for running or rebuilding the test harness.
runtest.bat
A utility test command file which executes a single test.
testone.bat
A utility test command file which executes a single test and logs the results.
runtests.bat
The main test command file which can be used to execute all or a series of tests.
testcase
A directory containing all of the individual test scripts which make up the TCK
testdesc.txt
The test description file used by the test harness.
testdesc.html
Test descriptions in JavaTest html format for use with JavaTest harness.

Running the tests using the supplied test harness

To execute the tests using the Reference Implementation as the Activity Service, edit the setenv.bat file to set the following environment variables:

See the comments in the setenv.bat for which other environment variables may also need to be set.
The tests can then be executed by running the runtests command file.

To execute the tests using an Activity service implementation other than the Reference Implementation, it is necessary to edit the setenv.bat command file further to indicate where the Activity service implementation can be found. Specifically:

  1. Remove the jsr95ri.jar from the CPATH environment variable, and replace it with the jars that contain the target implementation.
  2. Modify the ACTMGR and optionally ACTFACTORY environment variables to identify the name of the javax.activity.ActivityManager implementation class or factory. Use the ACTMGR environment variable if the ActivityManager implementation has a public, default constructor or else set the ACTFACTORY environment variable to point to a suitable factory class for the ActivityManager implementation. This class must also have a public, default constructor and must implement the getObjectInstance method which returns a suitable ActivityManager object.

The tests can then be executed by running the runtests command file.

Output from each test is placed in the logs directory, while test results are recorded in the results directory. For each test that is executed, the logs directory will contain two files corresponding to the standard output and error streams of the test. These files contain useful information when debugging failures or test errors. When runtests completes, a summary.htm file is produced which summarizes the test results.

Rebuilding the test harness

A command file, jsr95bld_tck.bat, is provided to rebuild jsr95ut.jar. Before running this command file you need to extract the contents of the jsr95ut.jar to the working directory. The JAVA_HOME and JAVAX_ACTIVITY environment variables need to be set appropriately in the setenv.bat command file as described above.

Testing Requirements

The following points must be observed during compatability testing:

  1. The TCK source is provided and licensed, under the terms described in the license agreement below in order to encourage broad distribution to interested parties. No TCK source/binary may be modified in order to falsely claim compatibility.
  2. All tests are required to pass in order to be compatible.

Integration with the JavaTest harness

While there is no requirement to do so, the tests provided in this TCK can be run using the JavaTest harness with a few small modifications. The com.ibm.activity.unittest.TestActivity class must be unpackaged from the jsr95ut.jar file and edited to provide the correct interface method for JavaTest to locate. This is the
public Status run (String[], PrintWriter, PrintWriter)
method. A suitable piece of code is provided in the TestActivity.java file, in commented-out form. Simply remove the comments and recompile the java file using a suitable CLASSPATH that includes the JavaTest code.

JavaTest uses a test description file(s) to identify which tests are available and the execution requirements of each test. A suitable file (testdesc.html) is provided with the TCK for this purpose.

Test Framework description

The JSR95 Activity Service provides a series of interfaces that are designed to be used by one or more High Level Services (HLS). In order to test out these interfaces, it is necessary for the test harness to provide the functionality of an HLS. This is achieved by creating the appropriate implementations of the relevant interfaces (eg ServiceManager, SignalSet etc). Clearly each individual test will need to use these implementations, so the test code provides implementations of these interfaces which are configurable and can thus be used in many tests.

The test harness goes one step further than this and provides a means of creating and configuring these objects via simple commands which can be read from a test script or entered interactively. This has a number of benefits,

  1. test case configurations are easy and quick to script
  2. the scripts encapsulate the test steps in a concise form which is easily understood without having to decipher lots of java code
  3. because the same classes are used from test to test, the test harness can be instrumented (eg with trace) to facilitate debugging of tests
  4. tests can be run interactively to aid in both the creation and debugging of test scenarios.
  5. because the same code is used in many tests, confidence in the correct functioning of the test code can be high.

As well as allowing for the configuration of these objects, the command syntax also deals with the calling of the relevant Activity Service interface methods, passing these objects where appropriate.

The syntax and function of the various commands is summarized below in Test Syntax and described in more detail in the javadoc for the corresponding do_xxx methods in the TestActivity class.

In order to determine the test outcome (ie pass or fail), a logging system is set up so that each interaction of the Activity Service with the various objects is logged together with return values from method calls. The information in the log can then be compared to expected results to determine the test outcome. Note that, in some cases, the order of events in the log can be important and a required feature of the test while in other circumstance the Activity Service may not be constrained as to the order that it performs tasks and, in these cases, the test results do not depend on the order of events in the log.

Debugging test cases

When a test fails, it may be necessary to investigate to understand whether there may be a test case error or to more accurately assess what the underlying Activity Servive failure is. The first step is to understand what the test is attempting to do and this can be achieved by referring to the test specification document for the appropriate test case number. The relevant assertion in the JSR95 specification can then be located and the purpose of the test gleaned.

This may be enough to indicate what the problem is. However, more detail of the execution of the test can be found in the log files created during test execution (in the logs directory). These contain a record of the commands executed during the test and also a trace of the execution flow through the test code. This trace shows the various parameters which are passed and returned and also indicates where execution is passed to the Activity Service. Using this trace, the expected sequence of operations and values of parameters can be confirmed or anomalies pinpointed.

The test execution can also be performed interactively using the runtest command file. Each step of the test can be entered manually and any results viewed. Trace can be turned on in this mode using the trace command. The contents of the test log can also be viewed using the dump command, so that possible sequencing problems can be detected.

The following section lists the various commands that are recognized by the test program. The list is provided as a further aid to understanding the details of the test scripts for debugging purposes.

Test Syntax

The syntax of the various configuration and method execution commands is given below. The command syntax is generally case insensitive however some identifiers, such as the pre-defined SignalSet and Signal names, are mixed case and should be entered enclosed in single or double quotes.

Object creation/configuration
signalset
signalset id outcome outcomestring

signalset id [signal signalname1 ...]

signalset id response outcomestring boolean boolean
Create a new SignalSet with the given id and outcome and optionally configure to produce specified signals and to accept specified Action responses.
propertygroupmanager propertygroupmanager id [method commandstring] Create a new PropertyGroupManager with the given id or else configue an existing PropertyGroupManager to create PropertyGroups which execute the given command string when the appropriate method is called.
action action id [signalname outcomestring]

action id signalname command commandstring

action id getfinaloutcome

action id getglobalid gid

action id getcompletionstatus
Create a new Action with the given id or else configure an existing Action. Actions can be configured to respond with a specified Outcome for a given Signal and/or to execute a given command string when a Signal is received. The various get... methods are used after the Action has received a pre-defined Signal to recover extra information that was encoded in the Signal.
thread thread id Creates and uses a new thread of execution with the given id or else switches execution to an existing thread. The main execution thread id is 'threadMain'
servicemanager servicemanger id [group name] Creates a new ServiceManager with the given id or else switches to an existing ServiceManager for subsequent commands. If a new ServiceManager is created but no ContextGroup is supplied, then the ServiceManager is not registered with the Activity Service. If a group name is specified then registration is attempted, whether the ServiceManager is new or not.
addpropertygroupmanager addpropertygroupmanager id [method commandstring] Adds (and optionally creates) the PropertyGroupManager with the given id/name to the current ServiceManager. Optionally the PropertyGroupManager is configured to create PropertyGroups which execute the given command string when the appropriate method is called. Activities which are subsequently created from the ServiceManager will support PropertyGroups of the given name (id).
addsignalset addsignalset id [true] Adds (and optionally creates) the SignalSet with te given id/name to the current ServiceManager. If 'true' is specified, then this SignalSet becomes the Completion SignalSet for the ServiceManager.

Logging test commands
Until any test commands have been executed, the test is deemed to be 'in error'. Subsequent test commands will set the state to 'passed' only if the test has not failed or been explicitly set to 'error'.
test test teststring Tests 'teststring' against the last String logged. If the Strings do not match, then the test status is set to failed. The last logged String is removed.
testnot testnot teststring Tests 'teststring' against the last String logged. If the Strings do match, then the test status is set to failed. The last logged String is removed.
testnotall testnotall teststring Tests 'teststring' against all Strings logged. If there are any matches, then the test status is set to failed. No logged Strings are removed.
testapplicable testapplicable teststring Tests 'teststring' against the last String logged. If the Strings do match, then the test status is set to Not Applicable and the test is abandonned. This provides a means of having conditional tests.
end end Explicitly ends the test. The current status of the test log is returned to the caller.
dump dump Dumps the current contents of the log to the output stream. Generally used for debugging purposes. Does not affect the contents of the log or test status.
trace trace Interactively turns on tracing of the components in the test harness. Trace output is written to the error stream.

Commands that drive interface methods
UserActivity
Commands that operate on the UserActivity and ActivityManager interfaces are routed through the current ServiceManager, which is the ServiceManager whose id was last selected via the servicemanager command.
activitycoordinator activitycoordinator id Calls the getCoordinator method of the UserActivity associated with the current ServiceManager. The returned ActivityCoordinator object is saved with the given id.
addaction addaction id signalsetid [priority] Calls the addAction method of the ActivityCoordinator associated with the current ServiceManager. If priority is not specified, it is set to 0.
addglobalaction addglobalaction id [priority] Calls the addGlobalAction method of the ActivityCoordinator associated with the current ServiceManager. If priority is not specified, it is set to 0.
begin begin [timeout] Calls the begin method of the UserActivity associated with the current ServiceManager. If timeout is not specified, it is set to -1
broadcast broadcast signalsetid Calls the broadcast method of the UserActivity associated with the current ServiceManager.
complete complete Calls the complete method of the UserActivity associated with the current ServiceManager.
completewithstatus completewithstatus completionstatus Calls the completeWithStatus method of the UserActivity associated with the current ServiceManager.
getcompletionstatus getcompletionstatus Calls the getCompletionStatus method of the UserActivity associated with the current ServiceManager.
getglobalid getglobalid id Calls the getGlobalId method of the UserActivity associated with the current ServiceManager.
getname getname id Calls the getName method of the UserActivity associated with the current ServiceManager.
getparentcoordinator getparentcoordinator id Calls the getParentCoordinator method of the UserActivity associated with the current ServiceManager.
getpropertygroup getpropertygroup id Calls the getPropertyGroup method of the UserActivity associated with the current ServiceManager.
getservice getservice id Calls the getService method of the UserActivity associated with the current ServiceManager.
getstatus getstatus Calls the getStatus method of the UserActivity associated with the current ServiceManager.
gettimeout gettimeout Calls the getTimeout method of the UserActivity associated with the current ServiceManager.
recreate recreate activity parent resume timeout id Calls the recreate method of the UserActivity associated with the current ServiceManager. The resulting ActivityCoordinator is saved with the given id.
removeaction removeaction id Calls the removeAction method of the ActivityCoordinator associated with the current ServiceManager.
removeglobalaction removeglobalaction id Calls the removeGlobalAction method of the ActivityCoordinator associated with the current ServiceManager.
setcompletionstatus setcompletionstatus completionstatus Calls the setCompletionStatus method of the UserActivity associated with the current ServiceManager.
settimeout settimeout timeout Calls the setTimeout method of the UserActivity associated with the current ServiceManager.

ActivityManager
suspend suspend tokenid Calls the suspend method of the ActivityManager associated with the current ServiceManager. The returned ActivityToken is saved with the id 'tokenid'
suspendall suspendall tokenid Calls the suspendAll method of the ActivityManager associated with the current ServiceManager. The returned ActivityToken is saved with the id 'tokenid'
suspendgroup suspendgroup tokenid Calls the suspendGroup method of the ActivityManager associated with the current ServiceManager. The returned ActivityToken is saved with the id 'tokenid'
resume resume tokenid Calls the resume method of the ActivityManager associated with the current ServiceManager.
resumeall resumeall tokenid Calls the resumeAll method of the ActivityManager associated with the current ServiceManager.
resumegroup resumegroup tokenid Calls the resumeGroup method of the ActivityManager associated with the current ServiceManager.

ActivityCoordinator
The following commands operate on the ActivityCoordinator id which must previously have been obtained via either the activitycoordinator, getparent or getparentcoordinator commands.
completeactivity completeactivity id completionstatus Calls the completeActivity method of the ActivityCoordinator with the given id.
heuristiccomplete heuristiccomplete id completionstatus Calls the heuristicComplete method of the ActivityCoordinator with the given id.
coordaddaction coordaddaction id actionid signalset [priority] Calls the addAction method of the ActivityCoordinator with the given id. If priority is not specified, it is set to 0.
coordaddglobalaction coordaddglobalaction id actionid [priority] Calls the addGlobalAction method of the ActivityCoordinator with the given id. If priority is not specified, it is set to 0.
coordgetname coordgetname id nameid Calls the getName method of the ActivityCoordinator with the given id.
coordgetstatus coordgetstatus id Calls the getStatus method of the ActivityCoordinator with the given id.
coordhibernate coordhibernate id {recdata} Calls the hibernate method of the ActivityCoordinator with the given id and optionally saves the returned RecreateData as recdata.
coordremoveaction coordremoveaction id actionid Calls the removeAction method of the ActivityCoordinator with the given id.
coordremoveglobalaction coordremoveglobalaction id actionid Calls the removeGlobalAction method of the ActivityCoordinator with the given id.
getactioncount getactioncount id Calls the getNumberRegisteredActions method of the ActivityCoordinator with the given id.
getparent getparent id parentid Calls the getParent method of the ActivityCoordinator with the given id.
getparentstatus getparentstatus id Calls the getParentStatus method of the ActivityCoordinator with the given id.
issameactivity issameactivity id1 id2 Calls the isSameActivity method of the ActivityCoordinator with the given id.
processsignalset processsignalset id signalset completionstatus Calls the processSignalSet method of the ActivityCoordinator with the given id.
setpersistent setpersistent id {recdata} Calls the setPersistent method of the ActivityCoordinator with the given id and optionally saves the returned RecreateData as recdata.

GlobalId / String
isequal isequal id1 id2 If id1 and id2 are both GlobalIds, then this command calls the isEqual method of the first GlobalId, passing the second as a parameter. If id1 and id2 are Strings, then this command calls the String.equals method.

Appeals Process

The Technology Compatability Kit is intended to provide a comprehensive set of tests to assess the compliance of Activity Service implementations to the JSR95 specification. While every care has been exercised in its design and construction, it is quite possible that there may be defects or omissions which may call into question the validity of tests. Examples of such problems include, but are not limited to

Should the validity of a test be called into question, the following process should be followed.

  1. Check on the website for latest updates to the TCK tests. Successful appeals will result in updates to the tests being made available, so ensure your challenge has not already been accepted and corrections published.
  2. If this is not the case, send a note to jsr-95-comments@jcp.org with the following details
  3. The appeal will be evaluated. During this time, further information or clarifications may be sought from the appellant.
  4. A decision should be reached and communicated to the appellant within 15 working days. This should include a full justification of why the challenge was either rejected or accepted
  5. If the challenge is accepted, then this may result in amendments to the test in question, or the test may be replaced or the test may be removed entirely depending upon the specific circumstances. Such amendments will be made generally available on the website, including details of the problem report.
  6. If the challenge is rejected and the appellant does not agree with the justification provided, then the appellant should work with the evaluation team to resolve the issues involved. As a last resort, the appeal may be escalated to the Executive Committee.

JSR-095 Technology Compatibility Kit License Agreement

BY DOWNLOADING OR USING THE SOFTWARE AND/OR DOCUMENTATION DESCRIBED IN EXHIBIT A HERETO (COLLECTIVELY THE "SOFTWARE"), YOU AGREE TO THE FOLLOWING TERMS AND CONDITIONS ("AGREEMENT"). IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS AGREEMENT, YOU MAY NOT DOWNLOAD OR USE THE SOFTWARE.

License Grant. You are hereby granted a personal, non-transferable and non-sublicenseable, nonexclusive, world-wide, royalty free license to use the JSR-095 Technology Compatibility Kit (including software and documentation) (the "TCK") solely for the purpose of testing compliance with the relevant portions of specifications or standards to which it applies (the "Specification"). You may not modify or create derivative works of any of the TCK except as is necessary to fulfill the purpose described above. You may not distribute copies of the TCK to other parties for any purpose, including for the purpose of allowing such other party to use the TCK. Nor may you modify or incorporate the TCK into any other software.  

No Warranties.  The TCK contained herein is provided on an "AS IS" basis and to the maximum extent permitted by applicable law, this material is provided AS IS AND WITH ALL FAULTS, and the developers of this material hereby disclaim all other warranties and conditions, either express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability or satisfactory quality, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses, and of lack of negligence. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THIS MATERIAL. Some jurisdictions do not allow the exclusion of such implied warranties, so the above may to that extent not apply to you.  

Limitation of Liability.  TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL ANY AUTHOR, DEVELOPER, LICENSOR, OR DISTRIBUTOR OF THIS MATERIAL BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, PUNITIVE, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS MATERIAL, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

Some jurisdictions do not allow the exclusion of implied warranties, or the limitation for consequential damages, so the above may not apply to you.  

Covenant Not to Assert.  As a material condition of this License, you hereby agree, to the extent that you have any patents which cover the use of the TCK in any manner permitted under this Agreement, not to assert, for the licensed use of the TCK, any such patent against any of the developers or distributors of the TCK or against any other party which has entered into a license substantially similar to this Agreement.  

Reciprocity.  You may now have, or may in the future have, the ability to license test suites developed or distributed pursuant to the Java Community Process ("Java Materials"). You acknowledge that under this License you are receiving the TCK under reasonable royalty-free terms. While you are not obligated to make Java Materials available, if you do so, you agree to license them under reasonable royalty-free terms. For the purpose of this paragraph, terms are not 'reasonable terms' if they are more restrictive than those of this License, or if they discriminate against any individual or group of JCP members or against any implementer of an independent implementation or an open source implementation. If you do make Java Materials available in the future and do not license such Java Materials under reasonable royalty-free terms, as consideration for licensing this TCK to you, you agree to pay IBM royalties as follows: (a) Fifty Thousand Dollars ($50,000) payable within forty-five (45) days of your distribution of such Java Materials; and (b) an additional Ten Thousand Dollars ($10,000) per year, starting in the year after your first year of distribution, for each year during which you use this TCK or use and/or distribute a product that has been tested for compliance with this TCK. In no event shall such royalties in the aggregate exceed Eighty Thousand Dollars ($80,000). In the event that you will pay IBM under this reciprocity clause, you agree to contact IBM's JSR Specification lead, who will instruct you whom you should contact to make arrangements to set up such royalty payments.  

Compatibility Claims.  You may not claim that any version or release of software passes the TCK, and therefore is compatible with the Specification, unless it is capable of passing the most current version of the TCK available one hundred and twenty (120) days prior to the date of its first shipment to customers. You will make available information regarding the version of the TCK passed, upon request. You agree that any claims regarding compliance with the Specification will be factually accurate and will not be misleading.  

Payment Terms. Subject to the receipt of a timely and correctly presented invoice from IBM, payments identified under the Reciprocity paragraph above shall be made within forty-five(45) days of your receipt of IBM's invoice.

General.

You agree to comply with all applicable export laws and regulations.

No other rights are granted by implication, estoppel or otherwise.  

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.  

Your rights under this Agreement shall terminate if you fail to comply with any of the material terms or conditions of this Agreement and do not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If your rights under this Agreement terminate, you agree to cease use of the TCK immediately and cease making any claims of compatibility regarding the Specification based on the use of the TCK.  

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights (if any) to a jury trial in any resulting litigation.

This Agreement is the only understanding and agreement we have with respect to the Software. It supersedes all other communications, understandings or agreements (oral or written) that we may have had with respect to the Software prior to this Agreement. Only a written agreement signed by both of us can modify this Agreement.

EXHIBIT A  

The "SOFTWARE" this Agreement applies to is the Java Specification Request (JSR) 095 for the Java Enterprise Edition Activity Service for Extended Transactions Technology Compatibility Kits (TCK).