You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by th...@apache.org on 2010/12/08 12:34:39 UTC
svn commit: r1043362 [6/23] - in
/incubator/river/site/trunk/content/river/docs: ./ release-notes/ specs/
specs/images/
Added: incubator/river/site/trunk/content/river/docs/release-notes/mercury.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/mercury.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/mercury.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/mercury.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,106 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+<a name="top">
+<title>Release Notes for Mercury</title>
+
+<center>
+<h1>Mercury<br>
+v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+"Mercury" is the name of the contributed Jini event mailbox
+service implementation from Sun Microsystems. The <i>Jini Event Mailbox
+Specification</i> is available in <a
+href="../specs/html/mailbox-spec.html">HTML</a>.
+
+<p>
+
+<H3>Changes since the v2.1.1 release</H3>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-241'>RIVER-241</a>] -
+Mercury spelling errore
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-247'>RIVER-247</a>] -
+Destroy processing should use configurable duration and interval for unexporting
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-289'>RIVER-289</a>] -
+Fix for RIVER-247 introduced wrong license headers and references
+</li>
+
+<H3>Changes since the v2.1 release</H3>
+<dl>None</dl>
+
+<H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+
+ <dt> <b>"Pull" Functionality</b>
+ <dd> The Jini(TM) Event Mailbox Service
+ <a href="../specs/html/mailbox-spec.html">Specification</a>
+ was augmented with additional classes and
+ interfaces that provide synchronous access to
+ events (see sections EM.5-EM.7). Mercury was also
+ updated to implement this new functionality. <BR>
+ The following work still needs to be done:
+ <UL>
+ <LI>Implement the timeout functionality for
+ <code>RemoteEventIterator.next</code>
+ <LI>Make the batching implementation configurable. For example,
+ configuring the number of events that get returned to the
+ event mailbox client in a single call. Currently all the available
+ events are sent.
+ </UL>
+ <p>
+</dl>
+
+
+<!-- No issues for now
+
+<p>
+<H3>Known Issues (& Workarounds)</H3>
+<p>
+
+-->
+
+
+</ul>
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/netjinientry.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/netjinientry.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/netjinientry.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/netjinientry.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,121 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+
+<html>
+<head>
+ <title>Release Notes for the net.jini.entry package
+ </title>
+</head>
+
+<body text="black" bgcolor="white" link="#9b37cc" vlink="#cc1877" alink="white">
+<center>
+<h1><code>net.jini.entry</code> package<br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<hr>
+<ul>
+<H3>Description</H3>
+
+The <a
+href="../api/net/jini/entry/package-summary.html"><code>net.jini.entry</code>
+package</a> provides classes that are useful when handling or implementing
+entries.
+
+<p>
+
+<H3>Changes since the v2.1.1 release</H3>
+
+<dl>
+
+<dt><b>None</b>
+
+</dl>
+
+<H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+
+<dt><b>The API Documentation is Now the Formal Specification</b>
+<dd>
+
+Previously, the formal specification for the <code>net.jini.entry</code>
+package was a separate document. With this release, the formal specification
+is the revised API Documentation. As part of this change the specification
+language was generally cleaned up and made tighter.<p>
+
+<dt><b>Behavior of Various <code>AbstractEntry</code> Methods Clarified</b>
+<dd>
+
+The previous versions of the specification for <code><a
+href="../api/net/jini/entry/AbstractEntry.html">net.jini.entry.AbstractEntry</a></code>
+did not specify how the static <code>equals</code>, <code>hashCode</code>,
+and <code>toString</code> methods behaved if passed <code>null</code>
+values. This version of the specification specifies that :
+
+<ul>
+<li> <code>equals</code> should return <code>true</code> if both
+ arguments are <code>null</code>, and <code>false</code> if
+ only one argument is <code>null</code>.
+<li> <code>hashCode</code> should return <code>0</code> if passed
+ <code>null</code>.
+<li> <code>toString</code> should return <code>"null"</code> if
+ passed <code>null</code>.
+</ul>
+<p>
+Note: Previously our implementation of <code>AbstractEntry</code> would
+throw a <code>NullPointerException</code> if any of these methods were
+passed a <code>null</code> value.
+<p>
+
+Also, the specification of the static <code>toString</code> method was
+changed to require that the returned string include the name of the
+argument's class.
+
+<dt><b> <code>UnusableEntriesException</code> Added</b>
+<dd>
+
+The <code><a
+href="../api/net/jini/entry/UnusableEntriesException.html">net.jini.entry.UnusableEntriesException</a></code>
+class was added. <code>UnusableEntriesException</code> can be used by
+methods that normally return a collection of entries when one or more of
+the entries can't be unmarshalled.
+
+</dl>
+
+<p>
+
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/new.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/new.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/new.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/new.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,211 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en-US">
+<head>
+ <title>Apache River Release Notes, v2.1.1</title>
+</head>
+<body alink="#ffffff" vlink="#cc1877" link="#9b37cc"
+ style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
+<h1>
+<center> <a name="TOP">Apache River <br>
+</a><a href="index.html">v2.1.2 Release Notes</a></center>
+</h1>
+<p>
+</p>
+<hr>
+<ul>
+ <h2>Release notes from v2.1</h2>
+ <p> </p>
+ <dl>
+
+<p>Note that some of the links here contain updated information since v2.1</p>
+ <dt><b><p>
+Ant build support</b> </dt>
+ <dd>This release contains support for generating binary
+ files and documentation from the provided source code using the Apache
+ Ant build tool. As part of this effort, we have simplified the source tree
+ structure by eliminating the historical <code>vob/jive</code> and
+ <code>vob/tools</code> intermediate directories.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="http://ant.apache.org">Apache Ant</a></li>
+ <li><a href="../build.html">Build Instructions</a><br>
+ </li>
+ </ul>
+ </dd>
+ <dt><b><p>
+<code>
+EnvCheck</code> tool</b> </dt>
+ <dd>This new tool is used to perform validity checks on the runtime
+ environment of a client or service by validating the system properties
+ and configuration files used when starting that service.<p>
+ <b>More Information</b>
+ <ul>
+ <li> <a href="../api/com/sun/jini/tool/envcheck/EnvCheck.html">
+ <code>com.sun.jini.tool.EnvCheck</code> API Documentation</a> </li>
+ </ul>
+ </dd>
+ <dt><b><p><code>
+PreferredListGen</code> tool</b> </dt>
+ <dd>This new tool is used to generate preferred class
+ information for a service's downloadable JAR files.<p>
+ <b>More Information</b>
+ <ul>
+ <li> <a href="../api/com/sun/jini/tool/PreferredListGen.html">
+ <code>com.sun.jini.tool.PreferredListGen</code> API Documentation</a> </li>
+ </ul>
+ </dd>
+ <dt><b><p>
+Tool wrappers</b> </dt>
+ <dd>Executable JAR wrapper files have been included for all of the tools
+ included in the release.<p>
+
+ <b>More Information</b>
+ <ul>
+ <li> <a href="index.html#tools_jars">
+ Tools section of the Release Notes</a> </li>
+ </ul>
+ </dd>
+ <dt><b><p>
+Mailbox extensions</b> </dt>
+ <dd>We are proposing the addition of pull-style access to the event mailbox
+ service. This extension allows mailbox clients to retrieve events on demand.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="mercury.html">Mercury Release Notes</a></li>
+ <li><a href="../api/com/sun/jini/mercury/package-summary.html">
+ <code>com.sun.mercury</code> API Documentation</a></li>
+ </ul>
+ </dd>
+ <dt><b><p>
+JavaSpaces extensions</b> </dt>
+ <dd>We are proposing the <code>net.jini.space.JavaSpace05</code> extension to
+ JavaSpaces technology. The extension supports batch operations and
+ makes it easier to develop applications where the same entry needs
+ to be read by multiple clients. The version of Outrigger included
+ with this release implements this extension.<p>
+ <b>More Information</b><p>
+ <ul>
+ <li><a href="../api/net/jini/space/JavaSpace05.html">
+ <code>net.jini.space.JavaSpace05</code> API Documentation</a>
+ <li><a href="outrigger.html">Outrigger Release Notes</a>
+ </ul>
+ </dd>
+ <dt><b><p><a name="JARchanges"></a>
+JAR file changes</b> </dt>
+ <dd>The <code>lib</code> directory (containing JAR files) has been split
+ into three directories in this release: <code>lib</code>, <code>lib-dl</code>,
+ and <code>lib-ext</code>. All codebase JAR files are now in the <code>lib-dl</code>
+ directory; this change was made to enable serving up just those files via the
+ HTTP server, providing a better network security posture. This change will affect
+ any existing scripts and configurations that start an HTTP server referencing
+ the <code>lib</code> directory. The <code>jsk-policy.jar</code> file is now
+ in the <code>lib-ext</code> directory so that, if desired, you can specify
+ that directory as an additional J2SE extension directory rather than
+ installing the JAR file into the default J2SE extension directory.
+ <p>
+ Two new JAR files, <code>jsk-lib.jar</code> and <code>jsk-dl.jar</code>,
+ have been introduced to better enable layered systems to use
+ JAR files directly in deployments and avoid including class
+ files in their own layered JAR files. These JAR files are also now used
+ by the services in the release. The addition of <code>jsk-lib.jar</code>
+ to class paths will affect existing service and browser policy files
+ (permissions must be granted to <code>jsk-lib.jar</code>), and the addition
+ of <code>jsk-dl.jar</code> to codebases will affect existing scripts
+ and configurations that set up codebases for services.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="../info-index.html#examine">Getting Started</a></li>
+ <li><a href="index.html#platform_jars">Platform JARs</a></li>
+ </ul>
+ </dd>
+ <dt><b><p><code>
+ConfigurationFile</code> additions</b> </dt>
+ <dd><code>net.jini.config.ConfigurationFile</code> now supports the
+ ability to concatenate strings using the '+' operator. This provider
+ now also allows subclasses to control the
+ <code>net.jini.config.ConfigurationException</code> it throws when
+ problems are encountered in parsing a configuration source or in
+ returning an entry or the type of an entry.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="../api/net/jini/config/ConfigurationFile.html">
+ <code>net.jini.config.ConfigurationFile</code> API Documentation</a></li>
+ </ul>
+ </dd>
+ <dt><b><p>
+Multihomed host support</b> </dt>
+ <dd>The standard Jini extensible remote invocation (Jini ERI)
+ transport layer providers and the discovery utilities now attempt
+ connections to all of the IP addresses that a host name resolves
+ to, instead of just the first one.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="../api/net/jini/discovery/package-summary.html">
+ <code>net.jini.discovery</code> API Documentation</a></li>
+ <li><a href="jeri.html">
+ Jini ERI Release Notes</a></li>
+ <li><a href="discovery.html">
+ Discovery Release Notes</a></li>
+ </ul>
+ </dd>
+ <dt><b><p>
+New <code>JoinManager</code> addition</b> </dt>
+ <dd><code>JoinManager</code>'s public APIs have been enhanced to provide the
+ ability to replace a previously registered service with all discovered
+ lookup services. In addition, the ability to configure lease renewal
+ intervals has been added.<p>
+ <b>More Information</b>
+ <ul>
+ <li><a href="../api/net/jini/lookup/JoinManager.html">
+ <code>net.jini.lookup.JoinManager</code> API Documentation</a>
+ </li>
+ </ul>
+ </dd>
+ <dt><b><p>
+Reggie enhancements</b> </dt>
+ <dd>There have been several modifications made to Reggie around handling
+ of evolved proxy and attribute set classes, reuse of multicast
+ announcements, and others.<p>
+ <b>More Information</b>
+ <ul>
+ <li> <a href="reggie.html">Reggie Release Notes</a></li>
+ </ul>
+ </dd>
+ </ul>
+
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/norm.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/norm.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/norm.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/norm.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,122 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+<a name="top">
+<title>Release Notes for Norm</title>
+
+<center>
+<h1>Norm<br>
+v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+"Norm" is the name of the contributed Jini technology lease renewal
+service implementation from Sun Microsystems. The <i>River Lease Renewal
+Service Specification</i> is available in <a
+href="../specs/html/lrs-spec.html">html</a>.
+<p>
+The specification for Norm is defined not only by the <i>River Lease
+Renewal Service Specification</i>, but also by the API documentation
+(generated by the Javadoc(TM) tool) for <a
+href="../api/net/jini/admin/Administrable.html">
+<code>Administrable</code></a>.
+<p>
+
+<H3>Changes since the v2.1.1 release</H3>
+
+<dl>
+ <dt> <b>None</b>
+</dl>
+<H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+
+ <dt> <b>Configuration</b>
+ <dd> In this release, no new configuration entries have been added, nor have any other
+ changes occurred with respect to the configuration.
+ <p>
+ A full list of supported configuration entries is given in this service's
+ <a href="../api/com/sun/jini/norm/package-summary.html#configuration"> man page</a>.
+ <p>
+
+ <dt> <b>Logging</b>
+ <dd> In this release, no changes have occurred with respect to the logging mechanism
+ employed by Norm, which logs diagnostic information using a separate
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html"> <code>Logger</code></a>
+ for each type of information logged. The name of each logger
+ is a dot-separated concatenation of the implementation package name,
+ <code>com.sun.jini.norm</code>, with a descriptive string. A description
+of each
+ logger used by this service, as well as what information is logged to which
+ logger, and at what logging level, is given in this service's
+ <a href="../api/com/sun/jini/norm/package-summary.html#logging"> man page</a>.
+ <p>
+
+ <dt> <b>Bug Fixes of Interest</b>
+ <dd> A number of bugs have been addressed in this release of Norm.
+ What follows is a description of those bugs that might be of
+ interest:
+ <p>
+
+ <dt><b>4965775: Norm threads should guard against lost interrupts</b><dt>
+
+ <dd> Thread subclasses in Norm that use logging and do not override the
+ <code>Thread.interrupt</code> method to set an "interrupted" field are
+ susceptable to lost interrupts. This problem can occur because
+ <code>java.util.logging</code> swallows internal
+ <code>InterruptedIOExceptions</code> without setting the receiving
+ thread's interrupted status, effectively forgetting the interrupt. The
+ end result is that some of Norm's threads could loop endlessly instead of terminating, causing Norm shutdowns to hang.
+ <p>
+ This bug has been fixed.
+ </dd>
+</dl>
+
+<!-- No issues for now
+
+<p>
+<H3>Known Issues (& Workarounds)</H3>
+<p>
+
+-->
+
+</ul>
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/outrigger.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/outrigger.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/outrigger.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/outrigger.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,334 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+
+<html>
+<head>
+ <title>Release Notes for com.sun.jini.outrigger
+ </title>
+</head>
+
+<body text="black" bgcolor="white" link="#9b37cc" vlink="#cc1877" alink="white">
+<center>
+<h1>Outrigger<br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<hr>
+<ul>
+<H3>Description</H3>
+
+"Outrigger" is the name of the contributed JavaSpaces service
+from Sun Microsystems. The primary interface implemented by Outrigger is the
+<code><a
+href="../api/net/jini/space/JavaSpace05.html">net.jini.space.JavaSpace05</a></code>
+interface (note, <code>JavaSpace05</code> extends the
+<code>net.jini.space.JavaSpace</code> interface so any implementation of
+<code>JavaSpace05</code> can also be used as a <code>JavaSpace</code>). For
+a listing of the additional interfaces implemented by Outrigger, please
+consult <a
+href="../api/com/sun/jini/outrigger/package-summary.html">Outrigger's
+package documentation</a>.
+<p>
+
+<H3>Changes since the v2.1.1 release</H3>
+
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-255'>RIVER-255</a>] -
+Outrigger DestroyThread does not catch exceptions from exporter.unexport
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-256'>RIVER-256</a>] -
+Outrigger catch Throwable blocks should also catch Throwable
+</li>
+<p>
+ <H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+
+<dt><b>Outrigger Implements the Proposed <code>net.jini.space.JavaSpace05</code> Extension to JavaSpaces technology</b>
+<dd>
+
+This version of Outrigger implements the proposed
+<code>net.jini.space.JavaSpace05</code> extension to JavaSpaces
+technology. The <code>JavaSpace05</code> interface extends the
+<code>JavaSpace</code> 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 <code>Entry</code> needs to be
+read by multiple clients. See the API documentation for the <code><a
+href="../api/net/jini/space/JavaSpace05.html">JavaSpace05</a></code>
+interface for details.<p>
+<p>
+
+<dt><b>New <code>Store</code> Implementation, PSEPro Runtime Classes Not
+Included in Release</b>
+<dd>
+
+The persistent version of Outrigger relies on a pluggable persistence layer,
+<a
+href="../api/com/sun/jini/outrigger/Store.html"><code>com.sun.jini.outrigger.Store</code></a>.
+Previous releases included one implementation of the <code>Store</code>
+interface, <a
+href="../api/com/sun/jini/outrigger/logstore/LogStore.html">logstore</a>.
+This release adds a second implementation, <a
+href="../api/com/sun/jini/outrigger/snaplogstore/LogStore.html">snaplogstore</a>.
+<p>
+
+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 <code>Store</code>, the logstore
+implementation of <code>Store</code> requires the runtime classes for
+Progress Software's <i>ObjectStore PSEPro for Java</i>
+(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.
+<p>
+
+Where v2.0.n releases used logstore as the default <code>Store</code>
+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 <a
+href="../api/com/sun/jini/outrigger/package-summary.html#store">
+<code>com.sun.jini.outrigger.store</code></a> configuration entry (or add a
+<code>store</code> if you don't already have one) to yield a
+<code>com.sun.jini.outrigger.snaplogstore.LogStore</code> object. You will
+also need to ensure that <code>outrigger-snaplogstore.jar</code> has been
+granted sufficient permissions (see Outrigger's package <a
+href="../api/com/sun/jini/outrigger/package-summary.html#outrigger_all_policy">documentation</a>
+for a sample security policy file.).<p>
+
+Note that depending on the nature of your application snaplogstore can have
+a significantly different performance profile than logstore.<p>
+
+The storage formats used by snaplogstore and logstore are mutually
+incompatible.<p>
+<p>
+
+<dt><b>Incompatible Change Made to <code>Store</code> Interface</b>
+
+<dd>
+The persistent version of Outrigger relies on a pluggable persistence
+layer, <a
+href="../api/com/sun/jini/outrigger/Store.html"><code>com.sun.jini.outrigger.Store</code></a>.
+This release makes incompatible changes to a subsidiary interface, <a
+href="../api/com/sun/jini/outrigger/LogOps.html"><code>com.sun.jini.outrigger.LogOps</code></a>
+in order to support the implementation of the <a
+href="../api/net/jini/space/JavaSpace05.html"><code>JavaSpace05</code></a>
+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.<p>
+
+Note, we consider the <code>Store</code> and its associated subsidiary
+interfaces to be experimental. They will often change incompatibly between
+releases, and could be removed completely.<p>
+
+<dt><b>Persistent Store Incompatible with Previous Versions</b>
+<dd>
+As part of implementing <a
+href="../api/net/jini/space/JavaSpace05.html"><code>JavaSpace05</code></a>,
+we made incompatible changes to Outrigger's persistent store. The files
+generated by previous releases will not be compatible with this release.
+<p>
+
+<dt><b>Network Protocol Incompatible with Previous Versions</b>
+<dd>
+In order to use a more efficient protocol for returning the results of <a
+href="../api/net/jini/space/JavaSpace.html#write(net.jini.core.entry.Entry,
+net.jini.core.transaction.Transaction,
+long)"><code>JavaSpace.write</code></a> 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.
+<p>
+
+<dt><b>The <code>JavaSpaceAdmin</code>,
+<code>ConstrainableJavaSpaceAdmin</code>, and <code>AdminIterator</code>
+Interfaces Have Been Deprecated</b>
+<dd>
+
+This release deprecates the <code><a
+href="../api/com/sun/jini/outrigger/JavaSpaceAdmin.html">
+com.sun.jini.outrigger.JavaSpaceAdmin</a></code> and <code><a
+href="../api/com/sun/jini/outrigger/ConstrainableJavaSpaceAdmin.html">
+com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin</a></code>
+interfaces. Outrigger's admin proxy still implements
+<code>JavaSpaceAdmin</code> (and if deployed with a Java(TM) Remote Method
+Invocation implementation that supports remote method constraints,
+<code>ConstrainableJavaSpaceAdmin</code>), but it is our intention to stop
+doing so in a future release. The primary function provided by
+<code>JavaSpaceAdmin</code> and <code>ConstrainableJavaSpaceAdmin</code>
+was the creation of <code><a
+href="../api/com/sun/jini/outrigger/AdminIterator.html">com.sun.jini.outrigger.AdminIterator</a></code>
+instances that could be used to semi-exhaustively read through the contents
+of the space. Similar functionality is now provided through the <code><a
+href="../api/net/jini/space/JavaSpace05.html#contents(java.util.Collection, net.jini.core.transaction.Transaction, long, long)">JavaSpace05.contents</a> </code> method. <p>
+
+<code>JavaSpaceAdmin</code> extends the <code><a
+href="../api/net/jini/admin/JoinAdmin.html">net.jini.admin.JoinAdmin</a></code>
+and <code><a
+href="../api/com/sun/jini/admin/DestroyAdmin.html">com.sun.jini.admin.DestroyAdmin</a></code>
+interfaces. It is our intention for Outrigger's admin proxy to continue
+implementing <code>JoinAdmin</code> and <code>DestroyAdmin</code> after
+support for <code>JavaSpaceAdmin</code> is dropped.
+
+<dt><b>Outrigger's JAR Files Have Been Restructured</b>
+<dd>
+
+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. <code>outrigger.jar</code>, <code>outrigger-logstore.jar</code>,
+etc.) may require changes to the security policy files used for Outrigger
+servers. Permissions must now be granted to <code>jsk-lib.jar</code> in
+addition to Outrigger's other server side JAR files. The changes to
+<code>outrigger-dl.jar</code> have an impact on how Outrigger's codebase is
+specified. Outrigger now requires a multi-element codebase that includes
+both <code>outrigger-dl.jar</code> and <code>jsk-dl.jar</code>. Also note
+that all of the starter kit's "<code>-dl.jar</code>" files, including
+<code>outrigger-dl.jar</code>, have been moved out of the <code>lib</code>
+directory and into the new <code>lib-dl</code> directory.<p>
+
+For more details on the JAR file changes, please see the note in the Jini
+Technology Starter Kit Release Notes on <a href="new.html#JARchanges">
+JAR file changes</a>.
+<p>
+
+For examples on how to start Outrigger and a description of Outrigger JAR
+file structure, please see <a
+href="../api/com/sun/jini/outrigger/package-summary.html">Outrigger's
+package documentation</a>.
+<p>
+
+<dt><b>Bug Fixes of Interest</b>
+<p>
+
+<dl>
+
+<dt><b>4754465:Race condition between logging takes and competing queries</b><dt>
+
+<dd>
+There was a race condition in persistent configurations of Outrigger that
+theoretically allowed the effects of a non-transactional <code>take</code>,
+non-transactional <code>takeIfExists</code>, 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:
+
+<ul>
+<li> If there was a query, <em>Q</em>, that matched the entry
+ <em>E</em>,
+<li> and a concurrent operation, <em>O</em>, that was removing
+ <em>E</em> but the space crashed between the time <em>O</em> removed
+ <em>E</em> and the time <em>E</em>'s removal was made durable
+ then,
+<li> it was possible for <em>Q</em> to return <code>null</code>, implying
+ that <em>O</em> had succeeded, and
+<li> for a future query to return <em>E</em>, implying that <em>O</em>
+ had failed.
+</ul>
+
+The race condition has been fixed in this release.
+
+
+<p>
+
+<dt><b>5002184:Blocking calls in server during destroy processing maxes CPU</b>
+<dd>
+The v2.0.n releases had a bug where if there was a blocked query
+in progress when the <a
+href="../api/com/sun/jini/admin/DestroyAdmin.html#destroy()"><code>DestroyAdmin.destroy</code></a>
+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 <a
+href="../api/com/sun/jini/outrigger/package-summary.html#unexportRetryDelay"><code>unexportRetryDelay</code></a>
+configuration entry. This version also introduces the <a
+href="../api/com/sun/jini/outrigger/package-summary.html#maxUnexportDelay"><code>maxUnexportDelay</code></a>
+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 <code>maxUnexportDelay</code> configuration entry for more
+details).
+<p>
+
+
+
+<dt><b>6201948:Outrigger fails to unblock takes when last conflicting read
+lock is prepared</b><dt>
+
+
+<dd>
+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). <p>
+
+What this meant in practice was that if you had entry, <em>E</em>, read
+locked under two transactions <em>T1</em>, and <em>T2</em> and a blocked
+<code>take</code> (or <code>takeIfExists</code>) under <em>T1</em> whose
+template matched <em>E</em>, then the <code>take</code> would not unblock
+if <em>T2</em> was prepared (the <code>take</code> would unblock if
+<em>T2</em> was aborted) even though the prepare resolved the last
+conflicting transaction. A <code>take</code> (or <code>takeIfExists</code>)
+under <em>T1</em> started after the prepare of <em>T2</em> would function
+properly. The take would also eventually unblock if the <em>maximum server
+query timeout</em> feature was being used.
+<p>
+
+<dt><b>6307184:Deadlock between adding entries and iteration</b>
+
+<dd>
+Previous 2.n versions of Outrigger had a bug where attempts to iterate over the
+space using the <code><a
+href="../api/com/sun/jini/outrigger/AdminIterator.html">com.sun.jini.outrigger.AdminIterator</a></code>
+or the <code><a
+href="../api/net/jini/space/JavaSpace05.html#contents">net.jini.space.JavaSpace05.contents</a></code> 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 <code>AdminIterator</code> than <code>contents</code>.
+<p>
+
+This issue has been fixed in this release.
+
+<p>
+
+
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/reggie.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/reggie.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/reggie.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/reggie.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,178 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+<a name="top">
+<title>Release Notes for com.sun.jini.reggie</title>
+
+<center>
+<h1>Reggie<br>
+v2.1.2 Release Notes</h1>
+</center>
+<hr>
+<ul>
+<h3>Description</h3>
+"Reggie" is the name of the contributed Jini lookup service implementation
+from Sun Microsystems. The specification for the River lookup service is
+available in <a href="../specs/html/lookup-spec.html">HTML</a>.
+<p/>
+The specification for Reggie is defined not only by the <i>Jini Lookup Service
+Specification</i>, but also by the API documentation (generated by the
+Javadoc(TM) tool) for <a href="../api/net/jini/admin/Administrable.html">
+<code>Administrable</code></a>.
+<p/>
+<h3>Changes since the v2.1.1 release</h3>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-225'>RIVER-225</a>] -
+NullPointerException in Reggie during destroy
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-246'>RIVER-246</a>] -
+Consider adding shutdown hook so Reggie sends final multicast packet if its VM
+is terminated
+</li>
+<h3>Changes since the v2.1 release</h3>
+<dl>
+ <dt><b>None</b></dt>
+
+</dl>
+<p>
+
+<h3>Changes since the v2.0.1 release</h3>
+<dl>
+ <dt><b>Handling of Evolved Types</b></dt>
+ <dd>
+ Consider the case where service <code>S</code> has been deployed in a
+ network, and <code>S</code> needs to be modified to implement
+ a new interface. Let's call the modified service <code>S'</code>.
+ In previous versions of Reggie, a client would not find a proxy to
+ <code>S'</code> when doing a lookup by the new interface unless
+ the <code>S'</code> proxy class was renamed. This version of Reggie
+ allows a client to find a proxy to <code>S'</code> when doing a
+ lookup by the new interface, even if the name of the proxy class has
+ not been changed and there are instances of <code>S</code> already
+ registered.<p/>
+ </dd>
+ <dt><b>Reuse of Multicast Announcements</b></dt>
+ <dd>
+ Reggie now reuses multicast announcements when there are no changes
+ in host, port, or group information in order to minimize the expense of
+ signing announcement packets in deployments that have been configured
+ to use secure discovery.<p/>
+ </dd>
+ <dt><b>Delayed Verification of Multicast Requests</b></dt>
+ <dd>
+ Reggie also delays verifying signatures on multicast requests until
+ it can determine that it must reply to the request. This minimizes
+ the expense of verifying signatures in deployments configured with
+ secure discovery.<p/>
+ </dd>
+ <dt><b>Socket Connection Timeout when Replying to a Multicast
+ Request</b></dt>
+ <dd>
+ This version of Reggie allows a deployer to specify a timeout to be
+ applied when establishing a connection to the multicast response
+ server of a client attempting to discover Reggie. The timeout can
+ be specified by adding a
+ <a href="../api/net/jini/core/constraint/ConnectionRelativeTime.html">
+ <code>ConnectionRelativeTime</code></a> constraint to Reggie's
+ <code>discoveryConstraints</code>. For information on additional
+ constraints supported by Reggie, refer to
+ <a href="../api/com/sun/jini/reggie/package-summary.html">
+ <code>Reggie's manual pages</code></a>
+ <p/>
+ </dd>
+ <dt><b>Modifications to Reggie's Proxies</b></dt>
+ <dd>
+ Reggie's
+ <a href="../api/net/jini/core/lookup/ServiceRegistrar.html">
+ <code>ServiceRegistrar</code></a>,
+ <a href="../api/net/jini/core/lookup/ServiceRegistration.html">
+ <code>ServiceRegistration</code></a>,
+ <a href="../api/net/jini/core/lease/Lease.html">
+ <code>Lease</code></a>, and admin proxies now override
+ <code>java.lang.Object.toString()</code> to facilitate debugging by
+ providing additional information, like Reggie's
+ <a href="../api/net/jini/core/lookup/ServiceID.html">
+ <code>ServiceID</code></a> and underlying Java (TM) Remote Method
+ Invocation (Java RMI) stub.<p/>
+ The communication protocol used between Reggie and its main proxy
+ has been modified to enable handling of evolved types. This new
+ protocol is not compatible with that of earlier releases.<p/>
+ </dd>
+ <dt><b>Log File Format</b></dt>
+ <dd>
+ The log file format used by the persistent version of Reggie in this
+ release is not compatible with that of earlier releases.<p/>
+ </dd>
+ <dt><b>Bug Fixes</b></dt>
+ <dd>
+ <ul>
+ <li>
+ <i>4939735 - Reggie doesn't refresh self-registration on
+ restart</i><br/>
+ The persistent version of reggie no longer stores its
+ self-registration; rather, the self-registration is recreated
+ each time reggie is restarted to allow for configuration or
+ export changes to be reflected in the proxy reggie registers
+ with itself.
+ </li>
+ <li>
+ <i>5002218 - Reggie should properly handle remote calls that
+ arrive before initialization is complete</i><br/>
+ Calls that arrive while reggie is in the process
+ of initializing will now block until reggie has completed its
+ initialization. Calls that arrive after reggie has commenced
+ its shutdown process will now result in a
+ <code>java.rmi.NoSuchObjectException</code>.
+ </li>
+ </ul>
+ </dd>
+</dl>
+<p>
+
+
+<!-- No issues for now
+
+<p>
+<H3>Known Issues (& Workarounds)</H3>
+<p>
+
+-->
+
+</ul>
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/security.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/security.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/security.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/security.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,120 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+<a name="top">
+<title>Release Notes for net.jini.security</title>
+
+<center>
+<h1><code>net.jini.security</code><br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+
+<p>The <a href="../api/net/jini/security/package-summary.html">
+<code>net.jini.security</code></a> package and its subpackages provide
+abstractions and facilities for managing security.
+
+<H3>Changes since the v2.1.1 release</H3>
+
+<dl>
+
+<dt><b>None</b></dt>
+
+</dl>
+
+<H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+
+<dt><b>New proxy preparer</b></dt>
+<dd>
+<p>A new proxy preparer class,
+<a href="../api/net/jini/security/VerifyingProxyPreparer.html">
+<code>VerifyingProxyPreparer</code></a>, has been added. In contrast to
+<a href="../api/net/jini/security/BasicProxyPreparer.html">
+<code>BasicProxyPreparer</code></a>, this new preparer always verifies that
+proxies are trusted, and permits full control over the context elements used
+during trust verification, the class loader used to find trust verifiers,
+and the principals used to scope dynamic permission grants. In particular,
+it can be used to specify a
+<a href="../api/net/jini/security/proxytrust/BasicUntrustedObjectSecurityContext.html">
+<code>BasicUntrustedObjectSecurityContext</code></a> context element for
+controlling the operation of
+<a href="../api/net/jini/security/proxytrust/ProxyTrustVerifier.html">
+<code>ProxyTrustVerifier</code></a> (see below).
+</dd>
+
+<a name="verification">
+<dt><b>Trust verification restriction</b></dt></a>
+<dd>
+<p><a href="../api/net/jini/security/proxytrust/ProxyTrustVerifier.html">
+<code>ProxyTrustVerifier</code></a> has been changed so that, by default,
+when attempting to obtain a bootstrap proxy, operations on untrusted objects
+are performed in a restricted security context that limits the permissions
+of unprivileged code (meaning code that does not use some form of
+<code>doPrivileged</code>) to just the permissions that have been
+granted to all code. In most cases this default will not cause problems,
+but there are cases where it will. In particular, if you are trying to
+verify a proxy that uses activation, and a remote call to activate the
+service is required to obtain the bootstrap proxy, the remote call will
+now fail due to lack of a <code>SocketPermission</code> (unless you have
+granted broad <code>connect</code> <code>SocketPermission</code> to all code,
+which is generally undesirable). To make such a deployment work, you need
+to provide a
+<a href="../api/net/jini/security/proxytrust/BasicUntrustedObjectSecurityContext.html">
+<code>BasicUntrustedObjectSecurityContext</code></a> context element that
+specifies which additional permissions unprivileged code is permitted to
+exercise (provided the code has already been granted those permissions).
+This is aimed in particular at specifying the permissions that local code
+(or already trusted code) is permitted to exercise. For example, you would
+specify <code>SocketPermission</code> to connect to whatever hosts and ports
+can be used for activation. You can use
+<a href="../api/net/jini/security/VerifyingProxyPreparer.html">
+<code>VerifyingProxyPreparer</code></a> (see above) to specify such a
+context element.
+</dd>
+
+</dl>
+
+
+</ul>
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/release-notes/servicediscovery.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/servicediscovery.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/servicediscovery.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/servicediscovery.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,508 @@
+<!--
+ ! 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.
+ !-->
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+
+
+<title>Jini Service Discovery Utilities Release Notes</title>
+
+<center>
+<h1>Jini Service Discovery Utilities
+ <BR>River v2.1.2 Release Notes
+</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+
+The class
+<a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>net.jini.lookup.ServiceDiscoveryManager</code></a>
+is a utility class that can be used to help a Jini technology-enabled
+service or client (<i>Jini service</i> or <i>Jini client</i>)
+acquire services of interest that are registered with lookup services
+with which the service or client wishes to interact.
+<p>
+The specification for the
+<a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>
+utility is contained in the <i>Jini Service Discovery Utilities Specification</i>,
+which is available in <a href="../specs/html/servicediscutil-spec.html">html</a>.
+<p>
+
+<H3>Changes since the v2.0.1 release</H3>
+
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-324'>RIVER-324</a>] -
+Under certain circumstances, the ServiceDiscoveryManager internal LookupCache
+implementation can incorrectly process attribute change events before the
+lookup snapshot is processed.
+</li>
+
+<H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+ <dt> <b>Configuration</b>
+ <dd> In this release, no new configuration entries have been added, nor have any other
+ changes occurred with respect to the configuration.
+ <p>
+ A full list of supported configuration entries is given in this utility's
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html#sdmConfigEntries"> class documentation</a>.
+ <p>
+
+ <dt> <b>Logging</b>
+ <dd> In this release, no changes have occurred with respect to the logging mechanism
+ employed by the service discovery manager implementation, which logs diagnostic information to the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html"> <code>Logger</code></a>
+ named <code>net.jini.lookup.ServiceDiscoveryManager</code>. For a description of the
+ information that is logged, as well as the associated logging levels, refer to the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html#sdmLogging"> class documentation</a>.
+ <p>
+
+ <dt> <b>Bug Fixes of Interest</b>
+ <dd> A number of bugs have been addressed in this release of the
+ service discovery manager. What follows is a description of those
+ bugs that might be of interest:
+ <p>
+
+ <dt><b>4972100: SDM NPE in getServiceItems when blocking lookup called before
+filter is applied</b><dt>
+ <dd> When one of the blocking versions of the <code>lookup</code> method is
+ invoked, there are conditions in which a <code>NullPointerException</code>
+ can occur. One possible scenario in which this bug can occur is as follows:
+
+<pre><code>SDM.lookup(duration)
+ SDM creates cache ----- RegisterListenerTask(wait for events)
+ LookupTask begins
+ get snapshot (lookup state)
+ -- done --
+wait(duration)
+ *** start targetted service ***
+ NOMATCH_MATCH event received
+ NotifyEventTask (process event)
+ NewOldServiceTask (new service)
+ addToMap -- (item,null)
+exit wait
+call cach.lookup()
+ filterMaybeDiscard()
+getServiceItems()
+map(item,null) ===> NPE
+ filter -- map(item,filteredItem)</code></pre>
+
+ If the timing is right, <code>getServiceItems</code> can be entered
+ before the filter is applied and the non-<code>null</code>
+ <code>filteredItem</code> is placed in the map. If this occurs,
+ <code>getServiceItems</code> will attempt to access
+ <code>filteredItem.srvc</code>, which will result in a
+ <code>NullPointerException</code>.
+ </dd>
+ <p>
+ <dt><b>5102733: SDM cache.notifyServiceMap does not use event ID in its decision process</b><dt>
+ <dd> Prior to this release, in the method
+ <code>ServiceDiscoveryManager.LookupCacheImpl.notifyServiceMap</code>,
+ only the sequence number of the new event and the sequence number stored
+ in the <code>EventReg</code> element of the <code>eventRegMap</code> were compared when determining whether or not there is a "gap" in the event
+ sequence; in which case, a snapshot would be requested from the associated
+ lookup service. This could result in multiple unnecessary snapshots being requested; and thus, unnecessary network traffic and resource usage.
+ <p>
+ To understand how this problem could occur, consider the following scenario:
+
+<pre>1 activatable lookup service registered with Phoenix (or RMID)
+4 services registered with that lookup service
+1 client using a cache to discover the services
+
+>>> phoenix -stop (or rmid -stop) to stop the lookup service
+>>> all 4 services eventually discard the lookup service
+>>> the client eventually discards the lookup service
+>>> restart phoenix (or rmid) before 30 minutes have expired
+ (to restart the lookup service and recover its state before
+ the client's original event registration [E0] has a chance
+ to expire)</pre>
+
+ When the client rediscovers the lookup service, its cache requests
+ a new event registration [E1]. But the lookup service still has E0
+ in its state.
+ <p>
+ When the services rediscover the lookup service, they reregister with
+ the lookup service, and the lookup service sends a serviceAdded
+ (<code>NOMATCH_MATCH</code>) event to both E0 and E1 for each of the
+ services. The cache's event listener receives both sets of events.
+ <p>
+ Prior to fixing this bug, <code>notifyServiceMap</code> only analyzed the sequence numbers of the events. It did not distinguish which event
+ registration each event corresponded to. Because E0 was recovered after
+ the lookup service went down and was restarted, the sequence numbers
+ of the events sent to that registration were greater than
+ <code>Integer.MAX_VALUE</code>, which resulted in a "gap" in the sequence so
+ that clients would know that they might have missed events. Because E1 was
+ not interrupted by a shutdown/restart, its sequence numbers started at 0. Thus, when serviceAdded events arrived for E0 and for E1, the sequence
+ looked something like the following to <code>notifyServiceMap</code>:
+
+<pre>event 0 --> Service0 added: Event ID = 0 - seq# 2147483650
+event 1 --> Service0 added: Event ID = 1 - seq# 0
+
+event 2 --> Service1 added: Event ID = 0 - seq# 2147483651
+event 3 --> Service1 added: Event ID = 1 - seq# 1
+
+event 4 --> Service2 added: Event ID = 0 - seq# 2147483652
+event 5 --> Service2 added: Event ID = 1 - seq# 2
+
+event 6 --> Service3 added: Event ID = 0 - seq# 2147483653
+event 7 --> Service3 added: Event ID = 1 - seq# 3</pre>
+
+ Because <code>notifyServiceMap</code> did not consider the event ID,
+ it appeared to <code>notifyServiceMap</code> that it was receiving a
+ stream of events in which the sequence numbers looked like:
+
+<pre>{ 2147483650, 0, 2147483651, 1, 2147483652, 2, 2147483653, 3 }</pre>
+
+ To <code>notifyServiceMap</code>, the sequence appeared to be
+ alternately "moving backward" and "moving forward" with a large
+ gap. In each case though, <code>notifyServiceMap</code> interpreted
+ the difference between sequence numbers as a gap; that is,
+
+<pre>(if event_(n+1)_seq# != 1 + event_n_seq#, then a gap is declared).</pre>
+
+ Thus, as each event was received, <code>notifyServiceMap</code>
+ declared a gap, and a new snapshot was requested; which meant that for
+ the four services, there were eight total snapshots requested.
+
+ To address this bug, the method <code>notifyServiceMap</code> was
+ modified to consider the event ID when determining whether or not
+ an event sequence contains a gap; which now results in the appropriate
+ behavior.
+ </dd>
+ <p>
+ <dt><b>6208587: SDM should create default LDM only when no DiscoveryManagement is configured</b><dt>
+ <dd> Prior to interrogating the configuration for a
+ <a href="../api/net/jini/discovery/DiscoveryManagement.html"> <code>DiscoveryManagement</code></a>
+ item (entry name = <b><i>discoveryManager</i></b>), a default
+ <a href="../api/net/jini/discovery/LookupDiscoveryManager.html"> <code>LookupDiscoveryManager</code></a>
+ is first created. Although that manager is initialized to discover no groups and no locators,
+ the <a href="../api/net/jini/discovery/LookupDiscovery.html"> <code>LookupDiscovery</code></a>
+ instance used by the default discovery manager to perform group discovery creates
+ a thread to listen for and process multicast announcements, as well as
+ additional, related threads. Thus, if a deployer configures a <i>discoveryManagement</i>
+ item, the creation of the default lookup discovery manager -- and the threads
+ that manager ultimately creates -- is unnecessary, and wastes resources.
+ <p>
+ This bug has been fixed.
+ </dd>
+ <p>
+ <dt> <b>Notes Of Interest</b>
+ <dd>
+ <p>
+ <b>Note 1: Service Reference Comparison</b>
+ <p>
+ The ability to appropriately compare two different service references
+ is very important to the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>
+ in general, and the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ in particular. Currently, there are three mechanisms used to accurately
+ compare service references. Each mechanism is applied in different situations,
+ to achieve different goals.
+ <p>
+ When storing and managing service references, it is important to be able
+ to determine when two different references (proxies) refer to the same
+ back-end service (such references are referred to as <i>duplicates</i>)
+ so that the storage and management of any duplicate references can be
+ avoided. In addition to identifying duplicate references, the ability to
+ determine when a previously discovered service has been replaced with a
+ new version is also important so that consistent state may be maintained, and entities that wish to know about such events can be informed.
+ Finally, when an entity wishes to discard (make eligible for rediscovery)
+ a particular service reference received from the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>,
+ it is important for the <code>LookupCache</code> to be able to compare the
+ reference provided by the entity to each of the previously stored references
+ so that the appropriate reference can be accurately selected for discard. <p>
+ <b>Comparison by <a href="../api/net/jini/core/lookup/ServiceID.html"> <code>net.jini.core.lookup.ServiceID</code></a></b>
+ <p>
+ To identify, and thus avoid storing, duplicate service references, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ compares the instances of <a href="../api/net/jini/core/lookup/ServiceID.html"> <code>ServiceID</code></a>
+ associated with each reference. Recall that an individual well-behaved service of
+ interest will usually register with multiple lookup services, and for
+ each lookup service with which that service registers, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ will receive a separate event containing a reference to the service. When the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ receives events from multiple lookup services, the
+ <a href="../api/net/jini/core/lookup/ServiceID.html"> <code>ServiceID</code></a>
+ (retrieved from the service reference in the event) is used to distinguish the
+ service references from each other. In this way, when a new event arrives containing
+ a reference associated with the same service as an already-stored reference,
+ the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ can determine whether or not the new reference is a duplicate; in which case, the
+ duplicate is ignored.
+ <p>
+ <b>Comparison by <a href="../api/net/jini/io/MarshalledInstance.html"> <code>net.jini.io.MarshalledInstance.fullyEquals</code></a></b>
+ <p>
+ With respect to determining when a previously discovered service has been
+ replaced with a new version, the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a> typically relies
+ on the event mechanism of the lookup service(s) with which that service is
+ registered to indicate that such an event has occurred. But there are
+ situations where the events from the lookup services do not provide enough
+ information to make such a determination. In those cases, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a> employs
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ to make the determination.
+ <p>
+ When a well-behaved service is replaced with a new version, the new
+ version is typically reregistered with each lookup service with
+ which the old version is registered. As described in the
+ <a href="../specs/html/lookup-spec.html"><i>Jini(TM) Lookup Service Specification</i></a>,
+ each lookup service with which this reregistration process occurs first
+ sends a service-removed event (<code>TRANSITION_MATCH_NOMATCH</code>), and
+ then sends a separate service-added event (<code>TRANSITION_NOMATCH_MATCH</code>).
+ In this case, there is no ambiguity, and thus no need for the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ to compare the new and old service references. This is because the
+ combination of service-removed and service-added events from each
+ lookup service is an explicit indication that the service has been
+ replaced. Note that, as described in the specification, the lookup
+ service only sends a service-changed event (<code>TRANSITION_MATCH_MATCH</code>)
+ when the attributes of the service have been modified; not when the
+ service itself has been changed (replaced). Thus, if the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ receives a <code>TRANSITION_MATCH_MATCH</code> event, then it is guaranteed
+ that the service referenced in that event has not been replaced with a new
+ version.
+ <p>
+ Whenever the following conditions are satisfied, the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ will use <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ to compare two service references:
+ <p>
+ <ul>
+ <li> The references are duplicates (same <a href="../api/net/jini/core/lookup/ServiceID.html"> <code>ServiceID</code></a>)
+ <li> The <b><i>possibility</i></b> exists that the references may refer to different versions of the service
+ </ul>
+ <p>
+ When determining whether or not these conditions (in particular, the
+ second condition) are satisfied, the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a> generally
+ takes a conservative approach. That is, only when it is absolutely
+ sure that two duplicates refer to the same version (such as when a
+ <code>TRANSITION_MATCH_MATCH</code> event is received), will the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ refrain from using
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ to compare the duplicate references; otherwise, duplicate references are
+ always compared using
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>.
+ <p>
+ One example of a situation where the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ employs <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ is the situation
+ where a lookup service of interest is newly discovered or rediscovered.
+ In this situation, the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ retrieves a snapshot of the services of interest that currently reside in that
+ lookup service. This is done so that previously undiscovered service references,
+ as well as new versions of previously discovered service references, can
+ both be stored, duplicates can be ignored, and clients can be sent the
+ appropriate notifications. Whenever a reference from the snapshot is a
+ duplicate of a previously discovered service reference, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ always compares the two references using
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>.
+ This is because the possibility always exists that the references may refer to different
+ versions of the service.
+ <p>
+ Another example of a situation where the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ employs <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ is when a <code>TRANSITION_NOMATCH_MATCH</code> event is received that
+ contains a reference that is a duplicate of a previously discovered
+ reference. When such an event is received, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ must allow for the possibility that the reference contained
+ in the event refers to a different version of the service
+ than that referenced by the previously discovered service reference.
+ This is because the event may represent either the second half of a
+ <code>TRANSITION_MATCH_NOMATCH</code>/<code>TRANSITION_NOMATCH_MATCH</code>
+ (remove/add) event pair, or it may be a notification of the initial
+ registration of a new version of the service with one of the (multiple)
+ lookup services targeted by the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ during the service discovery process.
+ <p>
+ To understand the last example described above, consider the situation
+ where a service initially registers with one lookup service and then
+ registers with a second lookup service. If the same version of the
+ service is registered with each lookup service, both lookup services
+ will send the same event -- a <code>TRANSITION_NOMATCH_MATCH</code>
+ event -- to indicate that a new service has registered with the
+ associated lookup service. In this case, there is no ambiguity for the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>;
+ the second reference can be safely ignored because the references are
+ duplicates that refer to the exact same service.
+ <p>
+ But suppose that prior to registering with the second lookup service,
+ the service is replaced with a new version. In that case, the second
+ lookup service will still send a <code>TRANSITION_NOMATCH_MATCH</code> event, but
+ if the appropriate action is not taken to determine that the old version
+ of the service has been replaced, the new version of the service will
+ be ignored by the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>.
+ This is because the two references will have the same
+ <a href="../api/net/jini/core/lookup/ServiceID.html"> <code>ServiceID</code></a>,
+ and thus the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ will identify the two references as duplicates; ultimately ignoring the new reference.
+ Of course, if the service is well-behaved, because the new version of the service will
+ eventually reregister with the first lookup service, that lookup service
+will
+ eventually send a <code>TRANSITION_MATCH_NOMATCH</code> event followed by a
+ <code>TRANSITION_NOMATCH_MATCH</code> event to indicate that the service
+has been
+ replaced. But the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ must still identify and handle this situation in order to prevent possible state
+ corruption, even though that corruption may be only temporary.
+ <p>
+ Thus, whenever a <code>TRANSITION_NOMATCH_MATCH</code> event is received
+and the
+ associated service reference is a duplicate of a previously discovered
+ reference, the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ will always compare the two references using
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>MarshalledInstance.fullyEquals</code></a>
+ to determine whether or not the references refer to the same version of the service.
+ When they do reference the same version, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ ignores the duplicate reference; otherwise, the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ sends a service-removed event followed by a service-added event to indicate
+ that the old version of the service has been replaced.
+ <p>
+ <b>Comparison by <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a></b>
+ <p>
+ The mechanism employed by the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a> to select (from
+ storage) a given reference for discard is the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ method provided by the discovered service itself. The
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ relies on the provider of each service to override the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ method with an implementation that allows
+ for the identification of the service reference an entity wishes to
+ be discarded. Although the default implementation of
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ often times may be sufficient for proper identification, service providers
+ are still encouraged to provide each service with its own well-defined
+ implementation of <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>.
+ <p>
+ In addition to the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ method, each service should also
+ provide a proper implementation of the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#hashCode"> <code>hashCode</code></a> method.
+ This is because references to the service may be stored in, or interact with,
+ container classes (for example,
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/HashMap.html"> <code>HashMap</code></a>)
+ where the service's <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ and <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#hashCode"> <code>hashCode</code></a>
+ methods may be invoked "under the covers" by the container object with
+ which the service is interacting. From the point of view of the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>
+ and the <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>,
+ providing an appropriate implementation for both the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#equals"> <code>equals</code></a>
+ method and the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#hashCode"> <code>hashCode</code></a>
+ method is a key characteristic of good behavior in a Jini service.
+
+ <p>
+ <b>Note 2: The Service Discovery Filtering Mechanism</b>
+ <p>
+ The specification of the
+ <a href="../api/net/jini/lookup/ServiceItemFilter.html"> <code>ServiceItemFilter</code></a>
+ interface specifies what it means to <i>filter</i> a service reference selected as a
+ candidate for discovery. In particular, instances of
+ <a href="../api/net/jini/lookup/ServiceItemFilter.html"> <code>ServiceItemFilter</code></a>
+ can be defined to perform proxy preparation. Thus, through the client-defined filter
+ (through the
+ <a href="../api/net/jini/lookup/ServiceItemFilter.html#check"> <code>check</code></a>
+ method), clients can request that the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>,
+ rather than the client itself, perform any desired proxy preparation
+ as part of the service discovery process.
+ <p>
+ To understand why this is important, consider what can happen when
+ the client performs preparation of its discovered proxies outside of the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>.
+ When proxy preparation is performed outside of the service discovery
+ manager, the client risks encountering a cycle where a matching service is
+ discovered by the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>,
+ is found to be untrusted when the client prepares the proxy, is discarded by the client because it is untrusted, and is then ultimately rediscovered
+ because it still matches the original discovery criteria. Such a cycle
+ will generally repeat indefinitely because the service is not likely to
+ become trusted at any point in the future. Supplying the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryManager.html"> <code>ServiceDiscoveryManager</code></a>
+ with the means to perform proxy preparation on the client's behalf
+ provides the client with a mechanism for avoiding such a cycle.
+ <p>
+ For more information, please refer to the section titled,
+ <i>SD.5.2 The <code>ServiceItemFilter</code> Interface</i>, contained in
+the
+ <a href="../specs/html/servicediscutil-spec.html"><i>Jini(TM) Service Discovery Utilities Specification</i></a>.
+
+ <p>
+ <b>Note 3: The Service Discovery Event Mechanism</b>
+ <p>
+ The specification of the
+ <a href="../api/net/jini/lookup/ServiceDiscoveryListener.html"> <code>ServiceDiscoveryListener</code></a>
+ interface describes how the filtering mechanism and the event mechanism provided by instances of
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>net.jini.lookup.LookupCache</code></a>
+ interact.
+ <p>
+ Additionally, this specification specifies that instances of the
+ <a href="../api/net/jini/lookup/LookupCache.html"> <code>LookupCache</code></a>
+ use the method
+ <a href="../api/net/jini/io/MarshalledInstance.html"> <code>net.jini.io.MarshalledInstance.fullyEquals</code></a>
+ to determine when a service has changed in some fundamental way (for example,
+ when a service is replaced with a new version).
+ <p>
+ For more information, please refer to the section titled,
+ <i>SD.5.4 The <code>ServiceDiscoveryListener</code> Interface</i>, contained in the
+ <a href="../specs/html/servicediscutil-spec.html"><i>Jini(TM) Service Discovery Utilities Specification</i></a>
+ <p>
+</dl>
+
+<!-- No issues for now
+<p>
+<H3>Known Issues (& Workarounds)</H3>
+ Currently, there are no known issues regarding the <code>ServiceDiscoveryManager</code>
+ utility.
+<p>
+-->
+
+</ul>
+<hr>
+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
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+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.
+
+</body>
+</html>