# Outrigger
Apache River v3.0.0 Release Notes

### Description

"Outrigger" is the name of the contributed JavaSpaces service from Sun Microsystems. The primary interface implemented by Outrigger is the `net.jini.space.JavaSpace05` interface (note, `JavaSpace05` extends the `net.jini.space.JavaSpace` interface so any implementation of `JavaSpace05` can also be used as a `JavaSpace`). For a listing of the additional interfaces implemented by Outrigger, please consult Outrigger's package documentation.

### Changes since the v2.2.0 release

- [RIVER-391] - Outrigger failure under stress

### Changes since the v2.1.1 release

- [RIVER-255] - Outrigger DestroyThread does not catch exceptions from exporter.unexport
- [RIVER-256] - Outrigger catch Throwable blocks should also catch Throwable

### Changes since the v2.0.1 release

Outrigger Implements the Proposed `net.jini.space.JavaSpace05` Extension to JavaSpaces technology
  This version of Outrigger implements the proposed `net.jini.space.JavaSpace05` extension to JavaSpaces technology. The `JavaSpace05` interface extends the `JavaSpace` interface to provide methods that allow clients to perform batch operations on the space (which are generally more efficient than performing an equivalent set of singleton operations) and to more easily develop applications where a given `Entry` needs to be read by multiple clients. See the API documentation for the `JavaSpace05` interface for details.

New `Store` Implementation, PSEPro Runtime Classes Not Included in Release
  The persistent version of Outrigger relies on a pluggable persistence layer, `org.apache.river.outrigger.Store`. Previous releases included one implementation of the `Store` interface, logstore. This release adds a second implementation, snaplogstore.

  While all the necessary classes are included with this release to run the transient version of Outrigger, or the persistent version using the new snaplogstore implementation of `Store`, the logstore implementation of `Store` requires the runtime classes for Progress Software's ObjectStore PSEPro for Java (PSEPro). Unfortunately, because of issues relating to the transition in licensing, this release does not include the PSEPro runtime classes, without which logstore will not work. We are sorry for any inconvenience this will cause. We hope to make a release with a complete version of logstore available as a separate download in the future.

  Where v2.0.n releases used logstore as the default `Store` implementation, this release has no default store. In order to switch an existing set of configuration files, security policy files, etc., from using logstore to snaplogstore, you will need to change the `org.apache.river.outrigger.store` configuration entry (or add a `store` if you don't already have one) to yield a `org.apache.river.outrigger.snaplogstore.LogStore` object. You will also need to ensure that `outrigger-snaplogstore.jar` has been granted sufficient permissions (see Outrigger's package documentation for a sample security policy file.).

  Note that depending on the nature of your application snaplogstore can have a significantly different performance profile than logstore.

  The storage formats used by snaplogstore and logstore are mutually incompatible.

Incompatible Change Made to `Store` Interface
  The persistent version of Outrigger relies on a pluggable persistence layer, `org.apache.river.outrigger.Store`. This release makes incompatible changes to a subsidiary interface, `org.apache.river.outrigger.LogOps` in order to support the implementation of the `JavaSpace05` interface. New methods were added and existing methods were changed, so old implementations will need to be changed to work with the current release, and any implementation that works with the current release will need to be changed to work with previous releases.

  Note, we consider the `Store` and its associated subsidiary interfaces to be experimental. They will often change incompatibly between releases, and could be removed completely.

Persistent Store Incompatible with Previous Versions
  As part of implementing `JavaSpace05`, we made incompatible changes to Outrigger's persistent store. The files generated by previous releases will not be compatible with this release.

Network Protocol Incompatible with Previous Versions
  In order to use a more efficient protocol for returning the results of `JavaSpace.write` calls, the network protocol used to communicate between Outrigger's proxy and server was incompatibly changed. Note, for most installations this should not cause a problem as clients will transparently download the new version of the proxy that uses the new protocol.

The `JavaSpaceAdmin`, `ConstrainableJavaSpaceAdmin`, and `AdminIterator` Interfaces Have Been Deprecated
  This release deprecates the `org.apache.river.outrigger.JavaSpaceAdmin` and `org.apache.river.outrigger.ConstrainableJavaSpaceAdmin` interfaces. Outrigger's admin proxy still implements `JavaSpaceAdmin` (and if deployed with a Java(TM) Remote Method Invocation implementation that supports remote method constraints, `ConstrainableJavaSpaceAdmin`), but it is our intention to stop doing so in a future release. The primary function provided by `JavaSpaceAdmin` and `ConstrainableJavaSpaceAdmin` was the creation of `org.apache.river.outrigger.AdminIterator` instances that could be used to semi-exhaustively read through the contents of the space. Similar functionality is now provided through the `JavaSpace05.contents` method.

  `JavaSpaceAdmin` extends the `net.jini.admin.JoinAdmin` and `org.apache.river.admin.DestroyAdmin` interfaces. It is our intention for Outrigger's admin proxy to continue implementing `JoinAdmin` and `DestroyAdmin` after support for `JavaSpaceAdmin` is dropped.

Outrigger's JAR Files Have Been Restructured
  To better support the layering of applications on top of the starter kit the starter kit's JAR files, including those related to Outrigger, have been restructured. The changes to the server-side files (e.g. `outrigger.jar`, `outrigger-logstore.jar`, etc.) may require changes to the security policy files used for Outrigger servers. Permissions must now be granted to `jsk-lib.jar` in addition to Outrigger's other server side JAR files. The changes to `outrigger-dl.jar` have an impact on how Outrigger's codebase is specified. Outrigger now requires a multi-element codebase that includes both `outrigger-dl.jar` and `jsk-dl.jar`. Also note that all of the starter kit's "`-dl.jar`" files, including `outrigger-dl.jar`, have been moved out of the `lib` directory and into the new `lib-dl` directory.

  For more details on the JAR file changes, please see the note in the Jini Technology Starter Kit Release Notes on JAR file changes.

  For examples on how to start Outrigger and a description of Outrigger JAR file structure, please see Outrigger's package documentation.

Bug Fixes of Interest

4754465:Race condition between logging takes and competing queries
  There was a race condition in persistent configurations of Outrigger that theoretically allowed the effects of a non-transactional `take`, non-transactional `takeIfExists`, or entry lease cancellation to be made visible before the removal of the entry was made durable. This race condition could give rise to scenarios where an entry flits out of, and then back into existence. For example:
  - If there was a query, Q, that matched the entry E,
  - and a concurrent operation, O, that was removing E but the space crashed between the time O removed E and the time E's removal was made durable then,
  - it was possible for Q to return `null`, implying that O had succeeded, and
  - for a future query to return E, implying that O had failed.
  The race condition has been fixed in this release.

5002184:Blocking calls in server during destroy processing maxes CPU
  The v2.0.n releases had a bug where if there was a blocked query in progress when the `DestroyAdmin.destroy` method was called, CPU usage would peak for up to two minutes and the process of destroying the server would be delayed. This was caused by Outrigger making repeated attempts to “nicely” unexport the server with no pause between attempts. This version addresses this issue by introducing a pause between unexport attempts. This delay can be controlled using the `unexportRetryDelay` configuration entry. This version also introduces the `maxUnexportDelay` configuration entry, which can be used to control how long Outrigger will attempt nice unexport attempts before giving up and forcefully unexporting itself (see the `maxUnexportDelay` configuration entry for more details).

6201948:Outrigger fails to unblock takes when last conflicting read lock is prepared
  Previous versions of Outrigger had a bug where Outrigger would not generate the correct internal events when an entry was read locked by two transactions and one of the transactions was prepared (Note Outrigger would generate the proper internal events if one of the two transactions was aborted, or if the entry was read locked by only one transaction and that transaction was prepared).

  What this meant in practice was that if you had entry, E, read locked under two transactions T1, and T2 and a blocked `take` (or `takeIfExists`) under T1 whose template matched E, then the `take` would not unblock if T2 was prepared (the `take` would unblock if T2 was aborted) even though the prepare resolved the last conflicting transaction. A `take` (or `takeIfExists`) under T1 started after the prepare of T2 would function properly. The take would also eventually unblock if the maximum server query timeout feature was being used.

6307184:Deadlock between adding entries and iteration
  Previous 2.n versions of Outrigger had a bug where attempts to iterate over the space using the `org.apache.river.outrigger.AdminIterator` or the `net.jini.space.JavaSpace05.contents` method while at the same time writing entries of a type the iteration could return would cause a deadlock. Note, in practice this was much more likely to happen with `AdminIterator` than `contents`.

  This issue has been fixed in this release.

  Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.