Jini(TM) Software Kit (JSK) Release Notes

JiniTM Software Kit (JSK) 1.0 Release Notes


The Jini Software Kit (JSK) provides implementations of the Lookup and Transaction Manager services specified in the Jini Technology Core Platform (JCP) as well as utility classes that are useful for writing new applications and services. The JSK software distribution consists of the com.sun.jini software, its API documentation, release notes for those classes and interfaces, examples, and references to the specific copyrights and licenses that protect each of the aforementioned components.

This document contains release notes for the Jini Software Kit API documentation, future directions that this software could take, and specifics on these packages:

If you have comments on the JSK, you can send email to jini-comments@java.sun.com. If you would like to submit a bug against the JSK, please send it to jini-submit@java.sun.com. If you encounter problems that you would like help with, you can subscribe to the jini-users list by sending email to listserv@java.sun.com, with a message of "subscribe jini-users".


Note on the API documentation

You may notice that the on-line API documentation (javadoc) was not produced for every class and interface in the com.sun.jini packages. This omission was intentional; we did not produce on-line API documentation for classes that were very implementation specific. We only produced on-line API documentation for the classes and interfaces that should be important to you, or that you may find useful. However, our implementation-specific classes and interfaces have javadoc comments, so that if you wish, you can produce the API docs yourself. Please let us know how you feel about this documentation approach by sending email to jini-comments@java.sun.com, with a subject of "API documentation".


Note on the com.sun.jini packages

The com.sun.jini package and its sub-packages contain our implementation of various Jini services. At present, all classes and interfaces in these packages are subject to change or removal in a future release, in ways that may not be backward compatible with this release.

We realize that there are administrative interfaces that you will need to depend on to effectively use Jini technology, and common tasks that Jini services and applications will have to perform that can be abstracted into utility classes. The following packages contain code specifically related to Jini technology that we invite you to review and provide feedback:

	com.sun.jini.admin
	com.sun.jini.discovery
	com.sun.jini.lease
	com.sun.jini.lease.landlord
	com.sun.jini.lookup
	com.sun.jini.lookup.entry

The classes that we believe have the broadest utility are:

	com.sun.jini.admin.DestroyAdmin
	com.sun.jini.lease.AbstractLease
	com.sun.jini.lease.AbstractLeaseMap
	com.sun.jini.lease.LeaseRenewalManager
	com.sun.jini.lookup.JoinManager
	com.sun.jini.lookup.entry.BasicServiceType

If you find a class, interface, or method that is particularly useful and you would like to see it included or enhanced in future releases, please send your suggestions to jini-comments@java.sun.com.


Note on com.sun.jini.lease

A general utility, com.sun.jini.lease.LeaseRenewalManager, has been provided to make it easy to renew leases.


Notes on com.sun.jini.reggie

"Reggie" is the name of Sun MicrosystemsTM first JiniTM Lookup service implementation. In the following discussion, we use the term "Reggie" to refer to Sun's Jini Lookup service implementation.

What's Important

It is strongly recommended that services in the Jini system use the general utility class, com.sun.jini.lookup.JoinManager, to participate in the Jini Discovery and Join protocols. This class encapsulates the proper behavior of a service that wishes to be a good "citizen" of the Jini Lookup service.

Starting Reggie from the command line

From the command-line, the syntax for starting up the lookup service would look like:

java -jar executable_jar_file
      codebase_arg  lookup_policy_file_arg   log_directory_arg

Where:

For example:

java -jar /files/jini1_0/lib/reggie.jar http://`hostname`:8080/reggie-dl.jar /files/jini1_0/example/lookup/policy /tmp/reggie_log

System properties

The following system properties control the behavior of Sun's implementation of the Jini Lookup service:

net.jini.discovery.announce
A Jini Lookup service will send out multicast packets announcing its existence every N milliseconds, where N is defined by this property. Currently, the default value of this property is 120,000 milliseconds (2 minutes).

com.sun.jini.reggie.unicastTimeout
When an instance of the current implementation of the Jini Lookup service uses the unicast request protocol to communicate with a client or service attempting to discover that lookup service, the socket connection used by the protocol will time out after N milliseconds, where N is defined by this property. Currently, the default value of this property is 60,000 milliseconds (1 minute).

com.sun.jini.reggie.proxy.debug
If set to any value, this property indicates that debugging information related to the execution of the lookup service's proxy should be printed to System.err. Set this property on clients if calls to the lookup service are unexpectedly returning null values for service objects, service types, attribute set classes, attribute sets, or attribute values.

Related system properties

The current implementation of Reggie participates in the Jini Discovery and Join protocols using the LookupDiscovery class. The operation of this class can be controlled by the system properties described in the JXP release notes.

Known Issues

Interaction with previous versions of the Jini Lookup service
The package name changes made between the 1.0 DC release and this release have made the two releases incompatible with each other. If the exception,
    java.lang.NoSuchMethodError: stub class initialization failed
is thrown by an application, along with a stack trace that ends with the method,
    net.jini.discovery.LookupDiscovery$UnicastDiscoverer.run(Compiled Code)
it means that your application is discovering a lookup service that was created using the 1.0 DC release. The solution is to terminate the old lookup service and create a new one to replace it.

SolsticeTM Network ClientTM on NT
If SolsticeTM Network ClientTM is installed on a Windows NT machine, and if NIS is selected as the primary name service, spurious UnknownHostException errors may occur in the RMI subsystem. These spurious errors are due to network timeouts. These errors cause the RMI subsystem to enable its multiplexed mode of operation; producing the following warning on the console (System.out):

*** RMI unable to listen on socket: using multiplexed connections instead ***

Note that the above condition does not result in system failure; only a slight degradation in performance.

To work around this problem, do the following:

Changes Since Beta

The com.sun.jini.reggie.proxy.debug property was added. See the property description above for more detail.

Notes on com.sun.jini.mahalo

"Mahalo" is the name of Sun MicrosystemsTM first JiniTM Transaction implementation. In the following discussion, we use the term "Mahalo" to refer to Sun's Jini Transaction implementation.

Mahalo was designed to run as a service within a Jini system or standalone. For this reason, Mahalo includes classes necessary for running in the Jini system environment. General information on the Jini technology may be found in the Jini technology release notes.

What's Important

Jar File Structure

To facilitate code downloading to clients, the Mahalo implementation is separated into two jar files.

Features

Mahalo Limitations

System Properties

Several system properties control Mahalo's behavior:
com.sun.jini.use.registry
If the com.sun.jini.use.registry property is set to a non-null value, the service will bind itself into the RMI registry. This property must be set on the VM that is creating the service. It is only used when creating a service from the command line. This property has no effect on how the service binds itself into Jini Lookup servers.

Note: Currently Mahalo can be configured to bind itself into an RMI registry or a Jini Lookup service. Support for binding into an RMI registry is being provided so developers can incorporate Jini technology into their systems incrementally instead of all at once. It is quite likely that we will remove support for binding into an RMI registry in future versions of Mahalo.

com.sun.jini.rmiRegistryPort
If the RMI registry is being used, this property can be used to set the port on which the service will look for the registry. This property must be set on the VM that is creating the Mahalo service. It is only used when creating a service from the command line.

com.sun.jini.mahalo.managerName
The com.sun.jini.mahalo.managerName property defines the name associated with the transaction manager. If the transaction manager is bound to the RMI registry, then the value of the managerName property is the name to which it is bound. If the transaction manager is bound to the Jini Lookup service, this name is used to create an attribute of type net.jini.lookup.entry.Name which is associated with the transaction manager's ServiceItem. This property must be set on the VM that is creating the service. It is only used when creating a Mahalo service from the command line.

java.security.policy
When using Mahalo, the java.security.policy property defines the path to the security policy file for the program that sets up the transaction manager. The security policy for transaction manager's VM should be specified by the second command-line argument to Mahalo.

java.rmi.server.codebase
When using Mahalo, the java.rmi.server.codebase property determines the URL that clients will use to load the classes of objects they get from the transaction manager. This URL is set by the first required command-line argument.

Known Bugs


Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.