JavaSpaces^TM Technology Kit (JSTK) 1.0 Eval Release Notes

This document contains release notes for the JavaSpaces Technology Kit installation, and specifics on the software in the com.sun.jini.outrigger package.

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

The current packaging of the JSTK requires that the Jini software be installed before the JSTK. The software packages build upon one another so the Jini software needs to be installed for the JSTK to work. If the Jini software and JSTK have been installed, but in the incorrect order, the API documentation will be incomplete, as may be the ./index.html file. For the complete installation instructions, click here.

When Should I Use Each Implementation?
If the application requires data to be retained across crashes or restarts of the space, FrontEndSpace should be used; if not, TransientSpace may be used. TransientSpace is slightly faster and is less complex to set up.

What's Important

Jar File Structure

To facilitate code downloading to clients, the Outrigger 1.0 Eval classes have been separated into three jar files; outrigger.jar and transient-outrigger.jar are both for the use of the JavaSpaces service, while outrigger-dl.jar is downloaded from the server for use by the client.

• outrigger.jar
  This jar file contains all of the class files FrontEndSpace needs to run, and should be in the bootclasspath of the VM in which it is running. However, when creating a FrontEndSpace from the command line (as opposed to creating one programmatically) you won't need to explicitly use the -Xbootclasspath option of the java command. This file has been configured to be an "executable jar file". When used with the -jar command-line option provided by some Java^TM VM implementations, it will start up a FrontEndSpace. For information on the -jar and -Xbootclasspath options to the java command, you can take a look at http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/java.html and http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/java.html.

• outrigger-dl.jar
  This jar file contains all of the class files that a client of an Outrigger service will need to communicate with the server. The java.rmi.server.codebase property of an Outrigger server should be a URL that points to this file. If the codebase property has been set correctly, this file does not have to be in the CLASSPATH of the client. This setup allows the client to be deployed in such a way that it is not dependent on any particular JavaSpaces service implementation.

• transient-outrigger.jar
  This jar file contains all of the class files TransientSpace needs to run and should be in the CLASSPATH of the VM in which that service is running. This file has been configured to be an "executable jar file". When used with the -jar command-line option provided by some Java VM implementations, it will start up a TransientSpace.

System Properties

Several system properties control the behavior of Outrigger:

java.security.policy

When using a TransientSpace, the java.security.policy property defines the path to the security policy file for the server. When using FrontEndSpace, the java.security.policy property defines the path to the security policy file for the program that sets up the server. In the case of FrontEndSpace, the security policy file for the VM in which the service is actually running is specified by the second required command-line argument.

java.rmi.server.codebase

When using TransientSpace, the java.rmi.server.codebase property determines the URL that clients will use to load the classes of objects they get from the space. When using FrontEndSpace, the codebase of the VM in which the service is running is set by the first required command-line argument.

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 to RMI registry. This property must be set on the VM that is creating the service. It is used only when creating a service from the command line, as opposed to creating the service programmatically. This property has no effect on how the service binds itself to Jini Lookup services.

Note: Currently Outrigger can be configured to bind itself to an RMI registry or a Jini Lookup service. Support for binding to 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 to an RMI registry in future versions of Outrigger.

com.sun.jini.rmiRegistryPort

If the RMI registry is being used, this property can assign the port on which the service will look for the registry (1099 is used if this property is not set). It is used only when creating a service from the command line, as opposed to creating the service programmatically.

com.sun.jini.outrigger.spaceName

The com.sun.jini.outrigger.spaceName property defines the name associated with the space. If the space is bound to the RMI registry, then the value of the spaceName property is the name to which it is bound. If the space is bound to the Jini Lookup service, this name is used to create an attribute of type net.jini.lookup.entry.Name that is associated with the space's ServiceItem. It is used only when creating a service from the command line, as opposed to creating the service programmatically.

com.sun.jini.outrigger.backend.vm.options

This property allows extra VM command line arguments to be passed to the back-end process associated with a FrontEndSpace. It must be set on the VM in which the FrontEndSpace is running. The value of this property should be a string that can be passed as an argument to the VM in which the back-end is running.

com.sun.jini.outrigger.java

This property specifies which java executable is used to spawn the VM in which the back-end process runs. The value of this property must be the name of a java executable, including its full path. The named program must be able to accept multiple -Dpropname=value options (as documented for the Solaris^TM operating system and Win32 versions of the java command) and the -Xbootclasspath: option. If this property is not set, a default value of "java" is used.

com.sun.jini.outrigger.backend.gcInterval

This property controls how aggressive the FrontEndSpace will be when garbage collecting the persistent store. The FrontEndSpace writes directives into logs that are consumed by a back end. This property is set to an integer which represents how many logs must be consumed before the persistent store is garbage collected. Once set to an integer, N, the persistent store is garbage collected by the back end every N logs. If not specified, a default value of 5 is used. This property must be set on the VM in which the back-end process is running

Known Bugs

• Multiple Outrigger instances cannot be started in the same Java^TM virtual machine (JVM)

  Currently, Outrigger is structured so that there can be only one instance running in a JVM.

• The com.sun.jini.mahout.binder.LookupBinder destroy method throws a NullPointerException

  In some cases, destroying an Outrigger server may generate a NullPointerException. This exception will cause a message to be written to the server's System.err but otherwise should not affect the efficacy of the destruction process.

• Blocking reads and takes sometimes take longer than they should

  If a blocking read or take operation occurs under the following three conditions, that operation may not return until the timeout expires, even if a matching entry appears in the space earlier:

  • If the operation is started while the space is being (re)started AND
  • If the timeout for the operation is not significantly longer than the time it takes the space to (re)start AND
  • If there is currently no matching entry in the space

  If a matching entry is still in the space when the timeout expires, the appropriate entry will be returned.

• Outrigger will sometimes drop event notifications

  A race condition in the code that sends event notifications will sometimes cause event notifications to be lost. Initial testing indicates that this happens infrequently. The event registration is not affected by this bug so future event notifications should be sent.

Requests For Enhancement (RFE)

• Outrigger should provide greater user feedback

  Currently, Outrigger provides minimal user feedback as to the success or failure of its initialization procedure. This lack of feedback is especially disconcerting with FrontEndSpace, because the program run by the user exits after setting up the space. Often the user does not expect this to happen.

• The class com.sun.jini.outrigger.BackEndSpace should be an activatable object

  The current FrontEndSpace implementation "manually" starts the corresponding BackEndSpace, as required. The BackEndSpace should instead be an activatable object that can be started by using RMI activation.

  This change would provide the following advantages:

  Isolation

  FrontEndSpace and BackEndSpace internals are hidden from each other. Any required communications could be handled by making RMI calls.

  Location transparency

  FrontEndSpace and BackEndSpace could potentially locate each other's process on different machines (provided the ability to share a common file system).

  Reliability

  BackEndSpace could continue log processing if the FrontEndSpace crashed.

  Simplification of FrontEndSpace

  FrontEndSpace would no longer have to know how to spawn a subprocess

  Flexibility

  Users would have more control over the environment in which the back-end process runs.

Known Issues

• The back-end process associated with FrontEndSpace does not always terminate immediately when the front end does

  When Outrigger is runing on the Solaris operating system this does not cause any additional problems.

  When the service is running on Windows NT, clients that attempt to call the service after the front end process dies will block until the back end dies, at which point they will get a RemoteException. Once the back-end process dies, the next call to the space will restart the service.

Changes from the JavaSpaces Technology 1.0Beta Release

Significant changes from Beta:

• Removal of PersistentSpace
  In the beta release there was a second persistent JavaSpaces service named PersistentSpace. This implementation was significantly slower than FrontEndSpace and offered no significant advantage. As a result, distribution and support of the implementation has been discontinued.

• Changes to the administration interface
  Outrigger's administration interface com.sun.jini.outrigger.JavaSpaceAdmin (obtained by casting the proxy to net.jini.admin.Administrable and calling getAdmin()) no longer implements com.sun.jini.outrigger.ShutDownAdmin.

  JavaSpaceAdmin has been extended to implement com.sun.jini.mahout.RegistryAdmin. This interface allows clients to make the service responsible for binding itself to an RMI registry on the service's machine, even after restarts if the service is persistent.

  Note: Currently Outrigger can be configured to bind itself to an RMI registry or a Jini Lookup service. Support for binding to 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 to an RMI registry in future versions of Outrigger.

• Outrigger servers can now be bound to RMI registry and Jini Lookup services simultaneously
  Prior to this release of Outrigger, a single Outrigger server instance could either be registered with Jini Lookup services or an RMI registry. With this release, that restriction has been removed. Additionally, the decision of which one(s) to use can be deferred until after service creation (though at least one has to be used at startup if you are using the command line for service creation).

  Binding to Jini Lookup services can be disabled by setting the lookup group and lookup locator lists to the empty list. Binding to Jini Lookup services can be enabled by setting either or both lists to be non-empty. The group list can be set by the optional group list command-line argument. The lookup locator list starts empty and cannot be set from the command line.

  Binding to an RMI registry can be enabled through the com.sun.jini.mahout.RegistryAdmin interface implemented by JavaSpaceAdmin. Once enabled it can not be disabled. From the command line, binding to the registry can be enabled by setting the com.sun.jini.use.registry property described earlier.

  As part of this change the com.sun.jini.binder property has been removed.

• Changes to Outrigger Command Line
  The command line arguments to FrontEndSpace are now:

  <codebase> <policy_file> <persistence_path> [group list] [JVM path] [JVM option]*

  The policy_file, persistence_path, JVM path, JVM option arguments are the same as they were in the beta release.

  The codebase was where both the service and the client could download the service's code. Now it is a URL from which clients can download the necessary code for interacting with the service. If using the provided jar files, the value of this argument should point to the outrigger-dl.jar file. The bootclasspath for the service is now set to be the same as the CLASSPATH of the VM that created the service.

  The group list argument is a new optional argument specifying which Jini Lookup service groups the service should join when it is first started (these groups can be changed through the net.jini.admin.JoinAdmin interface implemented by the service's admin proxy). The value of this argument must be one or more strings separated by commas or white space. If there is any white space in the list, the entire list must be enclosed in double quotes. The string "public" will be converted to "" (the empty string). If no group list is provided, it will default to the single entry list {""}. Initially, if the list consists only the string, "none", the service will be set up to not be bound into any groups. If "none" is used, then the com.sun.jini.use.registry property must be set to a non-null value.

  It is no longer necessary to explicitly use the -Xbootclasspath/p: argument to start a FrontEndSpace server from the command line.

  TransientSpace now takes one optional command-line argument: a "group list" of the form described above.

  For examples of how to run Outrigger servers from the command line, take a look at Starting Services, referenced by the JSTK examples page.

• Creation Interface Changes
  There are now two steps to create an Outrigger service programmatically (as opposed to from the command line or an exec() call):
  1. Create the service using one of the static create methods.
  2. Configure the service using its admin interfaces (including deciding to which directory services the service should bind itself).

  FrontEndSpace has two creation methods. They both return a reference to an activatable net.jini.space.JavaSpace instance. One method creates the service and a new activation group based on a passed com.sun.jini.mahout.PersistentServiceDesc object and places the service in that group. The other create method places the service in the activation group that was passed as a parameter. It also takes a location of a directory where the service should persist its data.

  TransientSpace has a create method that takes no arguments and returns a remote net.jini.space.JavaSpace object that resides in the method caller's VM.

  After invoking one of the create methods, the method caller will have a reference to an unconfigured Outrigger service. In particular, the service will not be set to bind itself to a directory service. The caller can either:

  • Use the service's admin to bind the service to Jini Lookup and/or RMI registry server(s)
    or
  • Take responsibility for binding the service to one or more directory services of its choosing

  • Changes to com.sun.jini.outrigger.AdminIterator
    Outrigger's AdminIterator interface was changed to have more in common with traditional iterators and to resolve some ambiguities in the previous interface. The new iterator returns only a single entry at a time, instead of an array, and can only delete the last entry returned, instead of any entry return by the last next() call. The iterator also makes stronger idempotency guarantees in the face of RemoteExceptions.

  • The Entry interface was removed from the JavaSpaces ^TM Technology Specification
    The Entry interface was moved out of the net.jini.space package into net.jini.core.entry. Alos, two new specifications were added to the Jini specification bundle, the Jini Entry Specification, and the Jini Entry Utilities Specification.

  • Other changes to the JavaSpaces^TM Technology Specification
    Please see section 1.8 of the 1.0 revision of the JavaSpaces Technology Specification for changes in the specification since beta. All these changes are implemented in this release of Outrigger.

  • Changes to the documentation
    The "HelloWorld" tutorial was removed from this version of the JSTK, but will be available later, unbundled from the JSTK.

  ---

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