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 [4/23] - in
/incubator/river/site/trunk/content/river/docs: ./ release-notes/ specs/
specs/images/
Added: incubator/river/site/trunk/content/river/docs/release-notes/classdep.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/classdep.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/classdep.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/classdep.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,90 @@
+<!--
+ ! 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 ClassDep</title>
+
+<center>
+<h1><code>ClassDep</code><br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+<code>ClassDep</code> is used to analyze a set of classes and determine on
+what other classes they directly or indirectly depend.
+<H3>Changes since the v2.1.1 release</H3>
+<dl>
+ The new implementation no longer depends upon the Java SDK <code>tools.jar</code>
+ library, <a href ="http://asm.ow2.org/">ASM</a> is now used to provide
+ equivalent and extended functionality, including detecting dependencies
+ from Annotations and Generics. Note that if a static class (nested class)
+ is included in the dependency graph, references from that static class to
+ its immediate lexically enclosing class are included in the dependency
+ search now by default.
+</dl>
+
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-7'>RIVER-7</a>] -
+com.sun.jini.tool.ClassDep should be smarter with outer classes
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-8'>RIVER-8</a>] -
+com.sun.jini.tool.ClassDep empty inside collection doesn't work
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-78'>RIVER-78</a>] -
+ClassDep generates duplicate output lines
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-82'>RIVER-82</a>] -
+ClassDep generates duplicate output lines
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-302'>RIVER-302</a>] -
+ClassDep -newdirbehaviour option does not work
+</li>
+
+
+<H3>Changes since the v2.0.1 release</H3>
+<dl>
+<dt><b>Executable JAR file</b>
+<dd>There is a new executable JAR file, <code>classdep.jar</code>,
+that can be used to run <code>ClassDep</code>. The advantage of using
+this JAR file is that it automatically loads <code>tools.jar</code>
+from your Java(TM) 2 SDK installation, if required.
+</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/classserver.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/classserver.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/classserver.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/classserver.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,74 @@
+<!--
+ ! 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 ClassServer</title>
+
+<center>
+<h1><code>ClassServer</code><br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+<code>ClassServer</code> is a simple HTTP server for serving up JAR and
+class files.
+
+<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>Multiple Directory Support</b>
+<dd>The class server can now serve up files from multiple directories.
+The <code>-dir</code> (or <code>-dirs</code>) command line option
+and the <code>dirlist</code> constructor parameter now accept a list
+of directories to serve files from, with entries separated by the
+system path-separator character.
+<p>
+<dt><b>Executable JAR file</b>
+<dd>There is a new executable JAR file, <code>classserver.jar</code>,
+that can be used to run the class server.
+</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/comsunjinithread.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/comsunjinithread.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/comsunjinithread.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/comsunjinithread.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,133 @@
+<!--
+ ! 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 com.sun.jini.thread package
+ </title>
+</head>
+
+<body text="black" bgcolor="white" link="#9b37cc" vlink="#cc1877" alink="white">
+<center>
+<h1><code>com.sun.jini.thread</code> package<br>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<hr>
+<ul>
+<H3>Description</H3>
+
+The <code>com.sun.jini.thread</code> package contains various
+thread-related utility classes and interfaces. These classes and interfaces
+are not intended for general use, but are used internally by other parts of
+the Apache River release. Some of these classes
+and interfaces are exposed via the configuration mechanism.
+
+<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>
+
+A number of improvements have been made to the <a
+href="../api/com/sun/jini/thread/WakeupManager.html">
+<code>com.sun.jini.thread.WakeupManager</code></a>.
+<code>WakeupManager</code> instances are used to schedule tasks that need
+to be run in the future. Many of the services and utilities in the starter
+kit obtain the required <code>WakeupManager</code> instances from their
+configuration. <p>
+
+<dl>
+
+<dt><b>The <code>WakeupManager.ThreadDesc</code> Class Can Now Be More
+Usefully Subclassed and Has Been Made More Accessible</b>
+<dd>
+Instances of the <a href="../api/com/sun/jini/thread/WakeupManager.ThreadDesc.html"><code>
+<code>WakeupManager.ThreadDesc</code></a> class are used by
+<code>WakeupManager</code> to create threads. A <code>ThreadDesc</code>
+can be specified optionally when a <code>WakeupManager</code> is created,
+and/or when a task is scheduled that needs to be run in its own thread.
+The <a
+href="../api/com/sun/jini/thread/WakeupManager.ThreadDesc.html#thread(java.lang.Runnable)"><code>
+ThreadDesc.thread</code></a> method has been made public, which gives
+subclasses of <code>ThreadDesc</code> complete control over how threads are
+created and allows subclasses of <code>WakeupManager</code> to invoke
+the <code> ThreadDesc.thread</code> method.
+Also, public <a
+href="../api/com/sun/jini/thread/WakeupManager.ThreadDesc.html#getGroup()"><code>getGroup</code></a>,
+<a
+href="../api/com/sun/jini/thread/WakeupManager.ThreadDesc.html#isDaemon()"><code>isDaemon</code></a>,
+and <a
+href="../api/com/sun/jini/thread/WakeupManager.ThreadDesc.html#getPriority()"><code>getPriority</code></a>
+methods have been added to <code>ThreadDesc</code> and the default
+implementation of <code>ThreadDesc.thread</code> has been changed to use
+them. This work had been assigned issue numbers 5091282 and 6308590.
+<p>
+
+<dt><b>Protected Factory Method for
+<code>WakeupManager.Ticket</code>s Has Been Added to <code>WakeupManager</code></b>
+<dd>
+
+When a task is added to a <code>WakeupManager</code>, the caller gets a <a
+href="../api/com/sun/jini/thread/WakeupManager.Ticket.html"><code>WakeupManager.Ticket</code></a>
+object than can be used to remove the task if necessary. The protected
+method, <a
+href="../api/com/sun/jini/thread/WakeupManager.html#newTicket"><code>WakeupManager.newTicket</code></a>,
+has been added so subclasses of <code>WakeupManager</code> can create
+<code>Ticket</code> instances. This work had been assigned issue number
+6264220.
+<p>
+
+
+<dt><b><code>WakeupManager</code> Only Keeps Internal Thread Running When
+There Are Tasks Pending</b>
+<dd>
+
+Previous versions of <code>WakeupManager</code> always had one running
+(though often waiting) thread even if there were no pending tasks. This
+version of <code>WakeupManager</code> only creates its internal thread when
+the first task is enqueued. It will let this thread end, after a
+configurable timeout, if there are no tasks pending. This work had been
+assigned issue number 6190278.
+<p>
+
+</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/discovery.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/discovery.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/discovery.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/discovery.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,174 @@
+<!--
+ ! 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 Discovery Utilities Release Notes</title>
+
+<center>
+<h1>Jini Discovery Utilities<BR>
+Apache River v2.1.2 Release Notes</h1>
+</center>
+<HR>
+<UL>
+<H3>Description</H3>
+The Jini discovery utilities contain
+a set of discovery management interfaces that define the policies to
+apply when implementing helper utilities that manage an entity's
+discovery duties: in particular, the management of multicast (group)
+discovery and unicast (locator) discovery. The discovery management
+interfaces are:
+<p>
+ <ul>
+
+ <li> <a href="../api/net/jini/discovery/DiscoveryManagement.html"> <code>net.jini.discovery.DiscoveryManagement</code></a>
+ <li> <a href="../api/net/jini/discovery/DiscoveryGroupManagement.html"> <code>net.jini.discovery.DiscoveryGroupManagement</code></a>
+ <li> <a href="../api/net/jini/discovery/DiscoveryLocatorManagement.html"> <code>net.jini.discovery.DiscoveryLocatorManagement</code></a>
+ </ul>
+<p>
+The discovery utilities also include a set of standard helper utility
+classes that implement one or more of the discovery management
+interfaces. The helper utility classes are:
+<p>
+ <ul>
+ <li> <a href="../api/net/jini/discovery/LookupDiscovery.html"> <code>net.jini.discovery.LookupDiscovery</code></a>
+ <li> <a href="../api/net/jini/discovery/LookupLocatorDiscovery.html"> <code>net.jini.discovery.LookupLocatorDiscovery</code></a>
+ <li> <a href="../api/net/jini/discovery/LookupDiscoveryManager.html"> <code>net.jini.discovery.LookupDiscoveryManager</code></a>
+ </ul>
+<p>
+Additional classes and packages:
+<p>
+ <ul>
+ <li> <a href="../api/net/jini/discovery/ConstrainableLookupLocator.html">
+ <code>net.jini.discovery.ConstrainableLookupLocator</code></a>
+ <li> <a href="../api/com/sun/jini/discovery/package-summary.html">
+ <code>com.sun.jini.discovery</code></a>
+ </ul>
+<p>
+The <i>Jini Discovery Utilities Specification</i> is available in
+<a href="../specs/html/discoveryutil-spec.html">html</a>.
+
+<p>
+<H3>Changes since the v2.1.1 release</H3>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-17'>RIVER-17</a>] -
+Misleading logging message when discovery constraint checking is delayed
+</li>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-245'>RIVER-245</a>] -
+Unicast discovery should close socket in case of connection exception.
+</li>
+
+ <H3>Changes since the v2.0.1 release</H3>
+
+<dl>
+ <dt> <b>API additions and changes</b>
+ <dd> Changes to the <a href="../api/net/jini/discovery/package-summary.html">
+ <code>net.jini.discovery</code></a> package.
+ <ul>
+ <li>Parsing of the input URL and host name arguments in the corresponding <a href="../api/net/jini/discovery/ConstrainableLookupLocator.html">
+ <code>ConstrainableLookupLocator</code></a> and
+ <a href="../api/net/jini/core/discovery/LookupLocator.html">
+ <code>LookupLocator</code></a> constructors has been made stricter;
+ this may generate new <code>MalformedURLException</code>s. Note that
+ the implementation does not conform to the DJ 3.0 specification, which
+ requires parsing according to RFC 2396. The implementation is more
+ permissive and allows characters such as <code>'_'</code> in host names
+ to minimize backward incompatibility issues and anticipate compliance
+ with RFC 3986 (which obsoletes RFC 2396).
+ <li>
+ <code>ConstrainableLookupLocator</code> handles
+ <a href="../api/net/jini/core/constraint/ConnectionAbsoluteTime.html">
+ <code>ConnectionAbsoluteTime</code></a> and
+ <a href="../api/net/jini/core/constraint/ConnectionRelativeTime.html">
+ <code>ConnectionRelativeTime</code></a> constraints, enabling the
+ specification of timeouts on unicast discovery connection attempts.
+ <li>
+ <a href="../api/net/jini/discovery/LookupLocatorDiscovery.html">
+ <code>LookupLocatorDiscovery</code></a> handles any
+ <code>ConnectionRelativeTime</code> and <code>ConnectionAbsoluteTime</code>
+ constraints that may be set on the <code>LookupLocator</code>s passed into its
+ constructors.
+ <li>The
+ <a href="../api/net/jini/discovery/LookupDiscovery.html"> <code>LookupDiscovery</code></a>,
+ <code>LookupLocator</code>, <code>ConstrainableLookupLocator</code>, and
+ <code>LookupLocatorDiscovery</code> classes now try all the IP addresses
+ that a given host name may resolve to, instead of just the first one. This is as per the
+ recommendations in RFC 1123.
+ </ul>
+ <p>
+ Changes to the <a href="../api/com/sun/jini/discovery/package-summary.html">
+ <code>com.sun.jini.discovery</code></a> package.
+ <ul>
+ <li>
+ The <a href="../api/com/sun/jini/discovery/Discovery.html">
+ <code>Discovery</code></a> class now enables constraint checking to be optionally
+ delayed. With this change, constraint checks need not be performed as part of multicast
+ announcement or request decoding.
+ Discovery providers that support delayed constraint checking must implement the new
+ <a href="../api/com/sun/jini/discovery/MulticastAnnouncementDecoder.html">
+ <code>MulticastAnnouncementDecoder</code></a>
+ and <a href="../api/com/sun/jini/discovery/MulticastRequestDecoder.html"> <code>MulticastRequestDecoder</code></a> interfaces.
+ <li>
+ The <a href="../api/com/sun/jini/discovery/DiscoveryConstraints.html">
+ <code>DiscoveryConstraints</code></a> class supports processing of
+ <code>ConnectionRelativeTime</code> and <code>ConnectionAbsoluteTime</code>
+ constraints. Note that the processed constraints will no longer return
+ <code>ConnectionRelativeTime</code> and <code>ConnectionAbsoluteTime</code>
+ <code>ConnectionRelativeTime</code> and <code>ConnectionAbsoluteTime</code>
+ constraints. Note that the processed constraints will no longer return
+ <code>ConnectionRelativeTime</code> and <code>ConnectionAbsoluteTime</code>
+ as unfulfilled constraints.
+ </ul>
+ <p>
+
+ <dt> <b>Configuration</b>
+ <dd> The current implementation of the <code>LookupDiscovery</code>
+ utility now allows <code>ConnectionRelativeTime</code> and
+ <code>ConnectionAbsoluteTime</code> as part of its discovery constraints.
+
+
+<!-- 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/evseqnums.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/evseqnums.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/evseqnums.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/evseqnums.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,164 @@
+<!--
+ ! 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>Note on JavaSpaces Technology, Persistent Outrigger Services, and Event Sequence Numbers
+ </title>
+</head>
+
+<body text="black" bgcolor="white" link="#9b37cc" vlink="#cc1877" alink="white">
+<center>
+<h1>Note on JavaSpaces Technology, Persistent Outrigger Services, and Event Sequence Numbers
+</h1>
+</center>
+<p>
+Previously the <i>JavaSpaces Service Specification</i> required that
+event sequence numbers associated with spaces events to be <em>fully
+ordered</em>. Fully ordered, as defined in the <i>River Distributed
+Event Specification</i>, requires that:
+<blockquote>
+ ... not only do sequence numbers increase, but they are not
+ skipped. In such a case, if <code>RemoteEvent</code> <I>x</I>
+ and <I>y</I> have the same source and the same event
+ identifier, and <I>x</I> has sequence number <I>m</I> and
+ <I>y</I> has sequence number <I>n</I>, then if <I>m</I> <
+ <I>n</I> there were exactly <I>n</I>-<I>m</I>-1 events of the
+ same event type between the event that triggered <I>x</I> and
+ the event that triggered <I>y</I>. Such sequence numbers are
+ said to be "fully ordered."
+
+</blockquote>
+<p>
+In the Fall of 2000, we received feedback (from Asaf Kariv of GigaSpaces
+Technologies Ltd.) stating that requiring event sequence numbers to be fully
+ordered places too high a burden on implementors of the <i>JavaSpaces
+Service Specification</i> (GigaSpaces is a vender of a commercial JavaSpaces
+service implementation). For example, the guarantee requires a persistent
+implementation to store sufficient information <em>during</em> each
+<code>write</code> so that after a crash it can know the event
+registrations matched by that <code>write</code>. This requirement
+places a significant restriction on what implementation strategies are
+practical.
+<p>
+An additional wrinkle was that at the time, the persistent version of Outrigger
+itself did not generate fully ordered event sequence numbers in all cases.
+While we believe we could have fixed this issue in
+the Outrigger codebase with minimal performance impact, serving only
+our own needs would not promote our goal of having JavaSpaces
+implementations from a number of vendors.
+<p>
+After substantial discussions within the River Community(SM) for more than a
+year, we came to the conclusion that weakening the fully ordered guarantee
+would be unlikely to have significant negative impact on users of
+JavaSpaces technology. As a result, in the 1.2 FCS release,
+we changed the <i>JavaSpaces
+Service Specification</i> so that only the basic guarantee required by the
+<i>River Distributed Event Specification</i> on event sequences numbers
+is called for. This basic guarantee requires that all sequence numbers are
+unique and ordered, but that gaps in the sequence do not necessarily imply
+that events have been missed. Put another way, if two remote events
+<I>x</I> and <I>y</I> come from the same source and have the same event
+identifier, then <I>x</I> occurred before <I>y</I>, if and only if, the
+sequence number of <I>x</I> is less than the sequence number of <I>y</I>,
+but the difference between the two sequence numbers implies nothing about
+how many events may or may not have occurred between <I>x</I> and <I>y</I>.
+<p>
+A related issue is that previous editions of the <i>JavaSpaces Service
+Specification</i> specifically allowed implementations to "compress" event
+deliveries because sequence numbers were fully ordered. This rasises the
+questions — is compression still allowed? and should we be
+calling it out in the specification? It was decided that the event
+specification does allow for event notifications to be dropped even when
+only the basic sequence number guarantee is present, and that it was not
+necessary to call this possibility out in the <i>JavaSpaces Service
+Specification</i>.
+
+<h2>What This Means for Persistent Outrigger Services</h2>
+
+As alluded to above, the persistent version of Outrigger did not generate
+fully ordered sequence numbers in all cases; indeed, in these cases it did
+not even meet the basic guarantee because it sometimes assigned the same
+sequence number to different events. What was especially troubling is that,
+in these cases, the client had no way of detecting that the same sequence
+number had been assigned to more than one event.
+<p>
+In the 1.2 beta release, Outrigger was changed to be
+<em>delta-well-ordered</em>. With delta-well-ordered sequence
+numbers, if two remote events <I>x</I> and <I>y</I> with the same type and
+source have sequence numbers that differ by less than some delta <I>D</I>
+(typically a large number), then the number of intervening values between
+the sequence numbers of <I>x</I> and <I>y</I> would be equal to the number
+of intervening events. If the difference is larger than <I>D</I>, then no
+inference about the number of intervening events could be made.
+<p>
+More formally, the characterization is:
+<blockquote>
+
+ Let <I>e</I>(<I>n</I>) and <I>e</I>(<I>m</I>) be notifications of
+ an event of type <I>e</I> from the same event generator with
+ sequence numbers <I>n</I> and <I>m</I>, and let <I>D</I> be some
+ integer. If |<I>n</I> - <I>m</I>| < <I>D</I>, then the number of
+ events that occurred between the events that triggered
+ notifications <I>e</I>(<I>n</I>) and <I>e</I>(<I>m</I>) is
+ |<I>n</I> - <I>m</I>| - 1.
+
+</blockquote>
+<p>
+The delta-well-ordered guarantee lets the implementation deliver a
+fully ordered guarantee where possible, but not where it becomes too
+burdensome. For example, a persistent implementation might be fully
+ordered in the usual case, incrementing the sequence number by one, but
+efficient during crash recovery by incrementing the sequence number by
+<I>D</I>.
+<p>
+
+In Outrigger, we insert a delta only after the server comes up from a
+crash (Reggie uses a similar implementation strategy).
+<p>
+
+Note that this will affect any existing code that assumes it can
+calculate the number of intervening events by subtracting sequence
+numbers. If your existing code is using persistent Outrigger
+across a crash, such code might be surprised to suddenly find
+that a few billion events seem to have transpired while it wasn't
+looking. The discussions within the River Community have yet to locate a
+critical dependency of this form, but one is possible.
+
+<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/execpolicy.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/execpolicy.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/execpolicy.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/execpolicy.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,457 @@
+<!--
+ ! 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.
+ !-->
+<HTML>
+<HEAD>
+<TITLE>Security requirements for specifying an Activation Group Descriptor</TITLE>
+</HEAD>
+<BODY LINK="#0000ff" VLINK="#800080" BGCOLOR="#ffffff">
+<H1 ALIGN="CENTER">Security Requirements on Activation Group Descriptors used with <code>phoenix</code> or <code>rmid</code>
+</H1>
+ <ul>
+
+<p>Some Jini network technology-based services may be activatable and
+as such will require the use of an activation daemon. The standard
+Java(TM) 2 Standard Edition (J2SE(TM)) Remote Method Invocation (Java RMI) activation daemon is
+<code>rmid</code>. The Apache River release
+provides <code>phoenix</code>, an alternative
+configurable implementation of a Java RMI activation daemon.
+
+<p>This note describes the security requirements to specify an
+activation group descriptor (of type
+<code>java.rmi.activation.ActivationGroupDesc</code>) for use with
+activatable objects handled by either <code>phoenix</code> or
+<code>rmid</code>.
+
+<p><i>Note</i>: We encourage developers to transition from <code>rmid</code>
+and to use its configurable alternative <code>phoenix</code>
+instead. The <code>phoenix</code> activation daemon supports
+configurable exporters for the remote objects that are part of the
+activation system and also supports flexible access control policies
+for the activation system. See the <code>com.sun.jini.phoenix</code>
+package documentation for details on configuring and starting
+<code>phoenix</code>.
+
+<p>
+<H2>
+Introduction and Rationale
+</H2>
+<P>
+ An activation daemon, such as <code>phoenix</code> or
+ <code>rmid</code>, executes subprocesses which run virtual machines
+ for the Java platform (VMs). It does this to
+ keep activation groups separate from one another, and to allow the
+ use of special VM engines and options for different activation
+ groups.
+<P>
+ An activation group is specified by an activation group descriptor
+ that describes the information necessary for an
+ activation daemon to start the activation group. An application
+ can register an activation group descriptor (of type
+ <code>ActivationGroupDesc</code>) directly with the
+ <code>ActivationSystem</code> of either <code>phoenix</code> or
+ <code>rmid</code> by calling the <code>ActivationSystem</code>'s
+ <code>registerGroup</code> method. Alternatively, an activation
+ group can be registered via the service starter API, by invoking
+ the <code>create</code> method on a
+ <code>com.sun.jini.start.SharedActivationGroupDescriptor</code>
+ instance. As a side effect of this invocation, an
+ <code>ActivationGroupDesc</code> is created and registered with the
+ <code>ActivationSystem</code> as above.
+<p>
+ An activation group descriptor used to start an activation
+ group affects the subprocess environment, command,
+ command options, and arguments for starting the activation group,
+ and is flexible enough that with an insecure security policy, any
+ command, even a non-Java-platform command or program, can be run
+ under the guise of starting the group. There is clearly a need
+ for a security control to prevent unauthorized specification of an
+ activation group descriptor and hence unauthorized execution
+ of a command. Note that whether an activation group is
+ registered directly with the <code>ActivationSystem</code> or
+ registered indirectly as a result of the
+ <code>SharedActivationGroupDescriptor.create</code> method, the
+ security requirements outlined below are the same for each situation.
+<P>
+ The activation daemons <code>phoenix</code> and <code>rmid</code>
+ have different schemes for preventing an unauthorized
+ activation group descriptor from being used. The <code>phoenix</code>
+ activation daemon may be configured with an access control policy
+ on its <code>ActivationSystem</code> that prevents an unauthorized
+ <code>ActivationGroupDesc</code> from either being registered via the
+ <code>ActivationSystem.registerGroup</code> method or being
+ modified via the <code>ActivationSystem.setActivationGroupDesc</code>
+ method. The <code>rmid</code> activation daemon has a slightly
+ different control point: it verifies that an
+ <code>ActivationGroupDesc</code> is authorized (according to
+ <code>rmid</code>'s security policy) just before
+ using it to create an activation group. The details of each access
+ control model are discussed in turn below. Although
+ <code>phoenix</code> and <code>rmid</code> have different points in
+ which they check permissions for such access, the basic permission
+ requirements are the same. Also, the permission types that
+ <code>phoenix</code> uses are modeled after the permission types
+ used by <code>rmid</code> (<code>ExecPermission</code> and
+ <code>ExecOptionPermission</code>); each permission type has the
+ same class name, but is in a different package.
+
+<p>
+<hr>
+<H2>
+<code>phoenix</code>
+</H2>
+
+<p>Since applications need to configure the access control policy for
+registering and updating an activation group descriptor with the
+<code>ActivationSystem</code>, the <code>phoenix</code> implementation
+includes a special <code>net.jini.export.Exporter</code>
+implementation for the <code>ActivationSystem</code>,
+<code>com.sun.jini.phoenix.SystemAccessExporter</code>, that allows
+the <code>ActivationSystem</code>'s access control policy to be
+configured. The <code>phoenix</code> implementation also includes a
+<code>net.jini.jeri.InvocationLayerFactory</code> implementation,
+<code>com.sun.jini.phoenix.SystemAccessILFactory</code>, to use with
+<code>net.jini.jeri.BasicJeriExporter</code>. This
+<code>InvocationLayerFactory</code> implementation supports the same
+configurable access control policy for the
+<code>ActivationSystem</code>.
+
+<p>By default, <code>phoenix</code>'s <code>ActivationSystem</code> is
+exported via <code>BasicJeriExporter</code> with a
+<code>SystemAccessILFactory</code> that produces a
+<code>net.jini.jeri.Dispatcher</code> that enforces an access control
+policy on calls to the <code>registerGroup</code> and
+<code>setActivationGroupDesc</code> methods. The default access
+control policy is specified by the
+<code>com.sun.jini.phoenix.DefaultGroupPolicy.checkGroup</code>
+method.
+
+<p>This default group policy requires the following when an
+<code>ActivationGroupDesc</code> is being recorded via the
+<code>registerGroup</code> or <code>setActivationGroupDesc</code>
+method:
+<p>
+<ul>
+<li>The group class name in the descriptor is either
+<code>null</code> (indicating the default) or specifically
+<code>com.sun.jini.phoenix.ActivationGroupImpl</code>.
+
+<li>For each property in the descriptor's property overrides, the
+calling context is granted the permission
+<code>com.sun.jini.phoenix.ExecOptionPermission</code> with a target
+of the form "-D<i>name</i>=<i>value</i>" (where <i>name</i> is the
+name of the property and <i>value</i> is the value of the property).
+
+<li>If the descriptor contains a non-<code>null</code> command
+environment, the calling context is granted the permission
+<code>com.sun.jini.phoenix.ExecPermission</code> with the command path
+as the target. Also, for each command option, the calling context is
+granted <code>ExecOptionPermission</code> with the option as a target.
+</ul>
+
+<p>These permissions must be specified in <code>phoenix</code>'s security
+policy file, indicated on the command line when starting up
+<code>phoenix</code>:
+
+<pre>
+java -J-Djava.security.policy=<i>configDir</i>/phoenix.policy
+ -J-Djava.rmi.server.codebase=<i>codebasePath</i> [<i>otherOptions</i>]
+ -jar <i>installDir</i>/lib/phoenix.jar <i>configOptions</i>
+</pre>
+
+where <i>configDir</i> is the directory containing
+<code>phoenix</code>'s security policy file, <i>codebasePath</i> is a
+codebase path (space-separated list of URLs that serves up
+<code>phoenix</code>'s download JAR file
+(<i>installDir</i><code>/lib/phoenix-dl.jar</code>),
+<i>otherOptions</i> are any other standard options for the
+<code>java</code> command, and <i>configOptions</i> are the options
+(typically a filename or URL) of a <code>phoenix</code> configuration.
+
+<p>Some things to keep in mind when defining permissions
+for <code>phoenix</code> are:
+<p> <ul>
+
+<li>Although in many cases all or part of the command line will be
+case insensitive (e.g. host names, files, and command paths on some
+operating systems), the checks <code>ExecPermission</code> and
+<code>ExecOptionPermission</code> perform are case sensitive, so it is
+important to make sure the case of the targets of the
+<code>ExecPermission</code>s and <code>ExecOptionPermission</code>s
+match the case of the command line elements in the
+<code>ActivationGroupDesc.CommandEnvironment</code>.
+
+<li>Because <code>phoenix</code> can be configured to support
+authentication and access control, it may be reasonable to grant more
+broad <code>ExecPermission</code>s and
+<code>ExecOptionPermission</code>s to a narrow set of trusted
+subjects.
+
+</ul>
+
+<p>Note that the permission class names <code>ExecPermission</code>
+and <code>ExecOptionPermission</code> are the same as those used for
+<code>rmid</code>'s access control policy except for the package name,
+which, for <code>phoenix</code>, is <code>com.sun.jini.phoenix</code>.
+The <a href="#examples"> examples given for <code>rmid</code></a>
+below are the same as for <code>phoenix</code> except that the package
+name for the permissions needs to be changed to
+<code>com.sun.jini.phoenix</code>.
+
+<p>
+<hr>
+<H2>
+<code>rmid</code>
+</H2>
+
+<P>
+ In releases of the Java 2 SDK prior to 1.2.2_006, the need to
+ control the security of an <code>ActivationGroupDesc</code> was
+ satisfied by the same stopgap measure used for
+ <CODE>rmiregistry</CODE> access control: if the caller was running
+ on the same host as the remote object, then all access was allowed;
+ otherwise, no access to sensitive functions was allowed.
+ Registering or changing an <CODE>ActivationGroupDesc</CODE> is an
+ example of a sensitive function; activating an object is an example
+ of a non-sensitive function that anyone can perform. This security
+ mechanism was predicated on the assumption that unprivileged code is
+ not allowed to connect to port 1098 on the executing host.
+<P>
+ However, that assumption is no longer as certain, and a
+ stronger security model has been developed. In this new model, an extra security control has been added:
+ before being executed, the command and options requested by an
+ <CODE>ActivationGroupDesc</CODE> are checked by the security manager
+ of <CODE>rmid</CODE>, which then references the security policy file
+ that was set for <CODE>rmid</CODE> from the command line (for
+ authorization).
+<P>
+ An "exec policy" is a Java class employed by the Java RMI activation
+ daemon to check commands and command-line options used to launch a
+ VM when deciding whether or not an <CODE>ActivationGroupDesc</CODE>
+ is authorized. The exec policy is adopted when <CODE>rmid</CODE> is
+ started. The value of the <code>sun.rmi.activation.execPolicy</code>
+ property dictates the policy that <code>rmid</code> uses to
+ determine whether or not the information in an
+ <code>ActivationGroupDesc</code> may be used to launch a VM
+ for an activation group. Some exec policies are built into
+ <CODE>rmid</CODE>, and <CODE>rmid</CODE> can be instructed to use
+ one of them by defining a property that specifies a built-in policy
+ instead of the exec policy's class name.
+<P>
+ In the exec policy represented by the value <CODE>none</CODE>
+ (discussed later, in the section, <a href="#prev"><i>How to achieve the
+ behavior of </i><code>rmid</code><i> released in previous versions of the
+ Java 2 SDK</i></a>), the new security control is disabled, and
+ execution is compatible with the <CODE>rmid</CODE> found in previous
+ releases of the Java 2 SDK.
+<P>
+ In the default exec policy (discussed in the section, <a
+ href="#assign"><i>How to assign and maintain security
+ controls</i></a>), the authorized commands and options are encoded
+ in the security policy file, which gets set using the
+ "<CODE>-J-Djava.security.policy=...</CODE>" option on the
+ <CODE>rmid</CODE> command line. Each command and option string in
+ each <CODE>ActivationGroupDesc</CODE> is separately authorized or
+ unauthorized. While there is no authentication of a caller (an
+ authorized option is authorized for everyone's use), there is still
+ a check to ensure that the registration of the
+ <CODE>ActivationGroupDesc</CODE> originates from the local host.
+<P>
+ The exec policy can be set to the name of another class that
+ <CODE>rmid</CODE> will instantiate; the exec policy object will then
+ be expected to perform the security check on
+ <CODE>ActivationGroupDesc</CODE>s at group activation time. This
+ option is the most flexible, but discussion of its use is beyond the
+ scope of this document. See the <CODE>rmid</CODE> tool documentation
+ (manpage) for details, at:
+<pre><a name="manpages">
+ <a href="http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/rmid.html">http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/rmid.html</a>
+</pre>
+ and
+
+<pre> <a href="http://java.sun.com/j2se/1.4/docs/tooldocs/windows/rmid.html">http://java.sun.com/j2se/1.4/docs/tooldocs/windows/rmid.html</a>
+</pre>
+<P>
+<H3><a name="prev">
+How to achieve the behavior of <code>rmid</code> released in
+previous versions of the Java 2 SDK</a></H3>
+<P>
+ The new security control can be effectively bypassed by assigning an
+ exec policy that permits all commands and all options. There is a
+ short way to specify this behavior by setting the exec policy value
+ to <CODE>none</CODE>:
+<pre>
+ rmid -J-Dsun.rmi.activation.execPolicy=none</pre>
+
+ which will run <CODE>rmid</CODE> in the normal way, but will
+ automatically authorize all <CODE>ActivationGroupDesc</CODE>s
+ registered from the local host.
+
+<P>
+ For the user who can control the <CODE>rmid</CODE> host to guarantee the
+ assumptions of Java 2 SDK, v1.2.x, or who is simply impatient with the new
+ security control, the <CODE>none</CODE> keyword is a convenient way to get
+ <CODE>rmid</CODE> up and running quickly. Remember that this is a way to
+ sacrifice security for temporary convenience, and therefore is not
+ recommended.
+<P>
+<H3><a name="assign">
+How to assign and maintain security controls
+</a></H3>
+<P>
+ The default exec policy is used if the
+ <CODE>sun.rmi.activation.execPolicy</CODE> system property is not
+ set for the <CODE>rmid</CODE> tool, or if the value of the
+ <CODE>execPolicy</CODE> property is set to <CODE>default</CODE>. In
+ this case, a security policy file must be specified on
+ <CODE>rmid</CODE>'s command line.
+<P>
+ In the default case, the <CODE>java.security.policy</CODE> system
+ property must be set for <CODE>rmid</CODE>. For example on a Microsoft Windows platform:
+<pre>
+ rmid -J-Djava.security.policy=<var><b>configDir</b></var>\rmid.policy</pre>
+<P>
+ The file named as the value of this property should contain a
+ Java 2 platform security policy file. An example which has
+ appropriate syntax for the Microsoft Windows platform is:
+<pre>
+ grant {
+ // permissions granted to everyone
+ permission com.sun.rmi.rmid.ExecPermission "C:\\jdk\\bin\\java_g";
+ permission com.sun.rmi.rmid.ExecOptionPermission "-Djava.security.policy=<var><b>configDir</b></var>\\lookup.policy";
+ };
+</pre>
+<P>
+ The two permission types shown above, <code>ExecPermission</code>
+ and <code>ExecOptionPermission</code>, are the only two security
+ permissions relevant to the new security control. Notice that they
+ are granted to all codebases (<CODE>grant {</CODE>): you should
+ always be cautious when granting permissions to all codebases,
+ because these permissions are also granted to unknown downloaded
+ code. See <a href="#manpages">the <code>rmid</code> reference
+ pages</a> for a complete description of the syntax for these
+ permissions.
+<P>
+ The straightforward way to build up an effective
+ <CODE>rmid.policy</CODE> is:
+<OL>
+ <LI> Start with an empty <CODE>rmid.policy</CODE>.
+
+ <LI> Run <CODE>rmid -J-Djava.security.policy=rmid.policy</CODE>.
+
+ <LI> Run a client program to activate an object (you might need to
+ register the object if you haven't already).
+
+ <LI> Catch and <CODE>printStackTrace</CODE> the
+ <CODE>AccessControlException</CODE> that gets
+ thrown by the activation attempt (usually the client program will
+ do this anyway).<br>
+<P>
+<B> Note on restartable <CODE>Activatable</CODE> objects:</B> Some
+ activatable objects are activated automatically by
+ <CODE>rmid</CODE> (if
+ <CODE>ActivationDesc.getRestartMode()</CODE> is
+ <CODE>true</CODE>); in this case, <CODE>rmid</CODE> will
+ <CODE>printStackTrace</CODE> the exception to its
+ <CODE>System.err</CODE>, preceded by the English-language
+ message "<CODE>rmid: unable to restart service</CODE>".
+<P>
+
+
+ <LI> Look in the <CODE>AccessControlException</CODE> to see the failed exception.
+ For example, the exception:
+<CODE><blockquote>
+ java.security.AccessControlException: access denied (com.sun.rmi.rmid.ExecOptionPermission -cp)
+</blockquote></CODE>
+ means that the permission you need to add to the security policy
+ file is:
+<pre>
+ grant {
+ permission com.sun.rmi.rmid.ExecOptionPermission "-cp";
+ };
+</pre>
+ <LI> Kill the <CODE>rmid</CODE> process (<code>rmid -stop</code>)
+ and return to step 2.
+</OL>
+
+<P>
+<H3><a name="examples">
+Specific examples for some River technology-enabled service implementations
+</H3>
+<P>
+Here's an example of an <CODE>rmid.policy</CODE> which will run Reggie (the
+contributed River lookup service implementation from Sun Microsystems) in the Solaris(TM) Operating System (Solaris OS):
+<PRE>
+ grant {
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.security.policy=<var><b>configDir</b></var>/lookup.policy";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.rmi.server.codebase=*";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-cp";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "<var><b>installDir</b></var>/lib/reggie.jar";
+ };
+</PRE>
+<P>
+Here's an example to run Mahalo (the contributed River transaction
+manager service implementation from Sun Microsystems) in the Solaris OS:
+<PRE>
+ grant {
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.security.policy=<var><b>configDir</b></var>/txn.policy";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.rmi.server.codebase=*";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-cp";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "<var><b>installDir</b></var>/lib/mahalo.jar";
+ };
+</PRE>
+<P>
+Here's one for <CODE>FrontEndSpace</CODE> (a contributed implementation of
+JavaSpaces technology from Sun Microsystems) in the Solaris OS:
+<PRE>
+ grant {
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.security.policy=<var><b>configDir</b></var>/books.policy";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Djava.rmi.server.codebase=*";
+ permission com.sun.rmi.rmid.ExecOptionPermission
+ "-Xbootclasspath/p::<var><b>installDir</b></var>/lib/outrigger.jar:<var><b>installDir</b></var>/lib/transient-outrigger.jar:<var><b>installDir</b></var>/lib/pro.zip";
+ };
+</PRE>
+</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/fiddler.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/release-notes/fiddler.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/release-notes/fiddler.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/release-notes/fiddler.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,207 @@
+<!--
+ ! 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 Fiddler</title>
+<center><h1>Fiddler
+ <BR>v2.1.2 Release Notes
+</h1></center>
+<hr>
+<UL>
+<H3>Description</H3>
+"Fiddler" is the name of the contributed Jini technology lookup discovery
+service implementation from Sun Microsystems. The <i>River Lookup
+Discovery Service Specification</i> is available in <a
+href="../specs/html/lds-spec.html">html</a>.
+<p>
+The specification for Fiddler is defined not only by the <i>River Lookup
+Discovery Service Specification</i>, but also by the API
+documentation (generated by the Javadoc(TM) tool) for
+<a href="../api/com/sun/jini/fiddler/FiddlerAdmin.html"> <code>com.sun.jini.fiddler.FiddlerAdmin</code></a>
+and
+<a href="../api/net/jini/admin/Administrable.html"> <code>net.jini.admin.Administrable</code></a>.
+<p>
+<H3>Changes since the v2.1.1 release</H3>
+<li>[<a href='https://issues.apache.org/jira/browse/RIVER-234'>RIVER-234</a>] -
+(DOC) Fiddler manpage directions for HTTP server should reference
+classserver.jar, not tools.jar
+</li>
+<H3>Changes since the v2.1 release</H3>
+<dl>
+ <dt> <b>None</b></dt>
+</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/fiddler/package-summary.html#fiddlerConfigEntries"> man page</a>.
+ <p>
+
+ <dt> <b>Logging</b>
+ <dd> In this release, no changes have occurred with respect to the logging mechanism
+ employed by Fiddler; 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.fiddler</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/fiddler/package-summary.html#fiddlerLoggers"> man page</a>.
+ <p>
+
+ <dt> <b>Bug Fixes of Interest</b>
+ <dd> A number of bugs have been addressed in this release of Fiddler.
+ What follows is a description of those bugs that might be of
+ interest:
+ <p>
+
+ <dt><b>4874580: FiddlerImpl throws NullPointerException in prepareNewLocators
+if locs is null</b><dt>
+ <dd> When calling the <code>register</code> method, if <code>null</code>
+ is passed as the value of the <code>locators</code> parameter,
+ a <code>NullPointerException</code> occurs.
+ <p>
+ This bug has been fixed.
+ </dd>
+ <p>
+ <dt><b>4979612: Fiddler relies on LookupLocator.equals to determine interest in discovered Regs</b><dt>
+ <dd> When Fiddler searches through its set of client registrations to
+ determine if any of those registrations are interested in a particular
+ previously discovered lookup service, it compares the locators of
+ interest from each registration to the locator that is returned by a call to <code>getLocator</code> on the discovered lookup service. That
+ comparison is done using <code>LookupLocator.equals</code>.
+ <p>
+ <code>LookupLocator.equals</code> employs a case-insensitive string
+ compare of the host names of the locators to determine equality. Thus,
+ if one locator is associated with a hostname of "myHost",
+ and the other locator is associated with a fully qualified hostname like
+ "myHost.myCompany.com", <code>LookupLocator.equals</code> will return
+ <code>false</code>, and Fiddler will view as different, locators that
+ should actually be considered the same.
+ <p>
+ To address this bug, the implementation in this release now employs
+ the same strategy that <code>URL</code> currently employs. That is,
+ it first applies <code>LookupLocator.equals</code> (to do a case-insensitive
+ string compare). If the call to <code>LookupLocator.equals</code> returns <code>false</code>, then the IP addresses associated with each locator
+ are retrieved and compared to determine equality.
+ </dd>
+ <p>
+ <dt><b>4984939: Fiddler threads should guard against lost interrupts</b><dt>
+ <dd> Thread subclasses in Fiddler that use logging and do not override the
+ <code>Thread.interrupt</code> method to set an "interrupted" field are
+ susceptible to lost interrupts. This is because <code>java.util.logging</code>
+ swallows internal <code>InterruptedIOException</code>s without setting
+ the receiving thread's interrupted status; effectively 'forgetting' the
+ interrupt that occurred. The end result is that some of Fiddler's threads could endlessly loop instead of terminate, causing shutdown processing
+ in Fiddler to hang.
+ <p>
+ This bug has been fixed.
+ </dd>
+ <p>
+ <dt><b>5042473: FiddlerImpl.SetLocatorsTask handles NO_LOCATORS incorrectly</b><dt>
+ <dd> Prior to this release, when a client requested that locator discovery
+ be "turned off" by requesting the replacement of a registration's
+ locators-of-interest with the empty set (through an invocation of
+ the <code>setLocators</code> method), the result was the opposite
+ of what the specification prescribes. That is, the
+ locators-of-interest were <b>not</b> replaced at all.
+ <p>
+ This bug has been fixed.
+ </dd>
+ <p>
+ <dt><b>5049735: Fiddler should properly handle remote calls that arrive before init completes</b><dt>
+ <dd> Prior to this release, Fiddler contained no logic to ensure that
+ remote calls received before initialization completes would be handled
+ properly. Problems could occur, for example, if an instance of Fiddler is run with a well-known endpoint that was used (and advertised) by a
+ previous instance of Fiddler.
+ <p>
+ To address this issue, Fiddler now handles such "early" calls by blocking until initialization completes.
+ </dd>
+ <p>
+ <dt><b>6226306: Fiddler should allow null loginContext config entry, performing no JAAS login when null</b><dt>
+ <dd> Prior to this release, if Fiddler's configuration included a
+ <b><i>loginContext</i></b> entry, Fiddler would require that
+ entry to be non-<code>null</code>; throwing an exception if
+ a <code>null</code> value were entered. (Note that if the entry
+ were simply absent from the configuration, Fiddler interpretted
+ this as an indication that no JAAS login should be performed.)
+ <p>
+ To address this issue, Fiddler now interprets a <code>null</code>
+ value for the <i>loginContext</i> entry, as well as an absent
+ entry, as an indication that a JAAS login should not be performed.
+ </dd>
+ <p>
+ <dt> <b>Notes Of Interest</b>
+ <dd>
+ <p>
+ <b>Fiddler Has 3 Modes of Execution</b>
+ <p>
+ <ul>
+ <li> <i>Transient</i> - Fiddler does not persist its state and is not activatable
+ <li> <i>Nonactivatable</i> - Fiddler does persist its state but is not
+activatable
+ <li> <i>Activatable</i> - Fiddler persists its state and is activatable </ul>
+ For details, see the
+ <a href="../api/com/sun/jini/fiddler/package-summary.html"> <code>com.sun.jini.fiddler</code></a>
+ package documentation.
+ <p>
+
+</dl>
+
+
+
+<!-- No issues for now
+<p>
+<H3>Known Issues (& Workarounds)</H3>
+ Currently, there are no known issues regarding this implementation of
+ the lookup discovery service.
+<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>
+
+
+