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/01/05 18:12:27 UTC
svn commit: r896131 [4/6] - in /incubator/river/jtsk/trunk/doc: ./
release-notes/ specs/html/
Modified: incubator/river/jtsk/trunk/doc/specs/html/js-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/js-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/js-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/js-spec.html Tue Jan 5 17:12:26 2010
@@ -60,7 +60,7 @@
<a name="27387"> </a>JS.1.1 The JavaSpaces Application Model and Terms
</h4>
<p class="Body">
- <a name="27409"> </a>A JavaSpaces service holds <em class="Emphasis">entries</em>. An entry is a typed group of objects, expressed in a class for the Java platform that implements the interface <code>net.jini.core.entry.Entry</code>. Entries are described in detail in the <a href="entry-spec.html"><em class="Emphasis">Jini Entry Specification</em></a>.
+ <a name="27409"> </a>A JavaSpaces service holds <em class="Emphasis">entries</em>. An entry is a typed group of objects, expressed in a class for the Java platform that implements the interface <code>net.jini.core.entry.Entry</code>. Entries are described in detail in the <a href="entry-spec.html"><em class="Emphasis">River Entry Specification</em></a>.
</p>
<p class="Body">
<a name="27420"> </a>An entry can be <em class="Emphasis">written</em> into a JavaSpaces service, which creates a copy of that entry in the space<a href="#27423"><sup>2</sup></a> that can be used in future lookup operations.
@@ -72,16 +72,16 @@
<a name="27463"> </a>There are two kinds of lookup operations: <em class="Emphasis">read</em> and <em class="Emphasis">take</em>. A <em class="Emphasis">read</em> request to a space returns either an entry that matches the template on which the read is done, or an indication that no match was found. A <em class="Emphasis">take</em> request operates like a read, but if a match is found, the matching entry is removed from the space.
</p>
<p class="Body">
- <a name="27464"> </a>You can request a JavaSpaces service to <em class="Emphasis">notify</em> you when an entry that matches a specified template is written. This is done using the distributed event model contained in the package <code>net.jini.core.event</code> and described in the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>.
+ <a name="27464"> </a>You can request a JavaSpaces service to <em class="Emphasis">notify</em> you when an entry that matches a specified template is written. This is done using the distributed event model contained in the package <code>net.jini.core.event</code> and described in the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a>.
</p>
<p class="Body">
<a name="2902"> </a>All operations that modify a JavaSpaces service are performed in a transactionally secure manner with respect to that space. That is, if a write operation returns successfully, that entry was written into the space (although an intervening take may remove it from the space before a subsequent lookup of yours). And if a take operation returns an entry, that entry has been removed from the space, and no future operation will read or take the same entry. In other words, each entry in the space can be taken at most once. Note, however, that two or more entries in a space may have exactly the same value.
</p>
<p class="Body">
- <a name="2903"> </a>The architecture of JavaSpaces technology supports a simple transaction mechanism that allows multi-operation and/or multi-space updates to complete atomically. This is done using the two-phase commit model under the default transaction semantics, as defined in the package <code>net.jini.core.transaction</code> and described in the <a href="txn-spec.html"><em class="Emphasis">Jini Transaction Specification</em></a>.
+ <a name="2903"> </a>The architecture of JavaSpaces technology supports a simple transaction mechanism that allows multi-operation and/or multi-space updates to complete atomically. This is done using the two-phase commit model under the default transaction semantics, as defined in the package <code>net.jini.core.transaction</code> and described in the <a href="txn-spec.html"><em class="Emphasis">River Transaction Specification</em></a>.
</p>
<p class="Body">
- <a name="2966"> </a>Entries written into a JavaSpaces service are governed by a lease, as defined in the package <code>net.jini.core.lease</code> and described in the <a href="lease-spec.html"><em class="Emphasis">Jini Distributed Leasing Specification</em></a>.
+ <a name="2966"> </a>Entries written into a JavaSpaces service are governed by a lease, as defined in the package <code>net.jini.core.lease</code> and described in the <a href="lease-spec.html"><em class="Emphasis">River Distributed Leasing Specification</em></a>.
</p>
<h5 class="Heading4">
<a name="1765"> </a>JS.1.1.1 Distributed Persistence
@@ -209,10 +209,10 @@
<ul>
<li class="SmartList1"><a name="31963"> </a><em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Object Serialization Specification</em> <p>
<li class="SmartList1"><a name="2065"> </a><em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Remote Method Invocation Specification</em> <p>
- <li class="SmartList1"><a name="31881"> </a><a href="entry-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Entry Specification</em></a><p>
- <li class="SmartList1"><a name="31881"> </a><a href="event-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Distributed Events Specification</em></a><p>
- <li class="SmartList1"><a name="31881"> </a><a href="lease-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Distributed Leasing Specification</em></a><p>
- <li class="SmartList1"><a name="31881"> </a><a href="txn-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Transaction Specification</em></a><p>
+ <li class="SmartList1"><a name="31881"> </a><a href="entry-spec.html"><em class="Emphasis">River Entry Specification</em></a><p>
+ <li class="SmartList1"><a name="31881"> </a><a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a><p>
+ <li class="SmartList1"><a name="31881"> </a><a href="lease-spec.html"><em class="Emphasis">River Distributed Leasing Specification</em></a><p>
+ <li class="SmartList1"><a name="31881"> </a><a href="txn-spec.html"><em class="Emphasis">River Transaction Specification</em></a><p>
</ul>
<h3 class="Heading2">
@@ -234,7 +234,7 @@
<a name="7287"> </a>JS.2.1 Entries
</h4>
<p class="Body">
- <a name="30734"> </a>The types <code>Entry</code> and <code>UnusableEntryException</code> that are used in this specification are from the package <code>net.jini.core.entry</code> and are described in detail in the <a href="entry-spec.html"><em class="Emphasis">Jini Entry Specification</em></a>. In the terminology of that specification <code>write</code> is a store operation; <code>read</code> and <code>take</code> are combination search and fetch operations; and <code>notify</code> sets up repeated search operations as entries are written to the space.
+ <a name="30734"> </a>The types <code>Entry</code> and <code>UnusableEntryException</code> that are used in this specification are from the package <code>net.jini.core.entry</code> and are described in detail in the <a href="entry-spec.html"><em class="Emphasis">River Entry Specification</em></a>. In the terminology of that specification <code>write</code> is a store operation; <code>read</code> and <code>take</code> are combination search and fetch operations; and <code>notify</code> sets up repeated search operations as entries are written to the space.
</p>
<h4 class="Heading3">
<a name="7290"> </a>JS.2.2 <code>net.jini.space.JavaSpace</code>
@@ -359,7 +359,7 @@
<a name="31227"> </a>The <code>take</code> requests perform exactly like the corresponding <code>read</code> requests (see <a href="js-spec.html#7320">Section JS.2.4, "<code>readIfExists</code> and <code>read</code>"</a>), except that the matching entry is removed from the space. Two <code>take</code> operations will never return copies of the same entry, although if two equivalent entries were in the JavaSpaces service the two <code>take</code> operations could return equivalent entries.
</p>
<p class="Body">
- <a name="30790"> </a>If a <code>take</code> returns a non-<code>null</code> value, the entry has been removed from the space, possibly within a transaction (see <a href="js-spec.html#7388">Section JS.3, "Transactions"</a>). This modifies the claims to once-only retrieval: A <code>take</code> is considered to be successful only if all enclosing transactions commit successfully. If a <code>RemoteException</code> is thrown, the <code>take</code> may or may not have been successful. If an <code>UnusableEntryException</code> is thrown, the <code>take</code> removed the unusable entry from the space; the contents of the exception are as described in the <a href="entry-spec.html"><em class="Emphasis">Jini Entry Specification</em></a>. If any other exception is thrown, the <code>take</code> did not occur, and no entry was removed from the space.
+ <a name="30790"> </a>If a <code>take</code> returns a non-<code>null</code> value, the entry has been removed from the space, possibly within a transaction (see <a href="js-spec.html#7388">Section JS.3, "Transactions"</a>). This modifies the claims to once-only retrieval: A <code>take</code> is considered to be successful only if all enclosing transactions commit successfully. If a <code>RemoteException</code> is thrown, the <code>take</code> may or may not have been successful. If an <code>UnusableEntryException</code> is thrown, the <code>take</code> removed the unusable entry from the space; the contents of the exception are as described in the <a href="entry-spec.html"><em class="Emphasis">River Entry Specification</em></a>. If any other exception is thrown, the <code>take</code> did not occur, and no entry was removed from the space.
</p>
<p class="Body">
<a name="7336"> </a>With a <code>RemoteException</code>, an entry can be removed from a space and yet never returned to the client that performed the <code>take</code>, thus losing the entry in between. In circumstances in which this is unacceptable, the <code>take</code> can be wrapped inside a transaction that is committed by the client when it has the requested entry in hand.
@@ -389,7 +389,7 @@
<a name="7346"> </a>JS.2.7 <code>notify</code>
</h4>
<p class="Body">
- <a name="27483"> </a>A <code>notify</code> request registers interest in future incoming entries to the JavaSpaces service that match the specified template. Matching is done as it is for <code>read</code>. The <code>notify</code> method is a particular registration method under the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>. When matching entries are written, the specified <code>RemoteEventListener</code> will eventually be notified. When you invoke <code>notify</code> you provide an upper bound on the lease time, which is how long you want the registration to be remembered by the JavaSpaces service. The service decides the actual time for the lease. You will get an <code>IllegalArgumentException</code> if the lease time requested is not <code>Lease.ANY</code> and is negative. The lease time is expressed in the standard millisecond units, although actual lease times will usually be of much larger granularity. A lease time
of <code>Lease.FOREVER</code> is a request for an indefinite lease; if the service chooses not to grant an indefinite lease, it will return a bounded (non-zero) lease. The final argument to the notify request is a <CODE>MarshaledObject</CODE> called the handback.
+ <a name="27483"> </a>A <code>notify</code> request registers interest in future incoming entries to the JavaSpaces service that match the specified template. Matching is done as it is for <code>read</code>. The <code>notify</code> method is a particular registration method under the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a>. When matching entries are written, the specified <code>RemoteEventListener</code> will eventually be notified. When you invoke <code>notify</code> you provide an upper bound on the lease time, which is how long you want the registration to be remembered by the JavaSpaces service. The service decides the actual time for the lease. You will get an <code>IllegalArgumentException</code> if the lease time requested is not <code>Lease.ANY</code> and is negative. The lease time is expressed in the standard millisecond units, although actual lease times will usually be of much larger granularity. A lease tim
e of <code>Lease.FOREVER</code> is a request for an indefinite lease; if the service chooses not to grant an indefinite lease, it will return a bounded (non-zero) lease. The final argument to the notify request is a <CODE>MarshaledObject</CODE> called the handback.
<p>
Each notify returns a <CODE>net.jini.core.event.EventRegistration</CODE> object. When an object is written that matches the template supplied in the <CODE>notify</CODE> invocation, the listener's <CODE>notify</CODE> method is eventually invoked, with a <CODE>RemoteEvent</CODE> object. The <CODE>RemoteEvent</CODE> object's <CODE>getID</CODE> method will return the same value returned by the <CODE>EventRegistration</CODE> object's <CODE>getID</CODE> method. This value, the event ID, will be unique at least with respect to all other active event registrations on this JavaSpaces service with different templates or transactions. The <CODE>RemoteEvent</CODE> object's <CODE>getSource</CODE> method will return a reference to the JavaSpaces service. If the handback associated with the registration was non-<CODE>null</CODE>, the <CODE>RemoteEvent</CODE> object's <CODE>getRegistrationObject</CODE> method will return an object that is equivalent (in the sense of the <CODE>equals</CO
DE> method) to the handback, otherwise this method will return <CODE>null</CODE>. The <CODE>RemoteEvent</CODE> object's <CODE>getSequenceNumber</CODE> method will return the sequence number assigned to this event. Sequence numbers for a given event ID are strictly increasing. If there is no gap between two sequence numbers, no events have been missed; if there is a gap, events might (but might not) have been missed. For example, a gap might occur if the JavaSpaces service crashes, even if no events are lost due to the crash.
</p>
@@ -406,7 +406,7 @@
<a name="7352"> </a>The service will make a "best effort" attempt to deliver notifications. The service will retry at most until the notification request's lease expires. Notifications may be delivered in any order.
</p>
<p class="Body">
- <a name="7353"> </a>See the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a> for details on the event types.
+ <a name="7353"> </a>See the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a> for details on the event types.
</p>
<h4 class="Heading3">
<a name="7354"> </a>JS.2.8 Operation Ordering
@@ -450,7 +450,7 @@
<a name="7390"> </a>Transactions wrap together multiple operations. Either all modifications within the transactions will be applied or none will, whether the transaction spans one or more operations and/or one or more JavaSpaces services.
</p>
<p class="Body">
- <a name="7391"> </a>The transaction semantics described here conform to the default transaction semantics defined in the <a href="txn-spec.html"><em class="Emphasis">Jini Transaction Specification</em></a>.
+ <a name="7391"> </a>The transaction semantics described here conform to the default transaction semantics defined in the <a href="txn-spec.html"><em class="Emphasis">River Transaction Specification</em></a>.
</p>
<h4 class="Heading3">
<a name="7392"> </a>JS.3.1 Operations under Transactions
@@ -549,7 +549,7 @@
</tr>
<tr>
<td>v2.2 </td>
- <td>Removed dependency on Jini Entry Utilities Specification.</td>
+ <td>Removed dependency on River Entry Utilities Specification.</td>
</tr>
</table>
<p>
@@ -559,7 +559,7 @@
</p>
<a name="275577"> </a><a href="#2427"><sup>3</sup></a> "Linda" is the name of a public domain technology originally propounded by Dr. David Gelernter of Yale University. "Linda" is also claimed as a trademark for certain goods by Scientific Computing Associates, Inc. This discussion refers to the public domain "Linda" technology.
<p>
-<a name="04915"> </a><a href="#01886"><sup>4</sup></a> "Fully ordered" in defined in the <em>Jini Technology Core Platform Specification</em>, "Distributed Events".
+<a name="04915"> </a><a href="#01886"><sup>4</sup></a> "Fully ordered" in defined in the <em>River Technology Core Platform Specification</em>, "Distributed Events".
<h3 class="Heading2">
<a name="0188"> </a> License
</h3>
Modified: incubator/river/jtsk/trunk/doc/specs/html/jxpnote-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/jxpnote-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/jxpnote-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/jxpnote-spec.html Tue Jan 5 17:12:26 2010
@@ -29,7 +29,7 @@
<table width="100%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><i>A Collection of Jini<font size="-1"><sup>TM</sup></font> Technology Helper Utilities and Services Specifications</i></td>
+<td align=right><i>A Collection of River Technology Helper Utilities and Services Specifications</i></td>
</tr>
</table>
<br clear="all">
@@ -49,20 +49,20 @@
<a name="1007837"> </a>US.1 Summary
</h3>
<p class="Body">
- <a name="998142"> </a>When developing clients and services that will participate in the application environment for Jini<font size="-1"><sup>TM</sup></font> technology, there are a number of behaviors that the developer may find desirable to incorporate in the client or service. Some of these behaviors may satisfy requirements described in the specifications of various Jini technology components; some behaviors may simply represent design practices that are desirable and should be encouraged. Examples of the sort of behavior that is required or desirable include the following:
+ <a name="998142"> </a>When developing clients and services that will participate in the application environment for River technology, there are a number of behaviors that the developer may find desirable to incorporate in the client or service. Some of these behaviors may satisfy requirements described in the specifications of various River technology components; some behaviors may simply represent design practices that are desirable and should be encouraged. Examples of the sort of behavior that is required or desirable include the following:
</p>
<ul>
- <li class="SmartList1"><a name="998413"> </a>It is a requirement of the Jini discovery protocols that a service must continue to listen for and act on announcements from lookup services in which the service has registered interest.<p>
- <li class="SmartList1"><a name="998151"> </a>It is a requirement of the Jini discovery protocols that, until successful, a service must continue to attempt to join the specific lookup services with which it has been configured to join.<p>
- <li class="SmartList1"><a name="998570"> </a>Under many conditions, a Jini technology-enabled client (<em class="Emphasis">Jini client</em>) or service will wish to regularly renew leases that it holds. For example, when a Jini technology-enabled service (<em class="Emphasis">Jini service</em>) registers with a Jini lookup service, the service is requesting residency in the lookup service. Residency in a lookup service is a leased resource. Thus, when the requested residency is granted, the lookup service also imposes a lease on that residency. Typically, such a registered service will wish to extend the lease on its residency beyond the original expiration time, resulting in a need to renew the lease on a regular basis.<p>
- <li class="SmartList1"><a name="998539"> </a>Many Jini services will need to maintain a dormant (inactive) state, becoming active only when needed.<p>
- <li class="SmartList1"><a name="998341"> </a>Many Jini clients and services will need to have a mechanism for finding and managing Jini services.<p>
- <li class="SmartList1"><a name="998435"> </a>Many Jini clients and services will find it desirable to employ a separate service that will handle events, in some useful way, on behalf of the participant.
+ <li class="SmartList1"><a name="998413"> </a>It is a requirement of the River discovery protocols that a service must continue to listen for and act on announcements from lookup services in which the service has registered interest.<p>
+ <li class="SmartList1"><a name="998151"> </a>It is a requirement of the River discovery protocols that, until successful, a service must continue to attempt to join the specific lookup services with which it has been configured to join.<p>
+ <li class="SmartList1"><a name="998570"> </a>Under many conditions, a River technology-enabled client (<em class="Emphasis">River client</em>) or service will wish to regularly renew leases that it holds. For example, when a River technology-enabled service (<em class="Emphasis">River service</em>) registers with a River lookup service, the service is requesting residency in the lookup service. Residency in a lookup service is a leased resource. Thus, when the requested residency is granted, the lookup service also imposes a lease on that residency. Typically, such a registered service will wish to extend the lease on its residency beyond the original expiration time, resulting in a need to renew the lease on a regular basis.<p>
+ <li class="SmartList1"><a name="998539"> </a>Many River services will need to maintain a dormant (inactive) state, becoming active only when needed.<p>
+ <li class="SmartList1"><a name="998341"> </a>Many River clients and services will need to have a mechanism for finding and managing River services.<p>
+ <li class="SmartList1"><a name="998435"> </a>Many River clients and services will find it desirable to employ a separate service that will handle events, in some useful way, on behalf of the participant.
</ul>
<p class="Body">
- <a name="1008785"> </a>To help simplify the process of developing clients and services for the application environment for Jini technology (<em class="Emphasis">Jini application environment</em>), several specifications in this document collection define reusable components that encapsulate behaviors such as those outlined above. Employing such utilities and services to build such desirable behavior into a Jini client or service can help to avoid poor design and implementation decisions, greatly simplifying the development process.
+ <a name="1008785"> </a>To help simplify the process of developing clients and services for the application environment for River technology (<em class="Emphasis">River application environment</em>), several specifications in this document collection define reusable components that encapsulate behaviors such as those outlined above. Employing such utilities and services to build such desirable behavior into a River client or service can help to avoid poor design and implementation decisions, greatly simplifying the development process.
</p>
<p class="Body">
<a name="1007748"> </a>What is presented first is terminology that may be helpful when analyzing these specifications. Following the section on terminology, brief summaries of the content of each of the current helper utilities and services specifications are provided. Finally, the other specifications on which these specifications depend are listed for reference.
@@ -78,28 +78,28 @@
<a name="998835"> </a>US.2.1 Terms Related to Discovery and Join
</h4>
<p class="Body">
- <a name="1000369"> </a>The <a href="discovery-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em></a> defines a <em class="Emphasis">discovering entity</em> as one or more cooperating software objects written in the Java<font size="-1"><sup>TM</sup></font> programming language (<em class="Emphasis">Java software objects</em>), executing on the same host, that are in the process of obtaining references to Jini lookup services. That specification also defines a <em class="Emphasis">joining entity</em> as one or more cooperating Java software objects, on the same host, that have received a reference to a lookup service and are in the process of obtaining services from, and possibly exporting services to, a federation of Jini technology-enabled services and/or devices and Jini lookup services referred to as a <em class="Emphasis">djinn</em>. The lookup services comprising a djinn may be organized into one or more sets
known as <em class="Emphasis">groups</em>. Multiple groups may or may not be disjoint. Each group of lookup services is identified by a logical name represented by a <code>String</code> object.
+ <a name="1000369"> </a>The <a href="discovery-spec.html"><em class="Emphasis">River Discovery and Join Specification</em></a> defines a <em class="Emphasis">discovering entity</em> as one or more cooperating software objects written in the Java<font size="-1"><sup>TM</sup></font> programming language (<em class="Emphasis">Java software objects</em>), executing on the same host, that are in the process of obtaining references to River lookup services. That specification also defines a <em class="Emphasis">joining entity</em> as one or more cooperating Java software objects, on the same host, that have received a reference to a lookup service and are in the process of obtaining services from, and possibly exporting services to, a federation of River technology-enabled services and/or devices and River lookup services referred to as a <em class="Emphasis">djinn</em>. The lookup services comprising a djinn may be organized into one or more sets known as <em class="Emphasis">gr
oups</em>. Multiple groups may or may not be disjoint. Each group of lookup services is identified by a logical name represented by a <code>String</code> object.
</p>
<p class="Body">
- <a name="999345"> </a>The <a href="discovery-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em></a> defines two protocols used in the discovery process: the <em class="Emphasis">multicast discovery protocol</em> and the <em class="Emphasis">unicast discovery protocol</em>.
+ <a name="999345"> </a>The <a href="discovery-spec.html"><em class="Emphasis">River Discovery and Join Specification</em></a> defines two protocols used in the discovery process: the <em class="Emphasis">multicast discovery protocol</em> and the <em class="Emphasis">unicast discovery protocol</em>.
</p>
<p class="Body">
<a name="999377"> </a>When a discovering entity employs the multicast discovery protocol to discover lookup services that are members of one or more groups belonging to a set of groups, that discovery process is referred to as <em class="Emphasis">group discovery</em>.
</p>
<p class="Body">
- <a name="999356"> </a>The utility class <code>net.jini.core.discovery.LookupLocator</code> is defined in the <a href="discovery-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em></a>. Any instance of that class is referred to as a <em class="Emphasis">locator</em>. When a discovering entity employs the unicast discovery protocol to discover specific lookup services, each corresponding to an element in a set of locators, that discovery process is referred to as <em class="Emphasis">locator discovery</em>.
+ <a name="999356"> </a>The utility class <code>net.jini.core.discovery.LookupLocator</code> is defined in the <a href="discovery-spec.html"><em class="Emphasis">River Discovery and Join Specification</em></a>. Any instance of that class is referred to as a <em class="Emphasis">locator</em>. When a discovering entity employs the unicast discovery protocol to discover specific lookup services, each corresponding to an element in a set of locators, that discovery process is referred to as <em class="Emphasis">locator discovery</em>.
</p>
<h4 class="Heading3">
- <a name="998836"> </a>US.2.2 Jini Clients and Services
+ <a name="998836"> </a>US.2.2 River Clients and Services
</h4>
<p class="Body">
- <a name="997888"> </a>For the purposes of the helper utilities and services specifications, a <em class="Emphasis">Jini client</em> is defined as a discovering entity that can retrieve a service (or a remote reference to a service) registered with a discovered lookup service and invoke the methods of the service to meet the entity's requirements. An entity that acts only as a client never registers with (requests residency in) a lookup service.
+ <a name="997888"> </a>For the purposes of the helper utilities and services specifications, a <em class="Emphasis">River client</em> is defined as a discovering entity that can retrieve a service (or a remote reference to a service) registered with a discovered lookup service and invoke the methods of the service to meet the entity's requirements. An entity that acts only as a client never registers with (requests residency in) a lookup service.
</p>
<p class="Body">
- <a name="998025"> </a>A <em class="Emphasis">Jini service</em> is defined as both a discovering and a joining entity containing methods that may be of use to some other Jini client or service, and which registers with discovered lookup services to provide access to those methods. Note that a Jini service can also act as a Jini client.
+ <a name="998025"> </a>A <em class="Emphasis">River service</em> is defined as both a discovering and a joining entity containing methods that may be of use to some other River client or service, and which registers with discovered lookup services to provide access to those methods. Note that a River service can also act as a River client.
</p>
<p class="Body">
- <a name="998960"> </a>The term <em class="Emphasis">client-like entity</em> may be used, in general, when referring to Jini clients and Jini services that act as clients.
+ <a name="998960"> </a>The term <em class="Emphasis">client-like entity</em> may be used, in general, when referring to River clients and River services that act as clients.
</p>
<p class="Body">
<a name="998964"> </a>Note that when the term <em class="Emphasis">entity</em> is used, that term may be referring to a discovering entity, a joining entity, a client-like entity, a service, or some combination of these types of entities. Whenever that general term is used, it should be clear from the context what type of entity is being discussed.
@@ -108,16 +108,16 @@
<a name="999426"> </a>US.2.3 Helper Service
</h4>
<p class="Body">
- <a name="999427"> </a>A Jini technology-enabled <em class="Emphasis">helper service</em> is defined in this document as an interface or set of interfaces, with an associated implementation, that encapsulates behavior that is either required or highly desirable in service entities that adhere to the Jini technology programming model (or simply the <em class="Emphasis">Jini programming model</em>). A helper service is a Jini service that can be registered with any number of lookup services and whose methods can execute on remote hosts.
+ <a name="999427"> </a>A River technology-enabled <em class="Emphasis">helper service</em> is defined in this document as an interface or set of interfaces, with an associated implementation, that encapsulates behavior that is either required or highly desirable in service entities that adhere to the River technology programming model (or simply the <em class="Emphasis">River programming model</em>). A helper service is a River service that can be registered with any number of lookup services and whose methods can execute on remote hosts.
</p>
<p class="Body">
- <a name="999428"> </a>In general, a helper service should be of use to more than one type of entity participating in the Jini application environment and should provide a significant reduction in development complexity for developers of such entities.
+ <a name="999428"> </a>In general, a helper service should be of use to more than one type of entity participating in the River application environment and should provide a significant reduction in development complexity for developers of such entities.
</p>
<h4 class="Heading3">
<a name="999429"> </a>US.2.4 Helper Utility
</h4>
<p class="Body">
- <a name="999430"> </a>This document distinguishes between a helper <em class="Emphasis">utility</em> and a helper <em class="Emphasis">service</em>. Helper utilities are programming components that can be used during the construction of Jini services and/or clients. Helper utilities are <em class="Emphasis">not</em> remote and do not register with a lookup service. Helper utilities are instantiated locally by entities wishing to employ them.
+ <a name="999430"> </a>This document distinguishes between a helper <em class="Emphasis">utility</em> and a helper <em class="Emphasis">service</em>. Helper utilities are programming components that can be used during the construction of River services and/or clients. Helper utilities are <em class="Emphasis">not</em> remote and do not register with a lookup service. Helper utilities are instantiated locally by entities wishing to employ them.
</p>
<h4 class="Heading3">
<a name="999384"> </a>US.2.5 Managed Sets
@@ -219,7 +219,7 @@
<a name="999048"> </a>To initiate an invocation of a remote method, the client must have access to an object referred to as the <em class="Emphasis">stub</em> of the remote object. The stub <em class="Emphasis">is</em> an object local to the client that acts as the "representative" of the remote object. The stub implements the same set of remote interfaces that the remote object implements. From the point of view of the client, the stub <em class="Emphasis">is</em> the remote object. When the client invokes a method on the local stub, communication with the remote object occurs, resulting in the execution of the corresponding method in the remote object's JVM.
</p>
<p class="Body">
- <a name="998990"> </a>The term <em class="Emphasis">proxy</em> is used extensively throughout the helper utilities and services specifications. With respect to remote objects in general, and entities operating within a Jini application environment in particular, a proxy is simply an intermediary object through which one entity (the client) may request the invocation of the methods provided by another entity (the remote object or the service).
+ <a name="998990"> </a>The term <em class="Emphasis">proxy</em> is used extensively throughout the helper utilities and services specifications. With respect to remote objects in general, and entities operating within a River application environment in particular, a proxy is simply an intermediary object through which one entity (the client) may request the invocation of the methods provided by another entity (the remote object or the service).
</p>
<p class="Body">
<a name="999229"> </a>Proxies can take a number of different forms. A <em class="Emphasis">smart proxy</em> typically consists of a set of local methods and a set of one or more remote object references (stubs). Clients invoke one or more of the local methods to access the methods of the remote objects referenced in the proxy.
@@ -231,7 +231,7 @@
<a name="999223"> </a>Some proxies are implemented as <em class="Emphasis">strictly local</em>. Proxies of this form consist of only local methods, each executing in the client's JVM. Unlike smart proxies, no remote invocations result when any method of a strictly local proxy is invoked.
</p>
<p class="Body">
- <a name="1000354"> </a>Typically, Jini services provide a proxy that has one of the forms described above. When a service registers with a lookup service, the service's proxy is copied (through serialization) into the lookup service. When a client looks up the service, the service's proxy is downloaded to the client. The client can then invoke the methods contained in the service's proxy. If the invoked method is a local method, then execution will occur in the JVM of the client. If the invoked method is a remote method (or results in a remote invocation), then execution is initiated in the client's JVM, but ultimately occurs in the JVM of the service.
+ <a name="1000354"> </a>Typically, River services provide a proxy that has one of the forms described above. When a service registers with a lookup service, the service's proxy is copied (through serialization) into the lookup service. When a client looks up the service, the service's proxy is downloaded to the client. The client can then invoke the methods contained in the service's proxy. If the invoked method is a local method, then execution will occur in the JVM of the client. If the invoked method is a remote method (or results in a remote invocation), then execution is initiated in the client's JVM, but ultimately occurs in the JVM of the service.
</p>
<p class="Body">
<a name="1000355"> </a>Note that the term <em class="Emphasis">front-end proxy</em> (or simply <em class="Emphasis">front end</em>) is often used interchangeably with the term <code>proxy.</code> Similarly, the term <em class="Emphasis">back-end server</em> (or simply, <em class="Emphasis">back end</em>) is often used interchangeably with the term <code>remote object.</code> Thus, the back end of a service is the part of the service's implementation that satisfies the contract advertised in the service's remote interface.
@@ -240,7 +240,7 @@
<a name="999291"> </a>US.2.8 Activation
</h4>
<p class="Body">
- <a name="1009168"> </a>The glossary defines <em class="Emphasis">active object</em> as a remote object that is instantiated and exported in a JVM on some system. Remote objects can be implemented with the ability to change their state from inactive to active, or from active to inactive; the process of doing so is referred to as <em class="Emphasis">activation</em> or <em class="Emphasis">deactivation</em>, respectively. Many Jini services that wish to conserve computational resources may find this capability desirable. When the back end of any Jini service is implemented with the ability to activate and deactivate, the service is referred to as an <em class="Emphasis">activatable</em> <em class="Emphasis">service</em>. Refer to the <em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Remote Method Invocation Specification</em> for the details of activation.
+ <a name="1009168"> </a>The glossary defines <em class="Emphasis">active object</em> as a remote object that is instantiated and exported in a JVM on some system. Remote objects can be implemented with the ability to change their state from inactive to active, or from active to inactive; the process of doing so is referred to as <em class="Emphasis">activation</em> or <em class="Emphasis">deactivation</em>, respectively. Many River services that wish to conserve computational resources may find this capability desirable. When the back end of any River service is implemented with the ability to activate and deactivate, the service is referred to as an <em class="Emphasis">activatable</em> <em class="Emphasis">service</em>. Refer to the <em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Remote Method Invocation Specification</em> for the details of activation.
</p>
<h3 class="Heading2">
<a name="1009170"> </a>US.3 Introduction to the Helper Utilities
@@ -249,7 +249,7 @@
<a name="1009531"> </a>US.3.1 The Discovery Utilities
</h4>
<p class="Body">
- <a name="1009535"> </a>The <em class="Emphasis"><a href="discoveryutil-spec.html">Jini Discovery Utilities Specification</a></em> defines a set of general-purpose utility interfaces collectively referred to as the discovery management interfaces. Those interfaces define the policies to apply when implementing helper utilities that manage an entity's discovery duties. Currently, the set of discovery management interfaces consists of the following three interfaces:
+ <a name="1009535"> </a>The <em class="Emphasis"><a href="discoveryutil-spec.html">River Discovery Utilities Specification</a></em> defines a set of general-purpose utility interfaces collectively referred to as the discovery management interfaces. Those interfaces define the policies to apply when implementing helper utilities that manage an entity's discovery duties. Currently, the set of discovery management interfaces consists of the following three interfaces:
</p>
<ul>
@@ -269,10 +269,10 @@
</ul>
<p class="Body">
- <a name="1007183"> </a>In order to provide a mechanism to control (through the application of sets of constraints) how unicast discovery is performed by the discovery management utilities described above, the discovery utilities specification defines a subclass of the <code>net.jini.core.discovery.LookupLocator</code> class defined in the <em>Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em>. That class is <code>ConstrainableLookupLocator</code>.
+ <a name="1007183"> </a>In order to provide a mechanism to control (through the application of sets of constraints) how unicast discovery is performed by the discovery management utilities described above, the discovery utilities specification defines a subclass of the <code>net.jini.core.discovery.LookupLocator</code> class defined in the <em>River Discovery and Join Specification</em>. That class is <code>ConstrainableLookupLocator</code>.
</p>
<p>
-The discovery utilities specification closes with a discussion of a set of low-level utility classes that can be useful when applying the discovery management policies to build higher-level helper utilities for discovery. It is important to note that these classes only support version 1 of the discovery protocol, as defined in the <em>Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em>. The low-level discovery utilities consist of the following classes:</p>
+The discovery utilities specification closes with a discussion of a set of low-level utility classes that can be useful when applying the discovery management policies to build higher-level helper utilities for discovery. It is important to note that these classes only support version 1 of the discovery protocol, as defined in the <em>River Discovery and Join Specification</em>. The low-level discovery utilities consist of the following classes:</p>
<ul>
<li class="SmartList1"><code>Constants</code><p>
<li class="SmartList1"><code>OutgoingMulticastRequest</code><p>
@@ -318,7 +318,7 @@
<a name="1007073"> </a>US.3.1.6 The <code>LookupDiscoveryManager</code> Helper Utility
</h5>
<p class="Body">
- <a name="1007170"> </a>The <code>LookupDiscoveryManager</code> is a helper utility class that organizes and manages all discovery-related activities on behalf of a Jini client or service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to group names, locators, and listeners, such an entity can employ this class to provide those facilities on its behalf.
+ <a name="1007170"> </a>The <code>LookupDiscoveryManager</code> is a helper utility class that organizes and manages all discovery-related activities on behalf of a River client or service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to group names, locators, and listeners, such an entity can employ this class to provide those facilities on its behalf.
</p>
<h5 class="Heading4">US.3.1.7 The <code>ConstrainableLookupLocator</code> Utility</h5>
<p>
@@ -382,7 +382,7 @@
<a name="1007423"> </a>US.3.2 The Lease Utilities
</h4>
<p class="Body">
- <a name="1007424"> </a>The <em class="Emphasis"><a href="leaseutil-spec.html#1004356">Jini Lease Utilities Specification</a></em> defines helper utility classes, along with supporting interfaces and supporting classes, that encapsulate functionality which provides for the coordination, systematic renewal, and overall management of a set of leases associated with some object on behalf of another object. Currently, this specification defines only one helper utility class:
+ <a name="1007424"> </a>The <em class="Emphasis"><a href="leaseutil-spec.html#1004356">River Lease Utilities Specification</a></em> defines helper utility classes, along with supporting interfaces and supporting classes, that encapsulate functionality which provides for the coordination, systematic renewal, and overall management of a set of leases associated with some object on behalf of another object. Currently, this specification defines only one helper utility class:
</p>
<ul>
@@ -393,13 +393,13 @@
<a name="1007438"> </a>US.3.2.1 The <code>LeaseRenewalManager</code> Helper Utility
</h5>
<p class="Body">
- <a name="1007439"> </a>The <code>LeaseRenewalManager</code> is a helper utility class that organizes and manages all of the activities related to the renewal of the leases granted to a Jini client or service by another Jini service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to lease renewal, such an entity can employ this class to provide those facilities on its behalf.
+ <a name="1007439"> </a>The <code>LeaseRenewalManager</code> is a helper utility class that organizes and manages all of the activities related to the renewal of the leases granted to a River client or service by another River service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to lease renewal, such an entity can employ this class to provide those facilities on its behalf.
</p>
<h4 class="Heading3">
<a name="1007461"> </a>US.3.3 The Join Utilities
</h4>
<p class="Body">
- <a name="1007462"> </a>The <em class="Emphasis"><a href="joinutil-spec.html#1015487">Jini Join Utilities Specification</a></em> defines helper utility classes, supporting interfaces, and supporting classes, that encapsulate functionality related to discovery and registration interactions that a well-behaved Jini service will typically have with a lookup service. Currently, this specification defines only one helper utility class:
+ <a name="1007462"> </a>The <em class="Emphasis"><a href="joinutil-spec.html#1015487">River Join Utilities Specification</a></em> defines helper utility classes, supporting interfaces, and supporting classes, that encapsulate functionality related to discovery and registration interactions that a well-behaved River service will typically have with a lookup service. Currently, this specification defines only one helper utility class:
</p>
<ul>
@@ -410,13 +410,13 @@
<a name="1007476"> </a>US.3.3.1 The <code>JoinManager</code> Helper Utility
</h5>
<p class="Body">
- <a name="1007514"> </a>The <code>JoinManager</code> is a helper utility class that performs all of the functions related to lookup service discovery, joining, lease renewal, and attribute management, functions that the programming model requires of a well-behaved Jini service. Rather than providing its own facility for providing such functions, a Jini service can employ this class to provide those facilities on its behalf.
+ <a name="1007514"> </a>The <code>JoinManager</code> is a helper utility class that performs all of the functions related to lookup service discovery, joining, lease renewal, and attribute management, functions that the programming model requires of a well-behaved River service. Rather than providing its own facility for providing such functions, a River service can employ this class to provide those facilities on its behalf.
</p>
<h4 class="Heading3">
<a name="1007520"> </a>US.3.4 The Service Discovery Utilities
</h4>
<p class="Body">
- <a name="1009054"> </a>The <em class="Emphasis"><a href="servicediscutil-spec.html#1010752">Jini Service Discovery Utilities Specification</a></em> defines helper utility classes (with supporting interfaces and classes) that encapsulate functionality that aids a Jini service or client in acquiring services of interest, registered with the various lookup services with which the service or client wishes to interact. Currently, the service discovery utilities specification defines only one helper utility class:
+ <a name="1009054"> </a>The <em class="Emphasis"><a href="servicediscutil-spec.html#1010752">River Service Discovery Utilities Specification</a></em> defines helper utility classes (with supporting interfaces and classes) that encapsulate functionality that aids a River service or client in acquiring services of interest, registered with the various lookup services with which the service or client wishes to interact. Currently, the service discovery utilities specification defines only one helper utility class:
</p>
<ul>
@@ -433,10 +433,10 @@
<a name="1007553"> </a>The <code>ServiceDiscoveryManager</code> class can be asked to "discover" services an entity is interested in using and to cache the references to those services as each is found. The cache can be viewed as a set of services that the entity can access through a set of public, non-remote methods. The <code>ServiceDiscoveryManager</code> class also provides a mechanism for an entity to request notification when a service of interest is discovered for the first time or has encountered a state change (such as removal from all lookup services or attribute set changes).
</p>
<p class="Body">
- <a name="1007555"> </a>For convenience, the <code>ServiceDiscoveryManager</code> class also provides versions of a method named <code>lookup</code>, which employs invocation semantics similar to the semantics of the <code>lookup</code> method of the <code>ServiceRegistrar</code> interface, specified in the <a href="lookup-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Lookup Service Specification</em></a>. Entities needing to find services on only an infrequent basis, or in which the cost of making a remote call is outweighed by the overhead of maintaining a local cache (for example, because of limited resources), may find this method useful.
+ <a name="1007555"> </a>For convenience, the <code>ServiceDiscoveryManager</code> class also provides versions of a method named <code>lookup</code>, which employs invocation semantics similar to the semantics of the <code>lookup</code> method of the <code>ServiceRegistrar</code> interface, specified in the <a href="lookup-spec.html"><em class="Emphasis">River Lookup Service Specification</em></a>. Entities needing to find services on only an infrequent basis, or in which the cost of making a remote call is outweighed by the overhead of maintaining a local cache (for example, because of limited resources), may find this method useful.
</p>
<p class="Body">
- <a name="1007853"> </a>All three mechanisms described above--local queries on the cache, service discovery notification, and remote lookups--employ the same template-matching scheme as that described in the <a href="lookup-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Lookup Service Specification</em></a>. Additionally, each mechanism allows the entity to supply an action object referred to as a <em class="Emphasis">filter</em>. Such an object is a non-remote object that defines additional matching criteria that will be applied when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of the standard template-matching scheme.
+ <a name="1007853"> </a>All three mechanisms described above--local queries on the cache, service discovery notification, and remote lookups--employ the same template-matching scheme as that described in the <a href="lookup-spec.html"><em class="Emphasis">River Lookup Service Specification</em></a>. Additionally, each mechanism allows the entity to supply an action object referred to as a <em class="Emphasis">filter</em>. Such an object is a non-remote object that defines additional matching criteria that will be applied when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of the standard template-matching scheme.
</p>
<h3 class="Heading2">
<a name="1007854"> </a>US.4 Introduction to the Helper Services
@@ -448,13 +448,13 @@
<a name="1007660"> </a>Under certain circumstances, a discovering entity may find it useful to allow a third party to perform the entity's discovery duties. For example, an activatable entity that wishes to deactivate may wish to employ a separate helper service to perform discovery duties on the entity's behalf. Such an entity may wish to deactivate for various reasons, one being to conserve computational resources. While the entity is deactivated, the helper service, running on the same or a separate host, would employ the discovery protocols to find lookup services in which the entity has expressed interest and would notify the entity when a previously unavailable lookup service becomes available. Such a helper service is referred to as a <em class="Emphasis">lookup discovery service</em>.
</p>
<p class="Body">
- <a name="1007694"> </a>The <code>LookupDiscoveryService</code> interface defines the lookup discovery helper service. Through that interface, other Jini services and clients may request that discovery processing be performed on their behalf.
+ <a name="1007694"> </a>The <code>LookupDiscoveryService</code> interface defines the lookup discovery helper service. Through that interface, other River services and clients may request that discovery processing be performed on their behalf.
</p>
<h4 class="Heading3">
<a name="1007697"> </a>US.4.2 The Lease Renewal Service
</h4>
<p class="Body">
- <a name="1009574"> </a>The <em class="Emphasis">lease renewal service</em>--defined by the <code>net.jini.lease.LeaseRenewalService</code> interface--is a helper service that can be employed by both Jini clients and services to perform all lease renewal duties on their behalf. Services that wish to remain inactive until they are needed may find the lease renewal service quite useful. Such a service can request that the lease renewal service take on the responsibility of renewing the leases granted to the service, and then safely deactivate without risking the loss of access to the resources corresponding to the leases being renewed.
+ <a name="1009574"> </a>The <em class="Emphasis">lease renewal service</em>--defined by the <code>net.jini.lease.LeaseRenewalService</code> interface--is a helper service that can be employed by both River clients and services to perform all lease renewal duties on their behalf. Services that wish to remain inactive until they are needed may find the lease renewal service quite useful. Such a service can request that the lease renewal service take on the responsibility of renewing the leases granted to the service, and then safely deactivate without risking the loss of access to the resources corresponding to the leases being renewed.
</p>
<p class="Body">
<a name="1007713"> </a>Entities that have continuous <em class="Emphasis">access</em> to a network but that cannot be continuously <em class="Emphasis">connected</em> to that network (for example, a cell phone), may also find this service useful. By allowing a lease renewal service (which can be continuously connected) to renew the leases on the resources acquired by the entity, the entity may remain disconnected until needed. This lease renewal service removes the need to perform the discovery and lookup process each time the entity reconnects to the network, potentially resulting in a significant increase in efficiency.
@@ -481,11 +481,11 @@
<li class="SmartList1"><a name="997298"> </a><em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Remote Method Invocation Specification</em><p>
<li class="SmartList1"><a name="997299"> </a><em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Object Serialization Specification</em><p>
- <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="discovery-spec.html">Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</a></em><p>
- <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="lease-spec.html">Jini<font size="-1"><sup>TM</sup></font> Distributed Leasing Specification</a></em><p>
- <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="txn-spec.html">Jini<font size="-1"><sup>TM</sup></font> Transaction Specification</a></em><p>
- <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="lookup-spec.html">Jini<font size="-1"><sup>TM</sup></font> Lookup Service Specification</a></em><p>
- <li class="SmartList1"><a name="998598"> </a><em class="Emphasis"><a href="schema-spec.html">Jini<font size="-1"><sup>TM</sup></font> Lookup Attribute Schema Specification</a></em>
+ <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="discovery-spec.html">River Discovery and Join Specification</a></em><p>
+ <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="lease-spec.html">River Distributed Leasing Specification</a></em><p>
+ <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="txn-spec.html">River Transaction Specification</a></em><p>
+ <li class="SmartList1"><a name="1009473"> </a><em class="Emphasis"><a href="lookup-spec.html">River Lookup Service Specification</a></em><p>
+ <li class="SmartList1"><a name="998598"> </a><em class="Emphasis"><a href="schema-spec.html">River Lookup Attribute Schema Specification</a></em>
</ul>
</p>
@@ -545,7 +545,7 @@
<a href="#skip" title="Skip navigation bar"></a>
<table width="100%"><tr>
<td align=left><a href="../../spec-index.html">Spec Index</a>
-</td><td align=right><em>A Collection of Jini<font size="-1"><sup>TM</sup></font> Technology Helper Utilities and Services Specifications</em></td>
+</td><td align=right><em>A Collection of River Technology Helper Utilities and Services Specifications</em></td>
</tr></table>
<a name="skip"></a>
Modified: incubator/river/jtsk/trunk/doc/specs/html/lds-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/lds-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/lds-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/lds-spec.html Tue Jan 5 17:12:26 2010
@@ -22,7 +22,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
-<title>Jini Lookup Discovery Service </title>
+<title>River Lookup Discovery Service </title>
</head>
<body bgcolor="#ffffff">
@@ -31,7 +31,7 @@
<table width="100%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><em>A Collection of Jini Technology Helper Utilities and Services Specifications</em></td>
+<td align=right><em>A Collection of River Technology Helper Utilities and Services Specifications</em></td>
</tr>
</table>
<br clear="all">
@@ -46,15 +46,15 @@
<a name="skip"></a>
<blockquote>
<h2>
- <a name="1013622"> </a>LD - Jini<font size="-1"><sup>TM</sup></font> Lookup Discovery Service</h2>
+ <a name="1013622"> </a>LD - River Lookup Discovery Service</h2>
<h3 class="Heading2">
<a name="1000045"> </a>LD.1 Introduction
</h3>
<p class="Body">
- <a name="1000634"> </a>Part of the <a href="discovery-spec.html"><em>Jini<font size="-1"><sup>TM</sup></font> Discovery and Join Specification</em></a> is devoted to defining the discovery requirements for well-behaved Jini clients and services, called <em class="Emphasis">discovering entities</em>, which are required to participate in the multicast discovery protocols. Discovering entities are required to send multicast discovery requests to lookup services with which the entities wish to interact. In addition, they must continuously listen for and act on announcements from the desired lookup services. Interactions with a discovered lookup service may involve registration with that lookup service, or may simply involve querying the lookup service for services of interest (or both). To find <em class="Emphasis">specific</em> lookup services, discovering entities also need to be able to participate in the unicast discovery protocol.
+ <a name="1000634"> </a>Part of the <a href="discovery-spec.html"><em>River Discovery and Join Specification</em></a> is devoted to defining the discovery requirements for well-behaved River clients and services, called <em class="Emphasis">discovering entities</em>, which are required to participate in the multicast discovery protocols. Discovering entities are required to send multicast discovery requests to lookup services with which the entities wish to interact. In addition, they must continuously listen for and act on announcements from the desired lookup services. Interactions with a discovered lookup service may involve registration with that lookup service, or may simply involve querying the lookup service for services of interest (or both). To find <em class="Emphasis">specific</em> lookup services, discovering entities also need to be able to participate in the unicast discovery protocol.
</p>
<p class="Body">
- <a name="1002945"> </a>Under certain circumstances, a discovering entity may find it useful to allow a third party to perform the entity's discovery duties. For example, an activatable entity that wishes to deactivate may wish to employ a special Jini technology-enabled service (<em class="Emphasis">Jini service</em>)--referred to as a <em class="Emphasis">lookup discovery service</em>--to perform discovery duties on its behalf. Such an entity may wish to deactivate for various reasons, one being to conserve computational resources. While the entity is inactive, the lookup discovery service, running on the same or a separate host, would employ the discovery protocols to find lookup services in which the entity has expressed interest and would notify the entity when a previously unavailable lookup service has become available.
+ <a name="1002945"> </a>Under certain circumstances, a discovering entity may find it useful to allow a third party to perform the entity's discovery duties. For example, an activatable entity that wishes to deactivate may wish to employ a special River technology-enabled service (<em class="Emphasis">River service</em>)--referred to as a <em class="Emphasis">lookup discovery service</em>--to perform discovery duties on its behalf. Such an entity may wish to deactivate for various reasons, one being to conserve computational resources. While the entity is inactive, the lookup discovery service, running on the same or a separate host, would employ the discovery protocols to find lookup services in which the entity has expressed interest and would notify the entity when a previously unavailable lookup service has become available.
</p>
<p class="Body">
<a name="1003079"> </a>The facilities of the lookup discovery service are of particular value in a scenario in which a new lookup service is added to a long-lived djinn containing multiple inactive services. Without the use of a lookup discovery service, the time frame over which the new lookup service is fully populated can be both unpredictable and unbounded.
@@ -82,13 +82,13 @@
<a name="1003028"> </a>Note that the scenario just described does not come without restrictions. For the lookup discovery service to be able to "link" an entity with lookup services in the way just described, the lookup discovery service must be registered with a lookup service having a location that either is known to the entity or is within the multicast radius of the entity. Furthermore, the lookup discovery service must be running on a host that is located within the multicast radius of the lookup services with which the entity wishes to be linked. That is, the entity must be able to find the lookup discovery service, and the lookup discovery service must be able to find the other desired lookup services.
</p>
<p class="Body">
- <a name="1000724"> </a>To address these scenarios, the lookup discovery service participates in both the multicast discovery protocols and the unicast discovery protocol on behalf of a registered discovering entity or <em class="Emphasis">client</em>. This service will listen for and process multicast announcement packets from Jini lookup services and will, until successful, repeatedly attempt to discover specific lookup services that the client is interested in finding.
+ <a name="1000724"> </a>To address these scenarios, the lookup discovery service participates in both the multicast discovery protocols and the unicast discovery protocol on behalf of a registered discovering entity or <em class="Emphasis">client</em>. This service will listen for and process multicast announcement packets from River lookup services and will, until successful, repeatedly attempt to discover specific lookup services that the client is interested in finding.
</p>
<p class="Body">
- <a name="1000786"> </a>Upon discovery of a previously undiscovered lookup service of interest, the lookup discovery service notifies all entities that have requested the discovery of that lookup service that such an event has occurred. The event mechanism employed by the lookup discovery service satisfies the requirements defined in the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>. Note that the entity that receives such an event notification does not have to be the client of the lookup discovery service; it may be a third-party event-handling service such as an event mailbox service. Once a client is notified of the discovery of a lookup service, it is left to the client to define the semantics of how it interacts with that lookup service. For example, the client may wish to join the lookup service, simply query it for other useful services, or both.
+ <a name="1000786"> </a>Upon discovery of a previously undiscovered lookup service of interest, the lookup discovery service notifies all entities that have requested the discovery of that lookup service that such an event has occurred. The event mechanism employed by the lookup discovery service satisfies the requirements defined in the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a>. Note that the entity that receives such an event notification does not have to be the client of the lookup discovery service; it may be a third-party event-handling service such as an event mailbox service. Once a client is notified of the discovery of a lookup service, it is left to the client to define the semantics of how it interacts with that lookup service. For example, the client may wish to join the lookup service, simply query it for other useful services, or both.
</p>
<p class="Body">
- <a name="1000236"> </a>The lookup discovery service must be implemented as a well-behaved Jini service and must comply with all of the policies embodied in the Jini technology programming model. Thus, the resources granted by this service are leased, and implementations of this service must adhere to the distributed leasing model for Jini technology as defined in the <a href="lease-spec.html"><em class="Emphasis">Jini Distributed Leasing Specification</em></a>. That is, the lookup discovery service will grant its services for only a limited period of time without an active expression of continuing interest on the part of the client.
+ <a name="1000236"> </a>The lookup discovery service must be implemented as a well-behaved River service and must comply with all of the policies embodied in the River technology programming model. Thus, the resources granted by this service are leased, and implementations of this service must adhere to the distributed leasing model for River technology as defined in the <a href="lease-spec.html"><em class="Emphasis">River Distributed Leasing Specification</em></a>. That is, the lookup discovery service will grant its services for only a limited period of time without an active expression of continuing interest on the part of the client.
</p>
<h4 class="Heading3">
<a name="1000358"> </a>LD.1.1 Goals and Requirements
@@ -98,9 +98,9 @@
</p>
<ul>
- <li class="SmartList1"><a name="1002280"> </a>To define a service that not only employs the Jini discovery protocols to discover, by way of either group association or <code>LookupLocator</code> association, lookup services in which clients have registered interest, but that also notifies its clients of the discovery of those lookup services<p>
+ <li class="SmartList1"><a name="1002280"> </a>To define a service that not only employs the River discovery protocols to discover, by way of either group association or <code>LookupLocator</code> association, lookup services in which clients have registered interest, but that also notifies its clients of the discovery of those lookup services<p>
<li class="SmartList1"><a name="1000361"> </a>To provide this service in such a way that it can be used by entities that deactivate<p>
- <li class="SmartList1"><a name="1000384"> </a>To comply with the policies of the Jini technology programming model
+ <li class="SmartList1"><a name="1000384"> </a>To comply with the policies of the River technology programming model
</ul>
<p class="Body">
@@ -139,7 +139,7 @@
<a name="1000124"> </a>LD.2 The Interface
</h3>
<p class="Body">
- <a name="1000801"> </a>The <code>LookupDiscoveryService</code> interface defines the service--referred to as the <em class="Emphasis">lookup discovery service</em>--previously introduced in this specification. Through this interface, other Jini services and clients may request that discovery processing be performed on their behalf. This interface belongs to the <code>net.jini.discovery</code> package, and any service implementing this interface must comply with the definition of a Jini service. This interface is not a remote interface; each implementation of this service exports a front end proxy object that implements this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server (the back end). All of the proxy methods must obey normal Java Remote Method Invocation (RMI) remote interface semantics except where explicitly noted. Two proxy objects are equal (using the <code>equals</code> method) if they are proxie
s for the same lookup discovery service.
+ <a name="1000801"> </a>The <code>LookupDiscoveryService</code> interface defines the service--referred to as the <em class="Emphasis">lookup discovery service</em>--previously introduced in this specification. Through this interface, other River services and clients may request that discovery processing be performed on their behalf. This interface belongs to the <code>net.jini.discovery</code> package, and any service implementing this interface must comply with the definition of a River service. This interface is not a remote interface; each implementation of this service exports a front end proxy object that implements this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server (the back end). All of the proxy methods must obey normal Java Remote Method Invocation (RMI) remote interface semantics except where explicitly noted. Two proxy objects are equal (using the <code>equals</code> method) if they are prox
ies for the same lookup discovery service.
</p>
<p class="Body">
<a name="1005712"> </a>The one method defined in this interface throws a <code>RemoteException</code><code>, </code>and requires only the default serialization semantics so that this interface can be implemented directly using Java RMI.
@@ -257,7 +257,7 @@
<a name="1016285"> </a>If, between the time a lookup service is discarded and the time it is rediscovered, a new registration is requested having parameters indicating interest in that lookup service, upon rediscovery of the lookup service an event will also be sent to that new registration's listener.
</p>
<p class="Body">
- <a name="1016032"> </a>The sequence numbers for a given event identifier are strictly increasing (as defined in the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>), which means that when any two such successive events have sequence numbers that differ by only a value of 1, then no events have been missed. On the other hand, when the set of received events is viewed in order, if the difference between the sequence numbers of two successive events is greater than 1, then one or more events may or may not have been missed. For example, a difference greater than 1 could occur if the lookup discovery service crashes, even if no events are lost because of the crash. When two such successive events have sequence numbers whose difference is greater than 1, there is said to be a <em class="Emphasis">gap</em> between the events.
+ <a name="1016032"> </a>The sequence numbers for a given event identifier are strictly increasing (as defined in the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a>), which means that when any two such successive events have sequence numbers that differ by only a value of 1, then no events have been missed. On the other hand, when the set of received events is viewed in order, if the difference between the sequence numbers of two successive events is greater than 1, then one or more events may or may not have been missed. For example, a difference greater than 1 could occur if the lookup discovery service crashes, even if no events are lost because of the crash. When two such successive events have sequence numbers whose difference is greater than 1, there is said to be a <em class="Emphasis">gap</em> between the events.
</p>
<p class="Body">
<a name="1005149"> </a>When a gap occurs between events, the local state (on the client) related to the discovered lookup services may or may not fall out of sync with the corresponding remote state maintained by the lookup discovery service. For example, if the gap corresponds to a missed event representing the (initial) discovery of a targeted lookup service, the remote state will reflect this discovery, whereas the client's local state will not. To allow clients to identify and correct such a situation, each registration object provides a method that returns a set consisting of the proxies to the lookup services that have been discovered for that registration. With this information the client can update its local state.
@@ -266,7 +266,7 @@
<a name="1006050"> </a>When requesting a registration with the lookup discovery service, a client may also supply (as a parameter to the <code>register</code> method) a reference to an object, wrapped in a <code>MarshalledObject</code>, referred to as a <em class="Emphasis">handback</em>. When the lookup discovery service sends an event to a registration's listener, the event will also contain a reference to this handback object. The lookup discovery service will not change the handback object. That is, the handback object contained in the event sent by the lookup discovery service will be identical to the handback object registered by the client with the event mechanism.
</p>
<p class="Body">
- <a name="1010251"> </a>The semantics of the object input to the <code>handback</code> argument are left to each client to define, although <code>null</code> may be input to this argument. The role of the <code>handback</code> object in the remote event mechanism is detailed in the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>.
+ <a name="1010251"> </a>The semantics of the object input to the <code>handback</code> argument are left to each client to define, although <code>null</code> may be input to this argument. The role of the <code>handback</code> object in the remote event mechanism is detailed in the <a href="event-spec.html"><em class="Emphasis">River Distributed Events Specification</em></a>.
</p>
<h4 class="Heading3">
<a name="1003330"> </a>LD.3.3 Leasing Semantics
@@ -494,7 +494,7 @@
<a name="1004599"> </a>The <code>discard</code> method provides a mechanism for registered clients to inform the lookup discovery service of the existence of an unavailable--or <em class="Emphasis">unreachable</em>--lookup service, and to request that the lookup discovery service discard that lookup service and make it eligible for rediscovery.
</p>
<p class="Body">
- <a name="1002366"> </a>The <code>discard</code> method takes a single argument: the proxy to the lookup service to discard. This method takes no action if the parameter to this method equals none of the proxies reflected in the managed set (using proxy equality as defined in the <a href="lookup-spec.html"><em class="Emphasis">Jini Lookup Service Specification</em></a>. If <code>null</code> is passed to <code>discard</code>, a <code>NullPointerException</code> is thrown.
+ <a name="1002366"> </a>The <code>discard</code> method takes a single argument: the proxy to the lookup service to discard. This method takes no action if the parameter to this method equals none of the proxies reflected in the managed set (using proxy equality as defined in the <a href="lookup-spec.html"><em class="Emphasis">River Lookup Service Specification</em></a>. If <code>null</code> is passed to <code>discard</code>, a <code>NullPointerException</code> is thrown.
</p>
<p class="Body">
<a name="1015507"> </a>Although the lookup discovery service monitors the multicast announcements from all discovered lookup services for indications of unavailability, it should be noted that there are conditions under which the lookup discovery service will not discard such a lookup service, even when the lookup service is found to be unreachable. Whether or not the lookup discovery service discards such an unreachable lookup service is dependent on how each registration is configured for discovery with respect to that lookup service. If every registration that is configured to discover the unreachable lookup service is configured to discover it through locator discovery only, the lookup discovery service will not discard the lookup service. In other words, in order for the lookup discovery service to discard a lookup service it has determined is unreachable, at least one registration must be configured for discovery of at least one group in which that lookup service is
a member.
@@ -795,7 +795,7 @@
<a href="#skip" title="Skip navigation bar"></a>
<table width="100%"><tr>
<td align=left><a href="../../spec-index.html">Spec Index</a>
-<td align=right><em>A Collection of Jini Technology Helper Utilities and Services Specifications</em></td>
+<td align=right><em>A Collection of River Technology Helper Utilities and Services Specifications</em></td>
</tr></table>
<a name="skip"></a>
Modified: incubator/river/jtsk/trunk/doc/specs/html/lease-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/lease-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/lease-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/lease-spec.html Tue Jan 5 17:12:26 2010
@@ -22,7 +22,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
-<title>Jini Distributed Leasing Specification </title>
+<title>River Distributed Leasing Specification </title>
</head>
<body bgcolor="#ffffff">
@@ -31,7 +31,7 @@
<table width="90%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><em>Jini Technology Core Platform Specifications</em></td>
+<td align=right><em>River Technology Core Platform Specifications</em></td>
</tr>
</table>
<br clear="all">
@@ -46,7 +46,7 @@
</table>
<a name="skip"></a>
<blockquote>
-<h2 align="left">LE - Jini<font size="-1"><sup>TM</sup></font> Distributed Leasing Specification<br>
+<h2 align="left">LE - River Distributed Leasing Specification<br>
</h2>
<h3 class="Heading2">
<a name="1032977"> </a>LE.1 Introduction
@@ -486,7 +486,7 @@
<a href="#skip" title="Skip navigation bar"></a>
<table width="100%"><tr>
<td align=left><a href="../../spec-index.html">Spec Index</a>
-<td align=right><em>Jini Technology Core Platform Specifications</em></td>
+<td align=right><em>River Technology Core Platform Specifications</em></td>
</tr></table>
<a name="skip"></a>