Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit
Frequently Asked Questions
v1.0

OVERVIEW

RUNNING THE LDJ KIT

LDJ KIT ADMINS

COMMON PROBLEMS

TROUBLESHOOTING

OVERVIEW

What is the Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit?

The Jini(TM) Technology Lookup, Discovery, and Join Compatibility Kit (LDJ Kit) is a set of free conformance tests, a test harness, and associated documentation, produced by Sun Microsystems, Inc.

The purpose of compatibility testing is to ensure that programs are good citizens in the environment of Jini technology-enabled services and/or devices (good lookup citizens). To be a good lookup citizen, a program must interoperate with other good lookup citizens and behave in a way that doesn't cause trouble for the rest of the networks, such as swamping a network with too much traffic. The rules of good citizenship are detailed in the Jini technology specifications and are, to a lesser extent, codified in the LDJ Kit.

This kit may not be used to fulfill any compliance requirements for code licensed under the Sun Community Source License v3.0/Jini Technology Specific Attachment v1.0 (SCSL3/Jini TSA 1.0).

Why should I use the LDJ Kit to test my program?

The LDJ Kit is a free test suite that helps to ensure that your Jini technology-enabled client, service, or lookup service (hereafter referred to as "program") conforms with some very basic, but critical, Jini specification requirements. For more information on specifications covered by individual tests, see the Jini Technology Lookup, Discovery, and Join Compatibility Kit Test Descriptions document found in the LDJ Kit download.

This kit may not be used to fulfill any compliance requirements for code licensed under the Sun Community Source License v3.0/Jini Technology Specific Attachment v1.0 (SCSL3/Jini TSA 1.0).

How can I get the LDJ Kit?

The LDJ Kit is freely available from http://starterkit.jini.org.

RUNNING THE LDJ KIT

Which version of the LDJ Kit should I use?

You should use the latest LDJ Kit available at the download site listed above.

Which JDK and operating system should I use to test my program?

While you may use Java(TM) 2 SDK, v1.2.2 or later on any operating system configuration, we recommend that you use a platform on which the LDJ Kit has been tested if you encounter problems. These tested platforms are listed at http://java.sun.com/developer/products/jini/tested.html.

Which LDJ Kit tests (or test categories) should I run?

You should run all the tests in all the categories that apply to your program. For example, if your program is a Jini technology-enabled service (Jini service) that also acts as a Jini technology-enabled client (Jini client), then you should run both the client and service tests against your program. If your program is a Jini lookup service that also acts as a Jini service (registers in other lookups), then you should run both the service and lookup tests against your program. The tests contained in each category are:
service
com.sun.jini.compat.test.RequestPacketTest
com.sun.jini.compat.test.UnicastRequestTest
com.sun.jini.compat.test.CodeDownloadTest
com.sun.jini.compat.test.AnnouncementResponseTest
com.sun.jini.compat.test.RegistrationTest
com.sun.jini.compat.test.MultipleRegistrationTest
com.sun.jini.compat.test.PublicGroupTest
com.sun.jini.compat.test.NonPublicGroupTest
com.sun.jini.compat.test.MultipleGroupTest
com.sun.jini.compat.test.LeaseTest
client
com.sun.jini.compat.test.RequestPacketTest
com.sun.jini.compat.test.UnicastRequestTest
com.sun.jini.compat.test.CodeDownloadTest
lookup
com.sun.jini.compat.test.LookupByServiceIDTest
com.sun.jini.compat.test.LookupByClassTest
com.sun.jini.compat.test.LookupBySuperClassTest
com.sun.jini.compat.test.LookupByInterfaceTest
com.sun.jini.compat.test.MultipleServiceLeaseRenewalTest
com.sun.jini.compat.test.ServiceLeaseExpirationTest
com.sun.jini.compat.test.ServiceIDTest
com.sun.jini.compat.test.MultipleEventLeaseRenewalTest
com.sun.jini.compat.test.EventLeaseExpirationTest

On which platforms should I run the LDJ Kit?

You should run the LDJ Kit on at least one platform that supports Java 2 SDK, v1.2.2 or later. Which platform you use is entirely your choice.

Under which configurations should I start my program when running the LDJ Kit tests?

To pass the LDJ Kit tests, Jini clients, services, and lookup services must be able to abide by the LDJ Kit good citizenship requirements, such as discovering and joining only lookup services in the "public" group. It is not required that every possible configuration be capable of passing the LDJ Kit, nor is it required that your program's default configuration be capable of passing; it is simply required that at least one configuration be capable of passing. If your service implementation uses the net.jini.lookup.JoinManager to handle Jini discovery and join functions, this requirement of the LDJ Kit should be easily met.

What is an "official run" of the LDJ Kit?

An official run of the LDJ Kit is a single execution of the LDJ Kit test suite that meets certain requirements. These requirements are described in Passing the Jini Technology Lookup, Discovery, and Join Compatibility Kit, Section 2.1, found in the LDJ Kit download.

How long does it take to run the LDJ Kit?

A successful official run of the three LDJ Kit client tests should take approximately five minutes. A successful official run of the ten LDJ Kit service tests should take approximately one hour. A successful official run of the nine LDJ Kit lookup tests should take approximately 30 minutes.

How can I shorten these test times for experimental and debugging purposes?

The LDJ Kit configuration file contains a commented-out property, com.sun.jini.compat.unofficialQuietTime, that can be used to reduce the wait time used by most tests. For an official run, the default value of 600000 milliseconds (10 minutes) or greater must be used for this property. However, for purposes of experimentation and debugging, you can reduce this to something smaller, such as 60000 milliseconds (one minute). Once you have resolved any problems, you must comment out this property to perform an official LDJ Kit run. This property is further documented in the LDJ Kit test descriptions and property file.

How can I automate LDJ Kit testing for my program?

To automate the LDJ Kit testing for your program, you must implement your own specialized Admin object. See the next section of this FAQ for more information on how to implement your own Admin.

LDJ KIT ADMINS

What is an "Admin"?

An "Admin" is an object that is responsible for starting and stopping the program you are testing. The LDJ Kit comes with three default Admins (one each for clients, services, and lookup services), which simply ask you to start and stop your program at the appropriate times determined by each test.

Can I implement my own Admin object?

Yes! In fact it may be necessary to implement your own Admin in certain circumstances where the supplied default Admins do not work for your program. In addition, if you wish to automate LDJ Kit testing of your program, you will need to implement your own, specialized Admin object to start and stop your program automatically. To help you get started, the LDJ Kit download includes, as examples, the Admins used to automatically test the services found in the Jini(TM) Technology Starter Kit, v1.2.1_001 and v2.1. See the API docs and source files for the com.sun.jini.compat.admin1 and com.sun.jini.compat.admin2 packages in the LDJ Kit download.

How do I implement my own Admin object?

See Implementing the Jini Technology Lookup, Discovery, and Join Compatibility Kit, v1.0 Admin Interface, found in the LDJ Kit download.

COMMON PROBLEMS

What are some things to watch out for when running the LDJ Kit?

TROUBLESHOOTING

The following questions and answers assume that you are familiar with the LDJ Kit test designs in the Jini Technology Lookup, Discovery, and Join Compatibility Kit Test Descriptions document found in the LDJ Kit download.

Why do I fail (or get a NullPointerException) when I run the RegistrationTest or the MultipleRegistrationTest?

possible cause
Service packaging problem
detail
If the service being tested specifies an attribute in the entry registered with the lookup service but the service's codebase does not include the attribute class, then the LDJ Kit will fail to download the attribute class.
solution
In general, the service's downloadable JAR files should contain ALL classes that a client might require because the service provider has no control over the CLASSPATH used by the service's client (in this case the LDJ Kit).

My service doesn't appear to register with the LDJ Kit lookup (or when I use the DefaultServiceAdmin, my service is not in the list displayed by the LDJ Kit)

possible cause
The java.rmi.server.codebase property value that you specified for your service is incorrect.
detail
The DefaultServiceAdmin of the LDJ Kit is acting like a Jini client, and as such is trying to obtain the proxy for the service you are testing from the LDJ Kit lookup service. In order to do so, the LDJ Kit must have access to your service's classes.
solution
To verify that this is the problem, pass the property -Dcom.sun.jini.compat.reggie.proxy.debug=true to the LDJ Kit VM (you may also find the -Dnet.jini.discovery.debug=true helpful). If the codebase is the problem, you will see one or more exceptions that should help you determine the problem.

Why am I failing a LDJ Kit test with "java.io.IOException: Could not create directory" or "java.io.IOException: The filename, directory name, or volume label syntax is incorrect"?

possible cause
The path you specified for the LDJ Kit property com.sun.jini.compat.scratchDir is the wrong format for the operating system on which you are testing or you do not have permission to write to the specified directory.
solution
Make sure that the directory you specified in the configuration file as the value of the com.sun.jini.compat.scratchDir is in the correct format for the operating system on which you are testing and that you have permission to write to the specified directory.

Why am I failing the PublicGroupTest?

possible cause
Your service is not registering with the "public" lookup service group.
detail
Jini(TM) Discovery & Join Specification, Section DJ.1.4.1, says the service "should" default to using the "public" group. The LDJ Kit was designed to verify that Jini services act as 'good citizens', and one of our decisions about what makes up a good citizen is that the service must be capable of joining the "public" group. The PublicGroupTest is the test that verifies this behavior.
solution
To pass this test, you must make it possible to configure your service and clients to perform multicast discovery for at least the "public" group.

Why am I failing the NonPublicGroupTest?

possible cause
Your service registers in ALL_GROUPS.
detail
The test is designed to check for this behavior because your service should NOT register in ALL_GROUPS.
solution
Modify your service to not register with ALL_GROUPS.

possible cause
An identical service that registers in ALL_GROUPS is running on the network. You selected that service from the list displayed by the LDJ Kit's DefaultServiceAdmin.
detail
The LDJ Kit lookup service will allow registrations from any service on the network that specifies the group to which the lookup service belongs. Thus, a service that registers with ALL_GROUPS will always register in the LDJ Kit lookup service. It could be possible that an identical service to the one you are testing is running on the network and is registering with the LDJ Kit lookup service by joining ALL_GROUPS.
solution
Be very careful to select the service that you are testing or "None of the above" from the list displayed by the LDJ Kit's DefaultServiceAdmin. The class annotation of your service's proxy is included in the list and should help you determine which service is the one you are testing. The annotation will contain the IP address or name of the machine where you started your HTTP server for your service's downloadable code.

possible cause
When using the LDJ Kit's DefaultServiceAdmin, you inadvertently selected a service that is not the one you are testing from the pick list instead of "None of the above."
detail
For a well-behaved Jini service, the service should not join the LDJ Kit lookup service started by this test. Therefore, if the service you are testing is well-behaved, it should not appear in the list displayed by the LDJ Kit's DefaultServiceAdmin. So, in this case, you should select "None of the above" from the list.
solution
If the service you are testing doesn't appear in the list, select "None of the above".

possible cause
Your service uses a lookup locator that discovers the lookup service on the default port on the local host.
detail
In this configuration, locator discovery will find the LDJ Kit lookup service, even though it belongs to a randomly named group.
solution
Change your service so that the use of the hardcoded lookup locator is configurable and can be turned off for LDJ Kit testing. Alternatively, run the service on a different host than you run the LDJ Kit. The LDJ Kit config file provides the com.sun.jini.compat.defaultAdmin.address property, which can be set to support this.

My service uses a dynamic proxy and I'm using the LDJ Kit's DefaultServiceAdmin. When I'm presented with the list of services, how do I know which one is mine?

The DefaultServiceAdmin constructs each list element using the string form of the proxy's class name and the proxy's class annotation. The dynamic proxy's class name probably starts with $Proxy and careful examination of the class annotation should help you determine which service is the one you are testing.

Why is my service failing the com.sun.jini.compat.test.CodeDownloadTest?

possible cause
Service started in LDJ Kit's VM
detail
The LDJ Kit starts a lookup service in another VM and downloads the lookup service proxy JAR file when it unmarshals the proxy. If you are using a custom Admin for the service being tested and your Admin starts your service in the same VM as the LDJ Kit, then your service won't download the lookup service proxy JAR file again (since it is already cached in the VM). Thus your service fails the test.
solution
Custom Admins must not start services in the same VM as the LDJ Kit.
Copyright 2005, Sun Microsystems, Inc.
Licensed under the Apache License, Version 2.0.