Outrigger
Apache River v3.0.1 Release Notes

Description

Changes since the v2.2.0 release

Changes since the v2.1.1 release

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.