Running the Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit

Running the Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit
v1.0

In this release of the Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit (LDJ Kit), there are three test sets used to verify that your service, client, or lookup service behaves as it is expected to behave. Note that a single LDJ Kit installation can test clients, services, and lookup services.

You may wish to run the tests individually first, so you can get a feel for how to interact with the command-line interface. However, you must successfully complete all of the tests for your program category, using the program com.sun.jini.compat.harness.Runner, for your service to be considered conformant. Passing the Jini Technology Lookup, Discovery, and Join Compatibility Kit gives details of the procedures necessary to verify compatibility.

The individual tests are documented in the Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit Test Descriptions.

This document contains instructions for setting up your environment to run the LDJ Kit tests, followed by two examples of running the kit.

Verify that your path environment variable is set up properly

Please ensure that the combination of operating system and Java(TM) 2 SDK, Standard Edition that you are using is one that we have tested. For a list of supported configurations, take a look at the platforms on which the LDJ Kit has been tested, listed at http://java.sun.com/developer/products/jini/tested.html.

Make sure that the Java 2 SDK executable files are accessible from your executable path environment variable. You can test to ensure that you have the correct version of the Java 2 SDK installed and that your executable path is set up properly by typing: 

	java -version

Ensure that you can run the Java RMI activation daemon, rmid

The LDJ Kit starts a lookup service which requires that the Java Remote Method Invocation (Java RMI) activation daemon be running. The RMI activation daemon needs to be started in the following way:

For example, on a UNIX platform using the Java 2 SDK v1.2.2-006 (or later), starting rmid as follows: 
	% cd /tmp
	% setenv CLASSPATH
	% rmid -J-Dsun.rmi.activation.execPolicy=none
causes rmid to enforce the same security policy as earlier versions of rmid. For earlier versions of 1.2.2, there is no need to set the property, -J-Dsun.rmi.activation.execPolicy=none.

To run rmid on Microsoft Windows platforms, using the Java 2 SDK v1.2.2-006 (or later), open a Command Prompt window, by using the "Start" button, and selecting "Programs" and then "Command Prompt". In that window: 

	C:\> cd C:\temp
	C:\> set CLASSPATH=
	C:\> start /min rmid -J-Dsun.rmi.activation.execPolicy=none
causes rmid to enforce the same security policy as earlier versions of rmid. For earlier versions of 1.2.2, there is no need to set the property, -J-Dsun.rmi.activation.execPolicy=none.

Start an HTTP server

You will need an HTTP server for your service. If you do not use an HTTP server to provide your downloadable JAR files to clients, you will fail at least one of the tests in the LDJ Kit. You can use the HTTP server provided with the Jini Technology Starter Kit (starter kit). Instructions on how to run it may be found in the starter kit.

It is important to note that the LDJ Kit test harness always starts an HTTP server on port 8080 for internal use. As a result, the HTTP server used to support class loading for the service under test must use a port other than 8080. The default HTTP port 80 is therefore available for use; however, in this document it will be assumed that all services use an HTTP server bound to port 8081.

Customize the LDJ Kit configuration file for your environment

The LDJ Kit configuration file contains property definitions that must be customized for your environment. Since none of the files provided with the LDJ Kit distribution should be modified directly, change directory to the LDJ Kit installation directory and copy the ldj.prop file to a new file name, for modification. This file name will be passed to the LDJ Kit command line later.

For example, on a UNIX platform where you have the LDJ Kit installed in /files/jinildj1_0/: 

       % cd /files
       % cp jinildj1_0/ldj.prop my.prop
Or on the Microsoft Windows platforms, where you have the LDJ Kit software installed in C:\files\jinildj1_0: 
       % cd C:\files
       % copy jinildj1_0\ldj.prop my.prop
There are two property values, specifying directory locations, that you must set in order for the LDJ Kit to run correctly. Other property values may also be necessary in certain situations. The LDJ Kit properties are: In addition to the above properties, Admins can define their own properties. The ldj.prop configuration file included in the LDJ Kit download contains commented-out property definitions for the example Admins contained in the LDJ Kit. These are for reference purposes only.

Example 1: Running a single test on a Jini technology-enabled service using DefaultServiceAdmin

This example will take you through the process of using the LDJ Kit to test the Jini technology-enabled transaction service (Mahalo) on a UNIX platform. This first test will probably take you ten to fifteen minutes to complete. Instructions on starting the activatable implementation of Mahalo using either JRMP or Jini extensible remote invocation (Jini ERI) for remote communication is available in the API documentation for the com.sun.jini.mahalo package in the Jini starter kit.

For this example, we assume that the Jini technology infrastructure software and documentation is available in the directory /files/jini2_1.

The DefaultServiceAdmin asks you to start and stop your service (Mahalo) for each test. Since the activatable implementation of Mahalo is being used and to ensure that the service is re-created rather than reactivated for each test, there will be a lot of manual stopping and restarting of rmid. To make the stopping and restarting easier, this example will require four shells or windows: one in which to run an http server for Mahalo, one in which to run rmid, one in which to run Mahalo, and one in which to run the LDJ Kit.

The general order of operations will be:

  1. Ensure that rmid is started as specified earlier
  2. Customize the LDJ Kit configuration file
  3. Start the test harness
  4. Start Mahalo when instructed by the test harness
Note: Each time that the test harness requests that you stop your service, you will need to perform these four steps before proceeding any further:

Customize the LDJ Kit configuration file

Copy the LDJ Kit configuration file to my.prop as specified earlier and set these properties:

The com.sun.jini.compat.installDir should accurately reflect the installation directory of the LDJ Kit on your system. The com.sun.jini.compat.scratchDir should be a location to which the LDJ Kit may write temporary files and log files. If the specified directory does not exist, then the directory will be created for you as part of the LDJ Kit run. Lowering the value of com.sun.jini.compat.unofficialQuietTime from its default 600000 milliseconds (10 minutes) to 60000 milliseconds (1 minute) will dramatically decrease the test time for this example run.

Start the test harness

Assuming that an http server for Mahalo and rmid are already running in two windows, start the test program in a third window. For complete instructions on starting the LDJ Kit, see the Command-line Usage for the Jini Technology Lookup, Discovery, and Join Compatibility Kit. Here's an example of how to start the test harness on a UNIX platform: The output should look like:

Start the service
At this point, start Mahalo in a fourth window. For an example of how to start the activatable implementation of Mahalo using either JRMP or Jini ERI for remote communication, see the API documentation for the com.sun.jini.mahalo package in the v2.1 starter kit.

Start testing

  1. Once Mahalo has started and registered with the activation system, you can return to the shell where the LDJ Kit is executing and press the "Enter" key. At this point, you should see a new message in that shell: 
    	Testing....
  2. The program pauses and asks you to select your service from the ones registered with the lookup service started by the LDJ Kit: 
    	Which of the following is the program being tested?
	  0) None of these
	  1) class com.sun.jini.compat.reggie.RegistrarProxy from codebase http://123.45.67.89:8080/compat-lus-dl.jar
	  2) class com.sun.jini.mahalo.TxnManagerImpl_Stub from http://myHostName:8081/mahalo-dl.jar
    Select the number of Mahalo, and press the "Enter" key: 
    	Select number and press Enter: 2
  3. You are then prompted to stop the program. Before you press the "Enter" key, you'll need to perform the sequence of "clean-up" activities, which we will go through next. 
    	Stop the program now.
	Press Enter when program stopped:
  4. In the window where you are running rmid, quit out of the process and remove the log directory: 
            % rmid
	^C
	% rm -rf log
  5. Remember to remove the log directory for Mahalo: 
    	% rm -rf /tmp/txn_log
  6. Return to the Runner window, press the "Return" or "Enter" key, and you'll see: 
    	Test Passed: OK

	--------------------------
    Congratulations! You've made it through one of the ten tests that a service must pass.

Example 2: Fully testing a Jini technology-enabled service using a custom admin

This example will take you through the process of using the LDJ Kit to test the Jini technology-enabled transaction service (Mahalo) on a UNIX platform. This unofficial run will probably take you less than 30 minutes to complete. Remember that for an official run of the LDJ Kit, you'll need to edit your config file, my.prop, to comment out the property com.sun.jini.compat.unofficialQuietTime. Because an official run would take about an hour to complete successfully, this example will continue to use a com.sun.jini.compat.unofficialQuietTime of 60000 milliseconds (1 minute).

By using one of the custom Admins provided with the LDJ Kit, you will avoid having to start and stop rmid and Mahalo for each of the ten tests. In addition, you will never have to execute the Mahalo command line, as the Admin will take care of registering Mahalo's activation descriptor with rmid.

Customize the LDJ Kit configuration file

First you will need to change several of the properties in the config file, so edit my.prop (created in the previous example) to define these property values:

The com.sun.jini.compat.admin2.* properties that are defined above are all documented in the ldj.prop file.

Start the test harness

Assuming that an http server for Mahalo is running (at port 8081) in one window and that rmid is running in a second window, start the test program in a third window. For complete instructions on starting the LDJ Kit, see the Command-line Usage for the Jini Technology Lookup, Discovery, and Join Compatibility Kit.

The Admin we are using, com.sun.jini.compat.admin2.ServiceStarterAdmin, is contained in the compat-admin2.jar within the LDJ Kit lib directory. This Admin requires that jsk-platform.jar, found in the Jini starter kit lib directory, also be included in the classpath. Here's an example of how to start the test harness on a UNIX platform:

The output will tell you that ten of the tests are applicable to the service being tested and that nine of the tests are just to test lookup services. The output may look a little disconcerting the first time you execute the command, but as long as it doesn't contain any errors that tell you it can't locate a class or a policy file, you should be in good shape. Without com.sun.jini.compat.debugLevel set to all, some tests may appear to be doing nothing. Be patient. Some tests will take many times the value specified by the com.sun.jini.compat.unofficialQuietTime property to execute.

A complete set of successful results will look like this:

Copyright 2005, Sun Microsystems, Inc.
Licensed under the Apache License, Version 2.0.