You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by bu...@apache.org on 2010/12/24 20:54:37 UTC
svn commit: r781452 [9/17] - in
/websites/staging/river/trunk/content/river/doc/specs/html: ./ images/
Added: websites/staging/river/trunk/content/river/doc/specs/html/jxpnote-spec.html
==============================================================================
--- websites/staging/river/trunk/content/river/doc/specs/html/jxpnote-spec.html (added)
+++ websites/staging/river/trunk/content/river/doc/specs/html/jxpnote-spec.html Fri Dec 24 19:54:36 2010
@@ -0,0 +1,574 @@
+<!--
+ ! 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>
+<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>Introduction to Helper Utilities and Services </title>
+</head>
+<body bgcolor="#ffffff">
+<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><i>A Collection of Jini<font size="-1"><sup>TM</sup></font> Technology Helper Utilities and Services Specifications</i></td>
+</tr>
+</table>
+<br clear="all">
+
+
+<hr align="left">
+<table width="90%">
+<tr>
+<td align="right" font size="4"><b>Version 2.0</b></td>
+</tr>
+</table>
+<blockquote>
+<h2>
+ <a name="1007029"> </a>US - Introduction to Helper Utilities and Services
+</h2>
+<h3 class="Heading2">
+ <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:
+</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.
+</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.
+</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.
+</p>
+<h3 class="Heading2">
+ <a name="996907"> </a>US.2 Terminology
+</h3>
+<p class="Body">
+ <a name="1008988"> </a>This section defines terms and discusses concepts that may be referenced throughout the helper utilities and services specifications. While the terms and concepts that appear in this section are general in nature and may apply to multiple components specified in this collection, each specification may define additional terms and concepts to further facilitate the understanding of a particular component. Each specification may also present supplemental information about some of the terms defined in this section and their relationship with the component being specified.
+</p>
+
+<h4 class="Heading3">
+ <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.
+</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>.
+</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>.
+</p>
+<h4 class="Heading3">
+ <a name="998836"> </a>US.2.2 Jini 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.
+</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.
+</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.
+</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.
+</p>
+<h4 class="Heading3">
+ <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.
+</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.
+</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.
+</p>
+<h4 class="Heading3">
+ <a name="999384"> </a>US.2.5 Managed Sets
+</h4>
+<p class="Body">
+ <a name="999385"> </a>When performing discovery duties, entities will often maintain references to discovered lookup services in a set referred to as the <em class="Emphasis">managed set of lookup services</em>. The entity may also maintain two other notable sets: the <em class="Emphasis">managed set of groups</em> and the <em class="Emphasis">managed set of locators</em>.
+</p>
+<p class="Body">
+ <a name="999386"> </a>Each element of the managed set of groups is a name of a group whose members are lookup services that the entity wishes to be discovered via group discovery. The managed set of groups is typically represented as a <code>String</code> array, or a <code>Collection</code> of <code>String</code> elements.
+</p>
+<p class="Body">
+ <a name="999397"> </a>Each element of the managed set of locators corresponds to a specific lookup service that the entity wishes to be discovered via locator discovery. Typically, this set is represented as an array of <code>net.jini.core.discovery.LookupLocator</code> objects or some other <code>Collection</code> type whose elements are <code>LookupLocator</code> objects.
+</p>
+<p class="Body">
+ <a name="999388"> </a>Note that when the general term <em class="Emphasis">managed set</em> is used, it should be clear from the context whether groups, locators, or lookup services are being discussed.
+</p>
+
+
+<h4 class="Heading3">
+ <a name="1003583"> </a>US.2.6 Unavailable Lookup Services
+</h4>
+<p class="Body">
+ <a name="1003833"> </a>When an entity encounters an exception while interacting (or attempting to interact) with a lookup service, what may be concluded about the state of the lookup service is dependent on the type of exception that is encountered. For the purposes of this discussion, an exception that is encountered while interacting with a lookup service can be generally classified as either an <em>indefinite exception</em> or a <em>definite exception</em>.
+</p>
+<p class="Body">
+ The term <em>indefinite exception</em> refers to a category of exception where any such exception does not allow assertions to be made about the probability of success (or failure) of future attempts to perform the operation that caused the exception. A <code>RemoteException</code> caused by a transient communication failure is an example of an exception that can be classified as an indefinite exception. Whenever an entity encounters an indefinite exception while interacting with a lookup service, the entity can interpret the exception as a failure that may or may not be only temporary. Thus, retrying the failed operation at a later time may be advisable because the operation may succeed when retried.
+<p>
+The term <em>definite exception</em> refers to a category of exception where any such exception is indicative of a permanent failure. That is, when an operation fails with an exception that can be classified as a definite exception, that exception allows one to assert that any future attempts to perform the failed operation will also be met with failure. Whenever an entity encounters a definite exception while invoking a method on a proxy to a lookup service, it is generally not advisable to retry the operation, because it is very likely that failure will again result upon all future attempts to perform the operation that caused the exception. Additionally, the occurrence of a definite exception usually allows the entity to conclude that the proxy can no longer be used for any sort of interaction with the lookup service. Thus, all further interaction with the lookup service through the proxy should be discontinued until the problem is resolved.</p>
+<p class="Body">
+ <a name="1003878"> </a>Whenever an entity receives either type of exception -- definite or indefinite -- while interacting with a lookup service, the affected lookup service is referred to as <em class="Emphasis">unavailable</em> or <em class="Emphasis">unreachable</em>. For most entities the unavailability of a particular lookup service should not prevent the entity from continuing its processing. In general, whenever an entity encounters an unreachable lookup service, the entity may initially choose to apply some sort of retry strategy (for the case of an indefinite exception only). Once the entity is satisfied that the lookup service is truly unreachable, the associated exception or error condition should be caught and handled, usually by requesting that the lookup service be <em class="Emphasis">discarded</em> (see the next section), and the entity should continue its processing.
+</p>
+<h4 class="Heading3">
+ <a name="999437"> </a>US.2.7 Discarding a Lookup Service
+</h4>
+<p class="Body">
+ <a name="999438"> </a>When an already discovered lookup service is removed from the managed set of lookup services, it is said to be <em class="Emphasis">discarded</em>. The process of discarding a lookup service is initiated either directly or indirectly by the discovering entity itself or by the utility that the entity employs to perform the actual discovery duties.
+</p>
+<p class="Body">
+ <a name="1003971"> </a>Whenever a lookup service is discarded by a utility employed by the entity, the utility sends to all of the entity's discovery listeners, a notification event referencing both the discarded lookup service and the member groups to which the lookup service belongs. This event is referred to as a <em class="Emphasis">discarded event</em>. It may be useful to note that discarded events can be classified by two characteristics:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1003984"> </a>Whether the event was generated as a direct consequence of an explicit request made by the entity itself (<em class="Emphasis">active</em>) or as a consequence of a determination made by some utility employed by the entity (<em class="Emphasis">passive</em>)<p>
+ <li class="SmartList1"><a name="1003989"> </a>Whether the event is related to communication problems or to the entity losing interest in discovering the affected lookup services
+</ul>
+
+<h5 class="Heading4">
+ <a name="1003904"> </a>US.2.7.1 Active Communication Discarded Event
+</h5>
+<p class="Body">
+ <a name="1008199"> </a>When the occurrence of exceptional conditions causes an entity to conclude that a lookup service is unreachable, the entity typically will request that the lookup service be discarded. When the entity itself requests that such an unreachable lookup service be discarded, the resulting discarded event may be referred to as an <em class="Emphasis">active</em> <em class="Emphasis">communication discarded</em> <em class="Emphasis">event</em>. The term <em class="Emphasis">active</em> is used because the entity takes specific action to request that the lookup service be discarded. Because the entity cannot communicate with the unreachable lookup service, the event is associated with <em class="Emphasis">communication</em>.
+</p>
+<h5 class="Heading4">
+ <a name="1008202"> </a>US.2.7.2 Active No-Interest Discarded Event
+</h5>
+<p class="Body">
+ <a name="1003905"> </a>Whenever the entity makes a request that results in the removal of an element from the relevant managed set of groups or locators, one or more of the lookup services associated with the removed groups or locators may be discarded--even though the lookup services are still reachable. The lookup services may be discarded in this situation because the contents of the sets of groups and locators the entity wishes to discover may have changed in such a way that one or more of the previously discovered lookup services are no longer of interest to the entity. In this case, if any already discovered lookup service is found to belong to none of the groups in the new managed set of groups or if its locator no longer belongs to the entity's new managed set of locators, a discarded event is generated and sent to all of the entity's discovery listeners. This type of discarded event may be referred to as an <em class="Emphasis">active</em> <em class="Emphasis">no-
interest discarded</em> <em class="Emphasis">event</em> (active because the entity itself executed an action that resulted in the discarding of one or more lookup services).
+</p>
+<h5 class="Heading4">
+ <a name="1008213"> </a>US.2.7.3 Passive Communication Discarded Event
+</h5>
+<p class="Body">
+ <a name="1003906"> </a>If the utility that the entity uses to perform group (multicast) discovery determines that one of the previously discovered lookup services has stopped sending multicast announcements, that utility may discard the lookup service. That is, the utility may remove the lookup service from the managed set and send a discarded event to notify the entity that the lookup service is unavailable. The discarded event sent in this situation is often referred to as a <em class="Emphasis">passive</em> <em class="Emphasis">communication discarded</em> <em class="Emphasis">event</em>.
+</p>
+<h5 class="Heading4">
+ <a name="1008220"> </a>US.2.7.4 Passive No-Interest Discarded Event
+</h5>
+<p class="Body">
+ <a name="1008259"> </a>If the utility that the entity uses to perform group discovery determines that the member groups of one of the previously discovered lookup services has changed, the utility may discard that lookup service. The lookup service may be discarded in this situation because the lookup service may no longer be a member of any of the groups the entity wishes to discover; that is, the lookup service is no longer of interest to the entity. In this case, the utility sends a discarded event to all of the entity's discovery listeners. This type of discarded event may be referred to as a <em class="Emphasis">passive</em> <em class="Emphasis">no-interest discarded</em> <em class="Emphasis">event</em> (passive because the entity itself did not explicitly request that the lookup service be discarded).
+</p>
+<p class="Body">
+ <a name="1008225"> </a>If a lookup service is discarded because it was found to be unreachable (associated with a communication discarded event), that lookup service will be made eligible for rediscovery. In this case, the process of discarding a lookup service--either actively or passively--can be viewed as a mechanism for the removal of stale entries in the managed set of lookup services. Discarding such a lookup service removes the need for operations such as lease renewal attempts on a lookup service that is currently unavailable. Upon rediscovery of the discarded lookup service, the entity typically processes the rediscovered lookup service as if it were discovered for the first time.
+</p>
+<p class="Body">
+ <a name="1004075"> </a>Any lookup service corresponding to a no-interest discarded event is no longer eligible for discovery until one of the following occurs:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1008301"> </a>The entity changes its managed set of locators or its managed set of groups to include, either the discarded lookup service's locator or at least one of its member groups respectively.<p>
+ <li class="SmartList1"><a name="1008296"> </a>The set of member groups of the discarded lookup service is changed to include one or more of the groups the entity is currently interested in discovering.
+</ul>
+
+<h5 class="Heading4">
+ <a name="1008285"> </a>US.2.7.5 Changed Event
+</h5>
+<p class="Body">
+ <a name="1004081"> </a>An event related to the discarded event is referred to as a <em class="Emphasis">changed</em> <em class="Emphasis">event</em>. This event notifies the entity of changes in the contents of the member groups of one or more of the lookup services in the managed set. If the entity registers interest in such an event and if the utility that the entity uses to perform group discovery determines that one or more of those member group sets has indeed changed, then a changed event is sent.
+</p>
+<h5 class="Heading4">
+ <a name="1009010"> </a>US.2.7.6 Remote Objects, Stubs, and Proxies
+</h5>
+<p class="Body">
+ <a name="1009014"> </a>The <em class="Emphasis">JavaTM Remote Method Invocation Specification</em> defines a <em class="Emphasis">remote object</em> as an object whose methods can be invoked from a Java virtual machine (JVM)<a href="#1009017"><sup>1</sup></a>, potentially on a different host. Furthermore, the specification states that such an object is described by one or more <em class="Emphasis">remote interfaces</em>.
+</p>
+<p class="Body">
+ <a name="999028"> </a>When invoking methods remotely through Java Remote Method Invocation (Java RMI), it is useful to think of the invocation as consisting of two components: a client component and a server component. When the client component initiates a remote method call, the server component carries out the execution of the remote method, and Java RMI facilitates the necessary communication between the two parties. Note that in discussing concepts related to Java RMI, the term <em class="Emphasis">server</em> (or <em class="Emphasis">remote server</em>) is sometimes used in place of the term <em class="Emphasis">remote object</em>.
+</p>
+<p class="Body">
+ <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).
+</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.
+</p>
+<p class="Body">
+ <a name="999144"> </a>Another form that a proxy can take is that of the stub of a remote object. That is, all stubs are simply proxies to their corresponding remote objects. Except for the local methods <code>equals</code> and <code>hashCode</code>, this type of proxy consists of remote methods only.
+</p>
+<p class="Body">
+ <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.
+</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.
+</p>
+<h4 class="Heading3">
+ <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.
+</p>
+<h3 class="Heading2">
+ <a name="1009170"> </a>US.3 Introduction to the Helper Utilities
+</h3>
+<h4 class="Heading3">
+ <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:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="999470"> </a><code>DiscoveryManagement</code><p>
+ <li class="SmartList1"><a name="999479"> </a><code>DiscoveryGroupManagement</code><p>
+ <li class="SmartList1"><a name="999484"> </a><code>DiscoveryLocatorManagement</code>
+</ul>
+
+<p class="Body">
+ <a name="999489"> </a>Because the discovery management interfaces provide a uniform way to define utility classes that perform discovery-related management duties on behalf of an entity, the discovery utilities specification defines a number of helper utility classes that implement one or more of these interfaces. Those classes are:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1007065"> </a><code>LookupDiscovery</code><p>
+ <li class="SmartList1"><a name="1007066"> </a><code>LookupLocatorDiscovery</code><p>
+ <li class="SmartList1"><a name="1007067"> </a><code>LookupDiscoveryManager</code>
+</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>.
+</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>
+ <ul>
+ <li class="SmartList1"><code>Constants</code><p>
+ <li class="SmartList1"><code>OutgoingMulticastRequest</code><p>
+ <li class="SmartList1"><code>IncomingMulticastRequest</code><p>
+ <li class="SmartList1"><code>OutgoingMulticastAnnouncement</code><p>
+ <li class="SmartList1"><code>IncomingMulticastAnnouncement</code><p>
+ <li class="SmartList1"><code>OutgoingUnicastRequest</code><p>
+ <li class="SmartList1"><code>IncomingUnicastRequest</code><p>
+ <li class="SmartList1"><code>OutgoingUnicastResponse</code><p>
+ <li class="SmartList1"><code>IncomingUnicastResponse</code><p>
+ </ul>
+<h5 class="Heading4">
+ <a name="1007113"> </a>US.3.1.1 The <code>DiscoveryManagement</code> Interface
+</h5>
+<p class="Body">
+ <a name="1007114"> </a>The <code>DiscoveryManagement</code> interface defines methods related to the discovery event mechanism and discovery process termination. Through this interface an entity can register or unregister <code>DiscoveryListener</code> objects to receive discovery events, retrieve proxies to the currently discovered lookup services, discard a lookup service so that it is eligible for rediscovery, or terminate the discovery process.
+</p>
+<h5 class="Heading4">
+ <a name="1007118"> </a>US.3.1.2 The <code>DiscoveryGroupManagement</code> Interface
+</h5>
+<p class="Body">
+ <a name="1007132"> </a>The <code>DiscoveryGroupManagement</code> interface defines methods and constants related to the management of the set containing the names of the groups whose members are the lookup services that are to be discovered via group discovery. The methods of this interface define how an entity retrieves or modifies the managed set of groups to discover.
+</p>
+<h5 class="Heading4">
+ <a name="1007123"> </a>US.3.1.3 The <code>DiscoveryLocatorManagement</code> Interface
+</h5>
+<p class="Body">
+ <a name="1007138"> </a>The <code>DiscoveryLocatorManagement</code> interface defines methods related to the management of the set of <code>LookupLocator</code> objects corresponding to the specific lookup services that are to be discovered via locator discovery. The methods of this interface define how an entity retrieves or modifies the managed set of locators to discover.
+</p>
+<h5 class="Heading4">
+ <a name="1007078"> </a>US.3.1.4 The <code>LookupDiscovery</code> Helper Utility
+</h5>
+<p class="Body">
+ <a name="1007156"> </a>The <code>LookupDiscovery</code> helper utility encapsulates the functionality required of an entity that wishes to employ multicast discovery to discover a lookup service located within the entity's <em class="Emphasis">multicast radius</em>. This utility provides an implementation that makes the process of acquiring lookup service instances, based on no information other than group membership, which is much simpler for both services and clients.
+</p>
+<h5 class="Heading4">
+ <a name="1007104"> </a>US.3.1.5 The <code>LookupLocatorDiscovery</code> Helper Utility
+</h5>
+<p class="Body">
+ <a name="1007164"> </a>The <code>LookupLocatorDiscovery</code> helper utility encapsulates the functionality required of an entity that wishes to employ the unicast discovery protocol to discover a lookup service. This utility provides an implementation that makes the process of finding specific instances of a lookup service much simpler for both services and clients.
+</p>
+<h5 class="Heading4">
+ <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.
+</p>
+<h5 class="Heading4">US.3.1.7 The <code>ConstrainableLookupLocator</code> Utility</h5>
+<p>
+The <code>ConstrainableLookupLocator</code> class is a subclass of <code>net.jini.core.discovery.LookupLocator</code> that supports constraint operations through the <code>net.jini.core.constraint.RemoteMethodControl</code> interface. The constraints of an instance of this class control how that instance performs unicast.
+</p>
+<h5 class="Heading4">
+ <a name="1007295"> </a>US.3.1.8 The <code>Constants</code> Class
+</h5>
+<p class="Body">
+ <a name="1007309"> </a>The <code>Constants</code> class provides easy access to defined constants that may be useful when participating in the discovery process.
+</p>
+<h5 class="Heading4">
+ <a name="1007300"> </a>US.3.1.9 The <code>OutgoingMulticastRequest</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007301"> </a>The <code>OutgoingMulticastRequest</code> class provides facilities for marshalling multicast discovery requests into a form suitable for transmission over a network to announce one's interest in discovering a lookup service.
+</p>
+<h5 class="Heading4">
+ <a name="1007313"> </a>US.3.1.10 The <code>IncomingMulticastRequest</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007314"> </a>The facilities provided by the <code>IncomingMulticastRequest</code> class encapsulate the details of the process of unmarshalling received multicast discovery requests into a form in which the individual parameters of the request may be easily accessed.
+</p>
+<h5 class="Heading4">
+ <a name="1007318"> </a>US.3.1.11 The <code>OutgoingMulticastAnnouncement</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007319"> </a>The <code>OutgoingMulticastAnnouncement</code> class encapsulates the details of the process of marshalling multicast discovery announcements into a form suitable for transmission over a network to announce the availability of a lookup service to interested parties.
+</p>
+<h5 class="Heading4">
+ <a name="1007323"> </a>US.3.1.12 The <code>IncomingMulticastAnnouncement</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007324"> </a>The <code>IncomingMulticastAnnouncement</code> class encapsulates the details of the process of unmarshalling multicast discovery announcements into a form in which the individual parameters of the announcement may be easily accessed.
+</p>
+<h5 class="Heading4">
+ <a name="1007328"> </a>US.3.1.13 The <code>OutgoingUnicastRequest</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007329"> </a>The <code>OutgoingUnicastRequest</code> class encapsulates the details of the process of marshalling unicast discovery requests into a form suitable for transmission over a network to attempt discovery of a specific lookup service.
+</p>
+<h5 class="Heading4">
+ <a name="1007333"> </a>US.3.1.14 The <code>IncomingUnicastRequest</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007334"> </a>The <code>IncomingUnicastRequest</code> class encapsulates the details of the process of unmarshalling unicast discovery requests into a form in which the individual parameters of the request may be easily accessed.
+</p>
+<h5 class="Heading4">
+ <a name="1007338"> </a>US.3.1.15 The <code>OutgoingUnicastResponse</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007339"> </a>The <code>OutgoingUnicastResponse</code> class encapsulates the details of the process of marshalling a unicast discovery response into a form suitable for transmission over a network to respond to a unicast discovery request.
+</p>
+<h5 class="Heading4">
+ <a name="1007343"> </a>US.3.1.16 The <code>IncomingUnicastResponse</code> Utility
+</h5>
+<p class="Body">
+ <a name="1007344"> </a>The <code>IncomingUnicastResponse</code> class encapsulates the details of the process of unmarshalling a unicast discovery response into a form in which the individual parameters of the request may be easily accessed.
+</p>
+<h4 class="Heading3">
+ <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:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1007430"> </a><code>LeaseRenewalManager</code>
+</ul>
+
+<h5 class="Heading4">
+ <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.
+</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:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1007463"> </a><code>JoinManager</code>
+</ul>
+
+<h5 class="Heading4">
+ <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.
+</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:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1007522"> </a><code>ServiceDiscoveryManager</code>
+</ul>
+
+<h5 class="Heading4">
+ <a name="1007561"> </a>US.3.4.1 The <code>ServiceDiscoveryManager</code> Helper Utility
+</h5>
+<p class="Body">
+ <a name="1007552"> </a>The <code>ServiceDiscoveryManager</code> class is a helper utility class that any entity can use to create and populate a cache of service references, and with which the entity can register for notification of the availability of services of interest. Although the <code>ServiceDiscoveryManager</code> performs lookup discovery event handling for clients and services, the primary functionality the <code>ServiceDiscoveryManager</code> provides is service discovery and management.
+</p>
+<p class="Body">
+ <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.
+</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.
+</p>
+<h3 class="Heading2">
+ <a name="1007854"> </a>US.4 Introduction to the Helper Services
+</h3>
+<h4 class="Heading3">
+ <a name="1007857"> </a>US.4.1 The Lookup Discovery Service
+</h4>
+<p class="Body">
+ <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.
+</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.
+</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.
+</p>
+<h4 class="Heading3">
+ <a name="1007750"> </a>US.4.3 The Event Mailbox Service
+</h4>
+<p class="Body">
+ <a name="1007751"> </a>The <em class="Emphasis">event mailbox service </em>defined by the <code>net.jini.event.EventMailbox</code> interface is a helper service that can be employed by entities to store event notifications on their behalf. When an entity registers with the event mailbox service, that service will collect events intended for the registered entity until the entity initiates delivery of the events.
+</p>
+<p class="Body">
+ <a name="1007761"> </a>A service such as the event mailbox service can be particularly useful to entities that desire more control over the delivery of the events sent to them. Some entities operating in a distributed system may find it undesirable or inefficient to be contacted solely for the purpose of having an event delivered, preferring to defer the delivery to a time that is more convenient, as determined by the entity itself.
+</p>
+<p class="Body">
+ <a name="1007762"> </a>For example, an entity wishing to deactivate or detach from a network may wish to have its events stored until the entity is available to retrieve them. Additionally, some entities may wish to batch process event notifications for efficiency. In both scenarios, the entities described may find the event mailbox service useful in achieving their respective event delivery goals.
+</p>
+<h3 class="Heading2">
+ <a name="999526"> </a>US.5 Dependencies
+</h3>
+<p class="Body">
+ <a name="997297"> </a>The helper utilities and services specifications rely on one or more of the following specifications:
+</p>
+<ul>
+
+ <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>
+</ul>
+</p>
+
+<h2>
+ <a name="01886"> </a>US.6 History
+</h2>
+
+
+
+<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" summary="changes made to this specification">
+ <caption><p class="Body">
+ <a name="01887"> </a>
+</p>
+</caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Version</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td valign="top">v1.0</td>
+ <td>Initial release of this specification.</td>
+ </tr>
+ <tr>
+ <td valign="top">v2.0</td>
+ <td>Removed "What Exceptions Imply about Future Behavior", formerly US.2.6.<br>
+
+In the section titled, "Unavailable Lookup Services", defined `indefinite exception' and `definite exception', and removed references to `bad invocation exception' and `bad object exception'.<br>
+Added <code>ConstrainableLookupLocator</code> to the section titled, "Introduction to the Helper Utilities".</td>
+ </tr>
+</table>
+
+<P>
+ <a name="1009017"><a href="#1009014"><sup>1</sup></a> The terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.<br>
+
+<h3 class="Heading2">
+ <a name="0188"> </a> License
+</h3>
+<p>
+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.
+</blockquote>
+
+<hr>
+<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>
+</tr></table>
+<a name="skip"></a>
+
+<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>
+
+<!-- This HTML file was initially created with Quadralay WebWorks Publisher 3.5.0 -->
+<!-- by Susan Snyder -->
+<!-- Last updated: 01/28/05 -->