# Outrigger
v2.0_002 Release Notes

### Description

"Outrigger" is the name of the contributed JavaSpaces(TM) service from Sun Microsystems. The JavaSpaces(TM) Service Specification is available in html.

The specification for Outrigger is defined not only by the JavaSpaces(TM) Service Specification but also by the API documentation (generated by the Javadoc(TM) tool) for `com.sun.jini.outrigger.AdminIterator` and `com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin`.

### Changes since the v1.2.X release

Configuration, Constraints, and Security
  This release supports the new `net.jini.config` configuration model. A number of aspects of Outrigger that were previously controlled by properties are now controlled by configuration entries:

  Property Name (no longer consulted) | Configuration Entry Name
  --- | ---
  `com.sun.jini.outrigger.backend.gcInterval` | `gcInterval`
  `com.sun.jini.outrigger.basicspace.reapingInterval` | `reapingInterval`
  `com.sun.jini.outrigger.defaultEventLease` | `eventLeasePolicy`
  `com.sun.jini.outrigger.maxEventLease` | `eventLeasePolicy`
  `com.sun.jini.outrigger.maxOps` | `maxOps`
  `com.sun.jini.outrigger.spaceName` | `initialLookupAttributes`

  There are also a number of properties where the associated functionally has either been superseded or changed to be controlled by a different mechanism:

  `com.sun.jini.outrigger.debug`
    This property is no longer consulted; instead all logging is done using the `java.util.logging` APIs. Consult Outrigger's package documentation for details on the loggers and logging levels used.
  `com.sun.jini.outrigger.maxProbeInterval`
    This property controlled a detail of the old blocking query protocol and is no longer consulted.
  `com.sun.jini.outrigger.backend.vm.options` and `com.sun.jini.outrigger.java`
    These properties controlled details of the old persistence layer and are no longer consulted.

  Most items that were previously controlled by command-line arguments are now controlled by configuration entries. The initial groups and locators to join are now controlled by the `initialLookupGroups` and `initialLookupLocators` configuration entries. The name of the persistence directory is controlled by the `persistenceDirectory` configuration entry. The codebase, classpath, and security policy file are all specified by the configuration that is passed to the Jini(TM) Technology Starter Kit (starter kit) service launcher `com.sun.jini.start`.

  This release also supports the new `net.jini.core.constraint` model. When Outrigger is configured to use a Java(TM) remote method invocation (Java RMI) implementation that supports constraints (e.g. Jini extensible method invocation), all of its proxies will support constraints. Most will do this by implementing `MethodConstraints`, but the proxies for iterators will do so by allowing constraints to be specified at the time the iterator is created.

  Certain configurations of Outrigger will support integrity, confidentiality, authentication, and access control on calls to the Outrigger server. This version of Outrigger also supports:

  - Verification of Outrigger's proxies through the proxy trust mechanism,
  - Deployer-defined preparation of the various proxy objects Outrigger's server encounters :
    - `RemoteListener` instances
    - `TransactionManager` instances
    - `ActivationID` instances
    - `ActivationSystem` instances
    - `LookupLocator` instances
    - `Lease` instances (via the new version of the `JoinManager` class)
    - `ServiceRegistrar` instances (via the new versions of the `JoinManager`, `LookupLocatorDiscovery`, and `LookupDiscovery` classes)
    - `ServiceRegistration` instances (via the new version of the `JoinManager` class)
  - Version two of the Jini technology-enabled discovery protocols
  - Establishment of a subject via a Java Authentication and Authorization Service (JAAS) login

  A complete list of the supported configuration entries plus example configuration files and command lines can be found in Outrigger's package documentation.

New Persistence Layer
  For this release Outrigger's persistence layer was completely rewritten. Progress Software's PSE Pro object database is still used, but the schema is simpler and much more loosely coupled to Outrigger's in memory data structures. This change also does away with the two process model, as the functionality of the former "back end" has been incorporated into a new thread running in the main Outrigger server process. This rewrite was done to make Outrigger more maintainable and to support new features going forward.

  This re-write also increased the number of Outrigger classes that can be re-built from source without the PSEPro development tools. See the note on building Outrigger from source code for details.

  The new implementation should be more reliable in the face of crashes but will also be slower for some applications. For other applications it may be faster because in most cases it performs fewer disk synchs when performing operations under transactions.

  Because of this rewrite, a database generated by previous releases will not be compatible with this release.

Outrigger's Blocking Query Protocol Has Been Overhauled
  Previously, Outrigger implemented blocking queries by having the proxy register a remote event listener with the space. When a matching entry appeared in the space, an event would be sent to the proxy and the proxy would try to grab the new entry.

  This release uses a new protocol where blocking queries block in the server. Although this ties up a thread (and potentially a socket connection) it appears to have better scaleability for most applications than the previous protocol. As part of developing and implementing the new protocol we were able to fix a number of bugs related to blocking queries. The new protocol should work better in non-LAN environments and is less complex to secure.

  If there is demand, we will investigate adding an optional callback-based blocking query protocol in a future release.

Add Support for Persistent, Non-Activatable Outrigger Servers
  Outrigger can now be run in three modes :
  - Transient,
  - Persistent and activatable, and
  - Persistent and non-activatable.
  See the package documentation for details.

Outrigger Uses the New Service Starter
  Like the other contributed service implementations in the starter kit, Outrigger has been changed to use the new service starter. Outrigger's package documentation has example command lines and configuration files for the new launcher.

Outrigger's Server Side JAR Files Have Been Restructured
  As part of the replacement of Outrigger's persistence layer, adding support for persistent, non-activatable Outrigger servers, and moving to the new service starter , Outrigger's JAR files have been restructured. Instead of having separate JAR files for the persistent and transient versions of Outrigger there is now just one top-level JAR file, `outrigger.jar`, that is used for both transient and persistent Outrigger services. The class files for the default persistence implementation have all been placed in `outrigger-logstore.jar` and `pro.zip`. Both files are included in `outrigger.jar` by reference and, if using the default persistence layer, must be present in the same directory as `outrigger.jar`. It is not necessary to have `outrigger-logstore.jar` or `pro.zip` present when running Outrigger in transient mode. Outrigger also assumes that `jsk-platform.jar` is also available. Under normal conditions as long as `jsk-platform.jar` is available to the service starter, the service starter will make `jsk-platform.jar` visible to Outrigger.

Outrigger Now Depends on Version 1.4 of the Java Platform
  Like the rest of the starter kit, Outrigger now requires version 1.4 of the Java platform, to host both the server and its proxies.

`outrigger-dl.jar` Has Been Restructured
  `outrigger-dl.jar` has been changed to enable the use of preferred classes by inclusion of a preferred list. Also, `outrigger-dl.jar` has been changed to assume that `jsk-platform.jar` is in the client's classpath (or extensions).

Numerous bugs and issues have been fixed or resolved

Persistent Outrigger's back end would sometimes produce intermittent `java.lang.StackOverflowError` errors
  Under certain usage patterns, in particular when storing a large number of small entries of the same class in the space, persistent Outrigger's back-end process would sometimes produce `java.lang.StackOverflowError` errors. There were two known workarounds for this issue, both involved passing additional arguments to the back-end process. One workaround was to set the `com.odi.Pool.objectsLimit` property to a sufficiently small value. The other workaround was to allocate a larger stack. This release uses a newer release of the PSE Pro object database, which fixes the underlying issue.

4462186:Blocking queries would sometimes fail even when there were matches in the space
  There was a race condition in Outrigger that would sometimes cause blocking queries submitted about the same time as a transaction commit or abort to not find entries that were made available by the transaction's end. This could cause the query to block longer than it should have. The race condition has been fixed in this release.

4616810:IfExists queries returned `null` when transactions replaced matching entries
  This was known as the Apples/Oranges bug and involved blocking ifExists queries using templates that had one or more subclasses. Under some circumstances, if an ifExists query using template `F' was blocked on a locked entry `A', and then a new entry `O' that matched F but was a different class from A, was written, and then the transaction that had A locked was resolved in such a way that A was removed from the space, the query could return `null` even though there had always been (and still was) an entry in the space that matched F. The way blocking ifExists queries are handled has been changed in this release so `null` will only be returned if there was a period where there were no matches in the space.

Clients who performed blocking queries sometimes took a long time to exit
  In previous versions, the first time a given Outrigger proxy performed a blocking query (a `read()`, `take()`, `readIfExists()`, or `takeIfExists()` with a non-zero timeout) against its server, the proxy exported a remote object using `java.rmi.server.UnicastRemoteObject.export()` and passed it to the server. As long as there were references to this remote object, Java RMI would keep a non-daemon thread running to accept connections for incoming calls. This non-daemon thread would keep the client's virtual machine for the Java platform from exiting - even if all of the client's other threads had finished. The way blocking queries are handled has been changed so it is no longer necessary for the proxy to export a remote object and thus no non-daemon threads will be created by the proxy.

Using an Entry class with an Outrigger server and then changing the structure of the class had unpredictable results
  In previous versions, if one created an `Entry` implementation class, wrote an instance of it into the space, and then changed the fields of the class (for example: adding fields, removing fields, changing their type, and so on), the results of writing instances of the new version of the class or performing reads and takes using an instance of the new version of the class were undefined. In the current release you will get an `java.rmi.UnmarshalException`.

The back-end process associated with `FrontEndSpace` did not always terminate immediately when the front-end process was terminated
  In the Solaris(TM) Operating System this did not cause any additional problems.

  On the Microsoft Windows NT platform, clients that attempted to call the service after the front-end process died would block until the back end process died, at which point they would get a `RemoteException`. Once the back-end process died, the next call to the space would restart the service.

  The current release does not have the back end in a separate process and thus does not run into this issue.

Outrigger needed to provide greater user feedback
  In previous releases Outrigger provided minimal user feedback on the success or failure of its initialization procedure. This lack of feedback was especially disconcerting with an activatable space, because the program run by the user exits after setting up the space. Often the user did not expect this to happen. The current release logs messages to the `com.sun.jini.outrigger.lifecycle` logger at the `INFO` level (which by default should print a message to the console) when an Outrigger server is successfully started.

4706973:Null pointer exceptions in debug statements
  In previous releases enabling certain debugging features would cause `NullPointerException`s. This issue has been addressed in this release.

Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.