You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by si...@apache.org on 2010/12/24 20:54:07 UTC
svn commit: r1052569 [3/17] - in
/incubator/river/site/trunk/content/river/doc/specs/html: ./ images/
Added: incubator/river/site/trunk/content/river/doc/specs/html/discoveryutil-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/doc/specs/html/discoveryutil-spec.html?rev=1052569&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/doc/specs/html/discoveryutil-spec.html (added)
+++ incubator/river/site/trunk/content/river/doc/specs/html/discoveryutil-spec.html Fri Dec 24 19:54:05 2010
@@ -0,0 +1,1735 @@
+<!--
+ ! 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">
+<meta name="TEMPLATEBASE" content="JiniSpec1.1alpha">
+<meta name="LASTUPDATED" content="Mar 5, 2003">
+<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
+<title>Jini Discovery Utilities Specification - DU </title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<p> </p>
+<a href="#skip" title="Skip navigation bar"></a>
+<table width="100%"><td align=left><tr>
+<td align=left><a href="../../spec-index.html">Spec Index</a></td>
+<td align=right><i>A Collection of Jini Technology Helper Utilities and Services Specifications
+</i></td>
+</tr>
+</table>
+<a name="skip"></a>
+<br clear="all">
+
+
+<hr align="left">
+<table width="90%">
+<tr>
+<td align="right" font size="4"><b>Version 3.0</b></td>
+</tr>
+</table>
+
+<blockquote>
+<h2>
+ <a name="1022667"> </a>DU - Jini<font size="-1"><sup>TM</sup></font> Discovery Utilities Specification
+</h2>
+<h3 class="Heading2">
+ <a name="1022668"> </a>DU.1 Introduction
+</h3>
+<p class="Body">
+ <a name="1022672"> </a>Each discovering entity in a Java<font size="-1"><sup>TM</sup></font> virtual machine (JVM)<a href="#1022671"><sup>1</sup></a> on a given host is independently responsible for obtaining references to lookup services. In this specification we first cover a set of <em class="Emphasis">discovery management interfaces</em> that define the policies to apply when implementing helper utilities that manage an entity's discovery duties: in particular, the management of multicast (group) discovery and unicast (locator) discovery. After the discovery management interfaces are defined, a set of standard helper utility classes that implement one or more of those interfaces is presented. A utility for performing unicast discovery controlled by constraints is also described. This specification closes with a discussion of a set of lower-level utility classes that can be useful when applying the discovery management policies to build higher-level helper utilities for
discovery.
+</p>
+<h3 class="Heading3">
+ <a name="997296"> </a>DU.1.1 Dependencies
+</h3
+<p class="Body">
+ <a name="997297"> </a>This specification relies on the following other specifications:
+</p>
+<ul>
+
+ <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="lookup-spec.html">Jini<font size="-1"><sup>TM</sup></font> Lookup Service Specification</a></em><p>
+</ul>
+
+<h3 class="Heading2">
+ <a name="1022214"> </a>DU.2 The Discovery Management Interfaces
+</h3>
+<h4 class="Heading3">
+ <a name="1022215"> </a>DU.2.1 Overview
+</h4>
+<p class="Body">
+ <a name="1022216"> </a>Discovery is one behavior that is common to all entities wishing to interact with a Jini lookup service. Whether an entity is a client, a service, or a service acting as a client, the entity must first discover a lookup service, before the entity can begin interacting with that lookup service.
+</p>
+<p class="Body">
+ <a name="1022217"> </a>The interfaces collectively referred to as the <em class="Emphasis">discovery management</em> interfaces specify sets of methods that define a mechanism that may be used to manage various aspects of the discovery duties of entities that wish to participate in an application environment for Jini technology (a <em class="Emphasis">Jini application environment</em>). These interfaces provide a uniform way to define utility classes that perform the necessary discovery-related management duties on behalf of a client or service. Currently, there are three discovery management interfaces belonging to the package <code>net.jini.discovery</code>:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1022218"> </a><code>DiscoveryManagement</code><p>
+ <li class="SmartList1"><a name="1022219"> </a><code>DiscoveryGroupManagement</code><p>
+ <li class="SmartList1"><a name="1022220"> </a><code>DiscoveryLocatorManagement</code>
+</ul>
+
+<p class="Body">
+ <a name="1022221"> </a>The <code>DiscoveryManagement</code> interface defines semantics for methods related to the discovery event mechanism and discovery process termination. Through this interface, an entity can register or un-register for discovery events, discard a lookup service, or terminate the discovery process.
+</p>
+<p class="Body">
+ <a name="1022222"> </a>The <code>DiscoveryGroupManagement</code> interface defines methods related to the management of the sets of lookup services that are to be discovered using the multicast discovery protocols (see the <a href="discovery-spec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>). The methods of this interface define how an entity accesses or modifies the set of groups whose members are lookup services that the entity is interested in discovering through group discovery.
+</p>
+<p class="Body">
+ <a name="1022223"> </a>The <code>DiscoveryLocatorManagement</code> interface defines methods related to the management of the set of lookup services that are to be discovered using the unicast discovery protocol (as defined in the <a href="discovery-spec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>). The methods of this interface define how an entity accesses or modifies the contents of the set of <code>LookupLocator</code> objects corresponding to the specific lookup services the entity has targeted for locator discovery.
+</p>
+<p class="Body">
+ <a name="1022224"> </a>Although each interface defines semantics for methods involved in the management of the discovery process, the individual roles each interface plays in that process are independent of each other. Because of this independence, there may be scenarios where it is desirable to implement some subset of these interfaces.
+</p>
+<p class="Body">
+ <a name="1022225"> </a>For example, a class may wish to implement the functionality defined in <code>DiscoveryManagement</code>, but may not wish to allow entities to modify the groups and locators associated with the lookup services to be discovered. Such a class may have a "hard-coded" list of the groups and locators that it internally registers with the discovery process. For this case, the class would implement only <code>DiscoveryManagement</code>.
+</p>
+<p class="Body">
+ <a name="1029478"> </a>Alternatively, another class may not wish to allow the entity to register more than one listener with the discovery event mechanism; nor may it wish to allow the entity to terminate discovery. It may simply wish to allow the entity to modify the sets of lookup services that will be discovered. Such a class would implement both <code>DiscoveryGroupManagement</code> and <code>DiscoveryLocatorManagement</code>, but not <code>DiscoveryManagement</code>.
+</p>
+<p class="Body">
+ <a name="1029479"> </a>A specific example of a class that implements only a subset of the set of interfaces specified here is the <code>LookupDiscovery</code> utility class defined later in this specification. That class implements both the <code>DiscoveryManagement</code> and <code>DiscoveryGroupManagement</code> interfaces, but not the <code>DiscoveryLocatorManagement</code> interface.
+</p>
+<p class="Body">
+ <a name="1022228"> </a>Throughout this discussion of the discovery management interfaces, the phrase <em class="Emphasis">implementation class</em> refers to any concrete class that implements one or more of those interfaces. The phrase <em class="Emphasis">implementation object</em> should be understood to mean an instance of such an implementation class. Additionally, whenever a description refers to the <em class="Emphasis">discovering entity</em> (or simply, the <em class="Emphasis">entity</em><em class="Emphasis">), </em>that phrase is intended to be interpreted as the object (the client or service) that has created an implementation object, and which wishes to use the public methods specified by these interfaces and provided by that object.
+</p>
+<h4 class="Heading3">
+ <a name="1022229"> </a>DU.2.2 Other Types
+</h4>
+<p class="Body">
+ <a name="1022230"> </a>The types defined in the specification of the discovery management interfaces are in the <code>net.jini.discovery</code> package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
+</p>
+<pre class="Preformatted">
+net.jini.core.discovery.LookupLocator
+net.jini.core.lookup.ServiceRegistrar
+net.jini.discovery.DiscoveryEvent
+net.jini.discovery.DiscoveryListener
+net.jini.discovery.DiscoveryChangeListener
+net.jini.discovery.LookupDiscovery
+net.jini.discovery.LookupDiscoveryManager
+java.io.IOException
+java.security.Permission
+java.util.EventListener
+java.util.EventObject
+java.util.Map
+</code></pre>
+<h4 class="Heading3">
+ <a name="1022232"> </a>DU.2.3 The <code>DiscoveryManagement</code> Interface
+</h4>
+<p class="Body">
+ <a name="1022233"> </a>The public methods specified by the <code>DiscoveryManagement</code> interface are:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public interface DiscoveryManagement {
+ public void addDiscoveryListener
+ (DiscoveryListener listener);
+ public void removeDiscoveryListener
+ (DiscoveryListener listener);
+ public ServiceRegistrar[] getRegistrars();
+ public void discard(ServiceRegistrar proxy);
+ public void terminate();
+}
+</code></pre>
+<h5 class="Heading4">
+ <a name="1022235"> </a>DU.2.3.1 The Semantics
+</h5>
+<p class="Body">
+ <a name="1022236"> </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 un-register <code>DiscoveryListener</code> objects to receive discovery events (instances of <code>DiscoveryEvent</code>), retrieve proxies to the currently discovered lookup services, discard a lookup service so that it is eligible for re-discovery, or terminate the discovery process.
+</p>
+<p class="Body">
+ <a name="1022237"> </a>Implementation classes of this interface may impose additional semantics on any method. For example, such a class may choose to require that rather than simply terminate discovery processing, the <code>terminate</code> method additionally should cancel all leases held by the implementation object and terminate all lease management being performed on behalf of the entity.
+</p>
+<p class="Body">
+ <a name="1029495"> </a>For information on any additional semantics imposed on a method of this interface, refer to the specification of the particular implementation class.
+</p>
+<p class="Body">
+ <a name="1029496"> </a>The <code>DiscoveryEvent</code>, <code>DiscoveryListener</code>, and <code>DiscoveryChangeListener</code> classes are defined later in this specification.
+</p>
+<p class="Body">
+ <a name="1022240"> </a>The <code>addDiscoveryListener</code> method adds a listener to the set of objects listening for discovery events. This method takes a single argument as input: an instance of <code>DiscoveryListener</code> corresponding to the listener to add to the set.
+</p>
+<p class="Body">
+ <a name="1022241"> </a>Once a listener is registered, it will be notified of all lookup services discovered to date, and will then be notified as new lookup services are discovered or existing lookup services are discarded.
+</p>
+<p class="Body">
+ <a name="1022758"> </a>If the added listener is also an instance of <code>DiscoveryChangeListener</code> (a subclass of <code>DiscoveryListener</code>), then in addition to receiving events related to discovered and discarded lookup services, that listener will also be notified of group membership changes that occur in any of the lookup services targeted for at least group discovery.
+</p>
+<p class="Body">
+ <a name="1022242"> </a>If <code>null</code> is input to this method, a <code>NullPointerException</code> is thrown. If the <code>listener</code> input to this method duplicates (using the <code>equals</code> method) another element in the set of listeners, no action is taken.
+</p>
+<p class="Body">
+ <a name="1028666"> </a>Implementations of the <code>DiscoveryManagement</code> interface must guarantee reentrancy with respect to <code>DiscoveryListener</code> objects registered through this method. Should the instance of <code>DiscoveryManagement</code> invoke a method on a registered listener (a local call), calls from that method to any method of the <code>DiscoveryManagement</code> instance are guaranteed not to result in a deadlock condition.
+</p>
+<p class="Body">
+ <a name="1022243"> </a>The <code>removeDiscoveryListener</code> method removes a listener from the set of objects listening for discovery events. This method takes a single argument as input: an instance of <code>DiscoveryListener</code> corresponding to the listener to remove from the set.
+</p>
+<p class="Body">
+ <a name="1028673"> </a>If the listener object input to this method does not exist in the set of listeners maintained by the implementation class, then this method will take no action.
+</p>
+<p class="Body">
+ <a name="1022246"> </a>The <code>getRegistrars</code> method returns an array consisting of instances of the <code>ServiceRegistrar</code> interface. Each element in the returned set is a proxy to one of the currently discovered lookup services. Each time this method is invoked, a new array is returned. If no lookup services have been discovered, an empty array is returned. This method takes no arguments as input.
+</p>
+<p class="Body">
+ <a name="1022247"> </a>The <code>discard</code> method removes a particular lookup service from the managed set of lookup services, and makes that lookup service eligible to be re-discovered. This method takes a single argument as input: an instance of the <code>ServiceRegistrar</code> interface corresponding to the proxy to the lookup service to discard.
+</p>
+<p class="Body">
+ <a name="1029504"> </a>If the proxy input to this method is <code>null</code>, or if it matches (using the <code>equals</code> method) none of the lookup services in the managed set, this method takes no action.
+</p>
+<p class="Body">
+ <a name="1029505"> </a>Currently, there exist utilities such as the <code>LookupDiscovery</code> and <code>LookupDiscoveryManager</code> helper utilities that will, on behalf of a discovering entity, automatically discard a lookup service upon determining that the lookup service has become unreachable or uninteresting. Although most entities will typically employ such a utility to help with both its discovery as well as its discard duties, it is important to note that if the entity itself determines that the lookup service is unavailable, it is the responsibility of the entity to invoke the <code>discard</code> method. This scenario usually happens when the entity attempts to interact with a lookup service, but encounters an exceptional condition (for example, a communication failure). When the entity actively discards a lookup service, the discarded lookup service becomes eligible to be re-discovered. Allowing unreachable lookup services to remain in the managed set can r
esult in repeated and unnecessary attempts to interact with lookup services with which the entity can no longer communicate. Thus, the mechanism provided by this method is intended to provide a way to remove such "stale" lookup service references from the managed set.
+</p>
+<p class="Body">
+ <a name="1022250"> </a>Invoking the <code>discard</code> method defined by the <code>DiscoveryManagement</code> interface will result in the flushing of the lookup service from the appropriate cache, ultimately causing a discard notification--referred to as a <em class="Emphasis">discarded</em> <em class="Emphasis">event--</em>to be sent to all listeners registered with the implementation object. When this method completes successfully, the lookup service is guaranteed to have been removed from the managed set, and the lookup service is then said to have been "discarded". No such guarantee is made with respect to when the discarded event is sent to the registered listeners. That is, the event notifying the listeners that the lookup service has been discarded may or may not be sent asynchronously.
+</p>
+<p class="Body">
+ <a name="1022251"> </a>The <code>terminate</code> method ends all discovery processing being performed on behalf of the entity. This method takes no input arguments.
+</p>
+<p class="Body">
+ <a name="1022252"> </a>After this method has been invoked, no new lookup services will be discovered, and the effect of any new operations performed on the current implementation object are undefined.
+</p>
+<p class="Body">
+ <a name="1022253"> </a>Any additional termination semantics must be defined by the implementation class.
+</p>
+<h4 class="Heading3">
+ <a name="1022254"> </a>DU.2.4 The <code>DiscoveryGroupManagement</code> Interface
+</h4>
+<p class="Body">
+ <a name="1022255"> </a>The public methods specified by the <code>DiscoveryGroupManagement</code> interface are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public interface DiscoveryGroupManagement {
+ public static final String[] ALL_GROUPS = null;
+ public static final String[] NO_GROUPS = new String[0];
+
+ public String[] getGroups();
+ public void addGroups(String[] groups) throws IOException;
+ public void setGroups(String[] groups) throws IOException;
+ public void removeGroups(String[] groups);
+}
+</code></pre>
+<h5 class="Heading4">
+ <a name="1022257"> </a>DU.2.4.1 The Semantics
+</h5>
+<p class="Body">
+ <a name="1025531"> </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 using the multicast discovery protocols; that is, lookup services that are discovered by way of group discovery. The methods of this interface define how an entity retrieves or modifies the managed set of groups to discover, where phrases such as "the groups to discover" or "discovering the desired groups" refer to the discovery of the lookup services that are members of those groups.
+</p>
+<p class="Body">
+ <a name="1022259"> </a>The methods that modify the managed set of groups each take a single input parameter: a <code>String</code> array, none of whose elements may be <code>null</code>. Each of these methods throws a <code>NullPointerException</code> when at least one element of the input array is <code>null</code>.
+</p>
+<p class="Body">
+ <a name="1022260"> </a>The empty set is denoted by an empty array, and "no set" is indicated by <code>null</code>. Invoking any of these methods with an input array that contains duplicate group names is equivalent to performing the invocation with the duplicates removed from the array.
+</p>
+<p class="Body">
+ <a name="1022261"> </a>The <code>ALL_GROUPS</code> and the <code>NO_GROUPS</code> constants are defined for convenience, and represent no set and the empty set respectively.
+</p>
+<p class="Body">
+ <a name="1022262"> </a>The <code>getGroups</code> method returns an array consisting of the names of the groups in the managed set; that is, the names of the groups the implementation object is currently configured to discover.
+</p>
+<p class="Body">
+ <a name="1022263"> </a>If the managed set of groups is empty, this method will return an empty array. If there is no managed set of groups, then null (<code>ALL_GROUPS</code>) is returned, indicating that any lookup service within range--even those that have no group affiliation--are to be discovered.
+</p>
+<p class="Body">
+ <a name="1022918"> </a>If an empty array is returned, that array is guaranteed to be referentially equal to the <code>NO_GROUPS</code> constant; that is, the array returned from that method and the <code>NO_GROUPS</code> constant can be tested for equality using the <code>==</code> operator.
+</p>
+<p class="Body">
+ <a name="1022906"> </a>This method takes no arguments as input and, provided the managed set of groups currently exists, will return a new array upon each invocation.
+</p>
+<p class="Body">
+ <a name="1022264"> </a>The <code>addGroups</code> method adds a set of group names to the managed set. The array input to this method contains the group names to be added to the set.
+</p>
+<p class="Body">
+ <a name="1022267"> </a>This method throws <code>IOException</code> because an invocation of this method may result in the re-initiation of the discovery process, which can throw <code>IOException</code> when socket allocation occurs.
+</p>
+<p class="Body">
+ <a name="1022268"> </a>This method throws an <code>UnsupportedOperationException</code> if there is no managed set of groups to augment, and it throws a <code>NullPointerException</code> if <code>null</code> (<code>ALL_GROUPS</code>) is input. If an empty array (<code>NO_GROUPS</code>) is input, the managed set of groups will not change.
+</p>
+<p class="Body">
+ <a name="1022269"> </a>The <code>setGroups</code> method replaces all of the group names in the managed set with names from a new set. The array input to this method contains the group names with which to replace the current names in the managed set.
+</p>
+<p class="Body">
+ <a name="1022270"> </a>Once a new group name has been placed in the managed set, no event will be sent to the entity's listener for the lookup services belonging to that group that have already been discovered, although attempts to discover all (as yet) undiscovered lookup services belonging to that group will continue to be made.
+</p>
+<p class="Body">
+ <a name="1022271"> </a>If <code>null</code> (<code>ALL_GROUPS</code>) is input to <code>setGroups</code>, then attempts will be made to discover all (as yet) undiscovered lookup services located within the <em class="Emphasis">multicast radius (</em><a href="discoveryutil-spec.html#1003666">Section DU.3, "LookupDiscovery Utility"</a><em class="Emphasis">)</em> of the implementation object, regardless of group membership.
+</p>
+<p class="Body">
+ <a name="1026358"> </a>If an empty array (<code>NO_GROUPS</code>) is input to <code>setGroups</code>, then group discovery will be halted until the managed set of groups is changed--through a subsequent call to this method or to <code>addGroups</code>--to a set that is either a non-empty set of group names or <code>null</code> (<code>ALL_GROUPS</code>).
+</p>
+<p class="Body">
+ <a name="1026360"> </a>This method throws <code>IOException</code>. This is because an invocation of this method may result in the re-initiation of the discovery process, a process that can throw <code>IOException</code> when socket allocation occurs.
+</p>
+<p class="Body">
+ <a name="1022274"> </a>The <code>removeGroups</code> method deletes a set of group names from the managed set of groups. The array input to this method contains the group names to be removed from the managed set.
+</p>
+<p class="Body">
+ <a name="1022275"> </a>This method throws an <code>UnsupportedOperationException</code> if there is no managed set of groups from which to remove elements. If <code>null</code> (<code>ALL_GROUPS</code>) is input to <code>removeGroups</code>, a <code>NullPointerException</code> will be thrown.
+</p>
+<p class="Body">
+ <a name="1022962"> </a>If any element of the set of groups to be removed is not contained in the managed set, <code>removeGroups</code> takes no action with respect to that element. If an empty array (<code>NO_GROUPS</code>) is input, the managed set of groups will not change.
+</p>
+<p class="Body">
+ <a name="1022975"> </a>Once a new group name is added to the managed set as a result of an invocation of either <code>addGroups</code> or <code>setGroups</code>, attempts will be made--using the multicast request protocol--to discover all (as yet) undiscovered lookup services that are members of that group. If there are no responses to the multicast requests, the implementation object will stop sending multicast requests, and will simply listen for multicast announcements containing the new groups of interest.
+</p>
+<p class="Body">
+ <a name="1022276"> </a>Any already discovered lookup service that is a member of one or more of the groups removed from the managed set as a result of an invocation of either <code>setGroups</code> or <code>removeGroups</code> will be discarded and will no longer be eligible for discovery, but only if that lookup service satisfies both of the following conditions:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1022277"> </a>the lookup service is not a member of any group in the new managed set that resulted from the invocation of <code>setGroups</code> or <code>removeGroups</code>, and<p>
+ <li class="SmartList1"><a name="1022278"> </a>the lookup service is not currently eligible for discovery through other means (such as locator discovery).
+</ul>
+
+<h4 class="Heading3">
+ <a name="1022279"> </a>DU.2.5 The <code>DiscoveryLocatorManagement</code> Interface
+</h4>
+<p class="Body">
+ <a name="1022280"> </a>The public methods specified by the <code>DiscoveryLocatorManagement</code> interface are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public interface DiscoveryLocatorManagement {
+ public LookupLocator[] getLocators();
+ public void addLocators(LookupLocator[] locators);
+ public void setLocators(LookupLocator[] locators);
+ public void removeLocators(LookupLocator[] locators);
+}
+</code></pre>
+<h5 class="Heading4">
+ <a name="1022282"> </a>DU.2.5.1 The Semantics
+</h5>
+<p class="Body">
+ <a name="1025588"> </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 using the unicast discovery protocol; that is, lookup services that are discovered by way of locator discovery. The methods of this interface define how an entity retrieves or modifies the managed set of locators to discover. Phrases such as "the locators to discover" and "discovering the desired locators" refer to the discovery of the lookup services that are associated with those locators.
+</p>
+<p class="Body">
+ <a name="1022284"> </a>The methods that modify the managed set of locators each take a single input parameter: an array of <code>LookupLocator</code> objects, none of whose elements may be <code>null</code>. Each of these methods throws a <code>NullPointerException</code> when at least one element of the input array is <code>null</code>.
+</p>
+<p class="Body">
+ <a name="1022285"> </a>Invoking any of these methods with an input array that contains duplicate locators (as determined by <code>LookupLocator.equals</code>) is equivalent to performing the invocation with the duplicates removed from the array.
+</p>
+<p class="Body">
+ <a name="1023019"> </a>The <code>getLocators</code> method returns an array containing the set of <code>LookupLocator</code> objects in the managed set of locators; that is, the locators of the specific lookup services that the implementation object is currently interested in discovering.
+</p>
+<p class="Body">
+ <a name="1023037"> </a>The returned set includes both the set of locators corresponding to lookup services that have already been discovered and the set of those that have not yet been discovered.
+</p>
+<p class="Body">
+ <a name="1023041"> </a>If the managed set is empty, this method returns an empty array. This method takes no arguments as input, and returns a new array upon each invocation.
+</p>
+<p class="Body">
+ <a name="1023020"> </a>The <code>addLocators</code> method adds a set of locators to the managed set. The array input to this method contains the set of <code>LookupLocator</code> objects to add to the managed set.
+</p>
+<p class="Body">
+ <a name="1023058"> </a>If <code>null</code> is input to <code>addLocators</code>, a <code>NullPointerException</code> will be thrown. If an empty array is input, the managed set of locators will not change.
+</p>
+<p class="Body">
+ <a name="1022289"> </a>The <code>setLocators</code> method replaces all of the locators in the managed set with <code>LookupLocator</code> objects from a new set. The array input to this method contains the set of <code>LookupLocator</code> objects with which to replace the current locators in the managed set.
+</p>
+<p class="Body">
+ <a name="1026284"> </a>If <code>null</code> is input to <code>setLocators</code>, a <code>NullPointerException</code> will be thrown.
+</p>
+<p class="Body">
+ <a name="1026376"> </a>If an empty array is input to <code>setLocators</code>, then locator discovery will be halted until the managed set of locators is changed--through a subsequent call to this method or to <code>addLocators</code>--to a set that is non-null and non-empty.
+</p>
+<p class="Body">
+ <a name="1022291"> </a>The <code>removeLocators</code> method deletes a set of locators from the managed set. The array input to this method contains the set of <code>LookupLocator</code> objects to remove from the managed set.
+</p>
+<p class="Body">
+ <a name="1022292"> </a>If <code>null</code> is input to <code>removeLocators</code>, a <code>NullPointerException</code> will be thrown.
+</p>
+<p class="Body">
+ <a name="1023074"> </a>If any element of the set of locators to remove is not contained in the managed set, <code>removeLocators</code> takes no action with respect to that element. If an empty array is input, the managed set of locators will not change.
+</p>
+<p class="Body">
+ <a name="1023095"> </a>Any already discovered lookup service, corresponding to a locator that is a member of the set of locators removed from the managed set as a result of an invocation of either <code>setLocators</code> or <code>removeLocators</code>, will be discarded and will no longer be eligible for discovery, but only if it is not currently eligible for discovery through other means (such as group discovery).
+</p>
+<h4 class="Heading3">
+ <a name="1023110"> </a>DU.2.6 Supporting Interfaces and Classes
+</h4>
+<p class="Body">
+ <a name="1023111"> </a>Discovery management depends on the interfaces <code>DiscoveryListener</code> and <code>DiscoveryChangeListener</code>, and on the concrete class <code>DiscoveryEvent</code>.
+</p>
+<h5 class="Heading4">
+ <a name="1023113"> </a>DU.2.6.1 The <code>DiscoveryListener</code> Interface
+</h5>
+<p class="Body">
+ <a name="1023163"> </a>The public methods specified by the <code>DiscoveryListener</code> interface are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public interface DiscoveryListener extends EventListener {
+ public void discovered(DiscoveryEvent e);
+ public void discarded(DiscoveryEvent e);
+}
+</code></pre>
+<p class="Body">
+ <a name="1023634"> </a>When an entity employs an object that implements one or more of the discovery management interfaces to perform and manage the entity's discovery duties, the entity often will want that object--generally referred to as a <em class="Emphasis">discovery utility--</em>to notify the entity when a desired lookup service is either discovered or discarded. The <code>DiscoveryListener</code> interface defines a mechanism through which an entity may receive such notifications from a discovery utility. When an entity registers interest in these notifications, an implementation of this interface must be provided to the discovery utility being employed. Through this registered listener, the entity may then receive instances of the <code>DiscoveryEvent</code> class, which encapsulate the required information associated with the desired notifications.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="1023707"> </a>The Semantics<br>
+</div>
+<p class="Body">
+ <a name="1023708"> </a>The events received by listeners implementing the <code>DiscoveryListener</code> interface can be the result of either group discovery or locator discovery. These events contain the discovered or discarded registrars, as well as the set of member groups corresponding to each registrar (see the specification of the <code>DiscoveryEvent</code> class).
+</p>
+<p class="Body">
+ <a name="1023722"> </a>The <code>discovered</code> method is called whenever a new lookup service is discovered or a discarded lookup service is re-discovered.
+</p>
+<p class="Body">
+ <a name="1023791"> </a>The <code>discarded</code> method is called whenever a previously discovered lookup service is discarded because the lookup service was determined to be either unreachable or no longer interesting to the entity, and the discard process was initiated by either the entity itself (an <em class="Emphasis">active</em> discard) or the discovery utility employed by the entity (a <em class="Emphasis">passive</em> discard).
+</p>
+<p class="Body">
+ <a name="1029102"> </a>The <code>DiscoveryGroupManagement</code> interface makes the following concurrency guarantee: for any given listener object that implements this interface or any sub-interface, no two methods defined by the interface or sub-interface will be invoked at the same time. This applies to different invocations of the same or different methods, on the same or different listeners registered with a single <code>DiscoveryManagement</code> instance. For example, the <code>discovered</code> method of one listener will not be invoked while the invocation of another listener's <code>discovered</code> or <code>discarded</code> method is in progress. Similarly, the one listener's <code>discovered</code> method will not be invoked while that same listener's <code>discard</code> method is in progress.
+</p>
+<h5 class="Heading4">
+ <a name="1023759"> </a>DU.2.6.2 The <code>DiscoveryChangeListener</code> Interface
+</h5>
+<p class="Body">
+ <a name="1023782"> </a>The <code>DiscoveryChangeListener</code> interface specifies only one public method:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public interface DiscoveryChangeListener
+ extends DiscoveryListener
+{
+ public void changed(DiscoveryEvent e);
+}
+</pre>
+<p class="Body">
+ <a name="1023762"> </a>In addition to being notified when a desired lookup service is discovered or discarded, some entities may also wish to be notified when a lookup service experiences changes in its group membership. The <code>DiscoveryChangeListener</code> interface defines an extension to the <code>DiscoveryListener</code> interface, providing a mechanism through which an entity may receive these additional notifications--referred to as <em class="Emphasis">changed</em> <em class="Emphasis">events</em>. As with the <code>DiscoveryListener</code> interface, when an entity wishes to receive changed events in addition to discovered and discarded events, an implementation of this interface must be provided to the discovery utility being employed. It is through that registered listener that the entity receives the desired notifications encapsulated in instances of the <code>DiscoveryEvent</code> class.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="1023877"> </a>The Semantics<br>
+</div>
+<p class="Body">
+ <a name="1023878"> </a>When the entity receives a <code>DiscoveryEvent</code> object through an instance of the <code>DiscoveryChangeListener</code> interface, the event contains the discovered, discarded, or changed registrars, as well as the set of member groups corresponding to each registrar. In the case of a changed event, each set of groups referenced in the event contains the new groups in which the corresponding registrar is a member.
+</p>
+<p class="Body">
+ <a name="1023765"> </a>The <code>changed</code> method is called whenever the discovery utility encounters changes in the set of groups in which a previously discovered lookup service is a member.
+</p>
+<p class="Body">
+ <a name="1024039"> </a>It is important to note that instances of this interface are eligible to receive changed events for only those lookup services that the entity has requested be discovered by (at least) group discovery. That is, if the entity requests that <em class="Emphasis">only</em> locator discovery be used to discover a specific lookup service, the listener will receive no changed events for that lookup service. This is because the semantics of this interface assume that since the entity expressed no interest in <em class="Emphasis">discovering</em> the lookup service through its group membership, it must also have no interest in any <em class="Emphasis">changes</em> in that lookup service's group membership. Thus, if an entity wishes to receive changed events for one or more lookup services, the entity must request that those lookup services be discovered by either group discovery alone, or by both group and locator discovery.
+</p>
+<h5 class="Heading4">
+ <a name="1023120"> </a>DU.2.6.3 The <code>DiscoveryEvent</code> Class
+</h5>
+<p class="Body">
+ <a name="1023294"> </a>The public methods provided by the <code>DiscoveryEvent</code> class are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public class DiscoveryEvent extends EventObject {
+ public DiscoveryEvent(Object source, Map groups) {...}
+ public DiscoveryEvent(Object source,
+ ServiceRegistrar[] regs) {...}
+ public Map getGroups() {...}
+ public ServiceRegistrar[] getRegistrars() {...}
+}
+</pre>
+<p class="Body">
+ <a name="1023597"> </a>The <code>DiscoveryEvent</code> class provides an encapsulation of event information that discovery utilities can use to notify an entity of the occurrence of an event involving one or more <code>ServiceRegistrar</code> objects (lookup services) in which the entity has registered interest. Discovery utilities pass an instance of this class to the entity's discovery listener(s) when one of the following events occurs:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1024126"> </a>Each lookup service referenced in the event has been discovered for the first time, or re-discovered after having been discarded.<p>
+ <li class="SmartList1"><a name="1024130"> </a>Each lookup service referenced in the event has been either actively or passively discarded.<p>
+ <li class="SmartList1"><a name="1024178"> </a>For each lookup service referenced in the event, the set of groups in which the lookup service is a member has changed.
+</ul>
+
+<p class="Body">
+ <a name="1024179"> </a>The <code>DiscoveryEvent</code> class is a subclass of <code>EventObject</code>, adding the following additional items of abstract state: a set of <code>ServiceRegistrar</code> instances (<em class="Emphasis">registrars</em>) referencing the affected lookup services, and a mapping from each of those registrars to their current set of member groups. Methods are defined through which this additional state may be retrieved upon receipt of an instance of this class.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="1024079"> </a>The Semantics<br>
+</div>
+<p class="Body">
+ <a name="1024215"> </a>The <code>equals</code> method for this class returns <code>true</code> if and only if two instances of this class refer to the same object. That is, <code>x</code> and <code>y</code> are equal instances of this class if and only if <code>x</code> <code>==</code> <code>y</code> has the value <code>true</code>.
+</p>
+<p class="Body">
+ <a name="1024384"> </a>The constructor for this class has two forms, where both forms expect two input parameters. Each form of the constructor takes, as its first input parameter, a reference to the source of the event; that is, the discovery utility object that created the event instance and sent it to the entity's listener(s) through the invocation of the <code>discovered</code>, <code>discarded</code>, or <code>changed</code> method on each listener. Note that neither form of the constructor makes a copy of the second parameter. That is, the reference input to the second parameter is shared with the invoking entity.
+</p>
+<p class="Body">
+ <a name="1028739"> </a>Depending on the constructor employed, the second parameter is one of the following:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1024385"> </a>A <code>Map</code> instance in which each element of the map's key set is a <code>ServiceRegistrar</code> instance that references one of the lookup services to be associated with the event being constructed. Each element of the map's value set is a <code>String</code> array, containing the names of the groups in which the corresponding lookup service is a member.<p>
+ <li class="SmartList1"><a name="1024277"> </a>An array of <code>ServiceRegistrar</code> instances in which each element references one of the lookup services to be associated with the event being constructed.<p>
+
+It is important to note that when this form of the constructor is used to construct a <code>DiscoveryEvent</code>, although the resulting event contains a <code>non-null</code> registrars array, the registrars-to-groups map is <code>null</code>. Therefore, discovery utilities should no longer use this constructor to instantiate the events they send.
+</ul>
+
+<p class="Body">
+ <a name="1024444"> </a>The <code>getGroups</code> method returns the mapping from each registrar referenced by the event to the registrar's current set of member groups. If the event was instantiated using the constructor whose second parameter is an array of <code>ServiceRegistrar</code> instances, this method will return <code>null</code>.
+</p>
+<p class="Body">
+ <a name="1024463"> </a>The returned map's key set is made up of <code>ServiceRegistrar</code> instances corresponding to the lookup services for which the event was constructed and sent. Each element of the returned map's value set is a <code>String</code> array, containing the names of the member groups of the corresponding lookup service.
+</p>
+<p class="Body">
+ <a name="1024451"> </a>On each invocation of this method, the same <code>Map</code> object is returned; that is, a copy is not made.
+</p>
+<p class="Body">
+ <a name="1024415"> </a>The <code>getRegistrars</code> method returns an array of <code>ServiceRegistrar</code> instances, in which each element references one of the lookup services for which the event was constructed and sent.
+</p>
+<p class="Body">
+ <a name="1024486"> </a>On each invocation of this method, the same array is returned; that is, a copy is not made.
+</p>
+<h4 class="Heading3">
+ <a name="1024575"> </a>DU.2.7 Serialized Forms<p>
+<CENTER>
+<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
+ cellpadding="5" cellspacing="0" Summary="serialized forms of <CODE>DiscoveryEvent</CODE>">
+ <caption></caption>
+ <tr bgcolor="#CCCCCC">
+ <th><a name="1029526"> </a>Class<br></th>
+ <th><a name="1029528"> </a><code>serialVersionUID</code><br></th>
+ <th><a name="1029530"> </a>Serialized Fields<br></th>
+ </tr>
+ <tr>
+ <td><a name="1029532"> </a><code>DiscoveryEvent</code><br></td>
+ <td><a name="1029534"> </a>5280303374696501479L<br></td>
+ <td><a name="1029536"> </a><div class="CellBody"><code>ServiceRegistrar[] regs</code></div><a name="1029537"> </a><code>Map groups</code></td>
+ </tr>
+</table>
+</CENTER>
+
+
+
+</h4>
+<p class="Body">
+ <a name="1024548"> </a>
+</p>
+<h3 class="Heading2">
+ <a name="1003666"> </a>DU.3 <code>LookupDiscovery</code> Utility
+</h3>
+<h4 class="Heading3">
+ <a name="10246"> </a>DU.3.1 Overview
+</h4>
+<p class="Body">
+
+ <a name="1003668"> </a>In a Jini application environment the multicast discovery protocols are often collectively referred to as multicast discovery or group discovery. The entities that participate in the multicast discovery protocol are a <em class="Emphasis">discovering entity</em> (Jini client or service) and a Jini lookup service, which acts as the entity that is to be discovered. When the discovering entity starts, it uses the multicast request protocol to announce its interest in finding lookup services within range. After a specified amount of time, the entity stops sending multicast requests, and simply listens for multicast announcements from any lookup services within range that may be broadcasting their availability. Through either of these protocols, the discovering entity can obtain references to lookup services belonging to member group in which the entity is interested. For the details of the multicast discovery protocols, refer to the <a href="discovery-sp
ec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>.
+</p>
+<p class="Body">
+ <a name="1024620"> </a>The <code>LookupDiscovery</code> helper utility in the package <code>net.jini.discovery</code> 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> (roughly, the number of hops beyond which neither the multicast requests from the entity, nor the multicast announcements from the lookup service, will propagate). This utility provides an implementation that makes the process of acquiring lookup service instances, based on no information other than group membership, much simpler for both services and clients.
+</p>
+<h4 class="Heading3">
+ <a name="1024688"> </a>DU.3.2 Other Types
+</h4>
+<p class="Body">
+ <a name="1025640"> </a>The types defined in the specification of the <code>LookupDiscovery</code> utility class are in the <code>net.jini.discovery</code> package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
+</p>
+<p class="Body">
+ <a name="1025641"> </a>
+</p>
+<pre class="Preformatted">
+net.jini.core.discovery.LookupLocator
+net.jini.config.Configuration
+net.jini.config.ConfigurationException
+net.jini.discovery.DiscoveryManagement
+net.jini.discovery.DiscoveryGroupManagement
+net.jini.discovery.DiscoveryPermission
+java.io.IOException
+java.io.Serializable
+java.security.Permission
+</code></pre>
+<h4 class="Heading3">
+ <a name="1024714"> </a>DU.3.3 The Interface
+</h4>
+<p class="Body">
+ <a name="1024692"> </a>The public methods provided by the <code>LookupDiscovery</code> class are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public class LookupDiscovery
+ implements DiscoveryManagement,
+ DiscoveryGroupManagement
+{
+ public static final String[] ALL_GROUPS
+ = DiscoveryGroupManagement.ALL_GROUPS;
+ public static final String[] NO_GROUPS
+ = DiscoveryGroupManagement.NO_GROUPS;
+
+ public LookupDiscovery(String[] groups)
+ throws IOException {...}
+ public LookupDiscovery(String[] groups,
+ ConFiguration config)
+ throws IOException, ConfigurationException {...}
+
+}
+</pre>
+<h4 class="Heading3">
+ <a name="1024748"> </a>DU.3.4 The Semantics
+</h4>
+<p class="Body">
+ <a name="1025460"> </a>The only new public method of the <code>LookupDiscovery</code> helper utility class is the constructor. All other public methods implemented by this class are specified in the <code>DiscoveryManagement</code> and the <code>DiscoveryGroupManagement</code> interfaces.
+</p>
+<p class="Body">
+ <a name="1025462"> </a>Each instance of the <code>LookupDiscovery</code> class must behave as if it operates independently of all other instances.
+</p>
+<p class="Body">
+ <a name="1024750"> </a>The <code>equals</code> method for this class returns <code>true</code> if and only if two instances of this class refer to the same object. That is, <code>x</code> and <code>y</code> are equal instances of this class if and only if <code>x</code> <code>==</code> <code>y</code> has the value <code>true</code>.
+</p>
+<p class="Body">
+ <a name="1024844"> </a>For convenience, this class defines the constants <code>ALL_GROUPS</code> and <code>NO_GROUPS</code>, which represent no set and the empty set respectively. For more information on these constants, refer to the specification of the <code>DiscoveryGroupManagement</code> interface.
+</p>
+<p>
+The constructor for the <code>LookupDiscovery</code> class has two versions. Each version of the constructor throws <code>IOException</code> because construction of a <code>LookupDiscovery</code> object can cause the initiation of the multicast discovery process, a process that can throw <code>IOException</code>.
+<p>
+The only difference between the two versions of the constructor is the absence or presence of a parameter of type <code>Configuration</code>, which is used to classify the constructors as either <em>non-configurable</em> or <em>configurable</em>, respectively.
+<p class="Body">
+ <a name="1024846"> </a>The single input parameter shared by both versions of the constructor is a <code>String</code> array, none of whose elements may be <code>null</code>. If at least one element of that input array is <code>null</code>, a <code>NullPointerException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="1024811"> </a>Constructing this class using an input array that contains duplicate group names is equivalent to constructing the class using an array with the duplicates removed.
+</p>
+<p class="Body">
+ <a name="1024827"> </a>If <code>null</code> (<code>ALL_GROUPS</code>) is input to the constructor, then attempts will be made to discover all lookup services located within the current multicast radius, regardless of group membership.
+</p>
+<p class="Body">
+ <a name="1029546"> </a>Although discovery events will not be sent by this class until a listener is added through an invocation of the <code>addListener</code> method, discovery processing usually starts as soon as an instance of this class is constructed. However, if an empty array (<code>NO_GROUPS</code>) is passed to the constructor, discovery will not be started until the <code>addGroups</code> or <code>setGroups</code> method is called to change the initial empty set of groups to either a non-empty set, or <code>null</code> (<code>ALL_GROUPS</code>).
+</p>
+<p class="Body">
+As noted, the configurable version of the constructor is characterized by an additional parameter of type <code>Configuration</code>. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting <code>LookupDiscovery</code> instance. Such customizations are implementation dependent. A <code>NullPointerException</code> is thrown if <code>null</code> is passed as the value of that parameter. A <code>ConfigurationException</code> is thrown to indicate that a problem occurred while attempting to retrieve an item from the given <code>Configuration</code>.
+<p>
+Creating a <code>LookupDiscovery</code> object using the non-configurable version of the constructor will result in an instance of <code>LookupDiscovery</code> having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.
+</p>
+<h4 class="Heading3">
+ <a name="1025042"> </a>DU.3.5 Supporting Interfaces and Classes
+</h4>
+<p class="Body">
+ <a name="1025066"> </a>The <code>LookupDiscovery</code> helper utility class depends on the interfaces <code>DiscoveryManagement</code> and <code>DiscoveryGroupManagement</code>, and on the concrete class <code>DiscoveryPermission</code>.
+</p>
+<h5 class="Heading4">
+ <a name="1025277"> </a>DU.3.5.1 The <code>DiscoveryManagement</code> Interfaces
+</h5>
+<p class="Body">
+ <a name="1025278"> </a>The <code>LookupDiscovery</code> class implements both the <code>DiscoveryManagement</code> and the <code>DiscoveryGroupManagement</code> interfaces, which together define methods related to the coordination and management of all group discovery processing. See <a href="discoveryutil-spec.html#1022214">Section DU.2, "The Discovery Management Interfaces"</a> for more information on those interfaces.
+</p>
+<h5 class="Heading4">
+ <a name="1025067"> </a>DU.3.5.2 Security and Multicast Discovery: The <code>DiscoveryPermission</code> Class
+</h5>
+<p class="Body">
+ <a name="1025095"> </a>When an instance of the <code>LookupDiscovery</code> class is constructed, the entity that creates the instance must be granted appropriate discovery permission. For example, if the instance of <code>LookupDiscovery</code> is currently configured to discover a non-empty, non-<code>null</code> set of groups, then the entity that created the instance must have permission to attempt discovery of each of the groups in that set. If the set of groups to discover is <code>null</code> (<code>ALL_GROUPS</code>), then the entity must have permission to attempt discovery of all possible groups. If appropriate permissions are not granted, the constructor of <code>LookupDiscovery</code>, as well as the methods <code>addGroups</code> and <code>setGroups</code>, will throw a <code>java.lang.SecurityException</code>.
+</p>
+<p class="Body">
+ <a name="1025096"> </a> Discovery permissions are controlled in security policy files using the permission class <code>DiscoveryPermission</code>. The public methods provided by the <code>DiscoveryPermission</code> class are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public final class DiscoveryPermission extends Permission
+ implements Serializable
+{
+ public DiscoveryPermission(String group) {...}
+ public DiscoveryPermission(String group,
+ String actions) {...}
+}
+</pre>
+<p class="Body">
+ <a name="1025112"> </a>The <code>DiscoveryPermission</code> class is a subclass of <code>Permission</code>, adding no additional items of abstract state.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="1025113"> </a>The Semantics<br>
+</div>
+<p class="Body">
+ <a name="1025114"> </a>The <code>equals</code> method for this class returns <code>true</code> if and only if two instances of this class have the same group name.
+</p>
+<p class="Body">
+ <a name="1025116"> </a>The constructor for this class has two forms: one form expecting one input parameter, the other form expecting two input parameters. Each form of the constructor takes, as its first input parameter, a <code>String</code> representing one or more group names for which to allow discovery.
+</p>
+<p class="Body">
+ <a name="1025155"> </a>The second parameter of the second form of the constructor is a <code>String</code> value that is currently ignored because there are no actions associated with a discovery permission.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="1025165"> </a><code>DiscoveryPermission</code> Examples<br>
+</div>
+<p class="Body">
+ <a name="1025166"> </a>A number of examples that illustrate the use of this permission are presented. Note that each example represents a line in a policy file.
+</p>
+<a name="1025174"> </a><code>permission net.jini.discovery.DiscoveryPermission "*";</code><br>
+<a name="1025175"> </a>Grant the entity permission to attempt discovery of all possible groups<p>
+<a name="1025176"> </a><code>permission net.jini.discovery.DiscoveryPermission "";</code><br>
+<a name="1025177"> </a>Grant the entity permission to attempt discovery of only the "public" group<p>
+<a name="1025178"> </a><code>permission net.jini.discovery.DiscoveryPermission "foo";</code><br>
+<a name="1025179"> </a>Grant the entity permission to attempt discovery of the group named "foo"<p>
+<a name="1025180"> </a><code>permission net.jini.discovery.DiscoveryPermission "*.sun.com";</code><br>
+<a name="1025181"> </a>Grant the entity permission to attempt discovery of all groups whose names end with the substring ".sun.com"<p>
+<p class="Body">
+ <a name="1025182"> </a>Each of the above declarations grants permission to attempt discovery of one name. A name does not necessarily correspond to a single group. That is, the following should be noted:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1025183"> </a>The name <code>"*"</code> grants permission to attempt discovery of <em class="Emphasis">all</em> possible groups.<p>
+ <li class="SmartList1"><a name="1025184"> </a>A name beginning with <code>"*."</code> grants permission to attempt discovery of all groups that match the <em class="Emphasis">remainder</em> of that name; for example, the name <code>"*.example.org"</code> would match a group named <code>"foonly.example.org"</code> and also a group named <code>"sf.ca.example.org"</code>.<p>
+ <li class="SmartList1"><a name="1025185"> </a>The empty name <code>""</code> denotes the <em class="Emphasis">public</em> group.<p>
+ <li class="SmartList1"><a name="1025186"> </a>All other names are treated as individual groups and must match exactly.
+</ul>
+
+<p class="Body">
+ <a name="1025204"> </a>Finally, it is important to note that a restriction of the Java2 platform security model requires that appropriate <code>DiscoveryPermission</code> be granted to the Jini technology infrastructure software codebase itself, in addition to any codebases that may use Jini technology infrastructure software classes.
+</p>
+<h4 class="Heading3">
+ <a name="1003769"> </a>DU.3.6 Serialized Forms<p>
+<CENTER>
+<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
+ cellpadding="5" cellspacing="0" Summary="serialized forms of <code>DiscoveryPermission</code>">
+ <caption></caption>
+ <tr bgcolor="#CCCCCC">
+ <th><a name="1029553"> </a>Class<br></th>
+ <th><a name="1029555"> </a><code>serialVersionUID</code><br></th>
+ <th><a name="1029557"> </a>Serialized Fields<br></th>
+ </tr>
+ <tr>
+ <td><a name="1029559"> </a><code>DiscoveryPermission</code><br></td>
+ <td><a name="1029561"> </a>-3036978025008149170L<br></td>
+ <td><em class="Emphasis">none</em></td>
+ </tr>
+</table>
+</CENTER>
+
+
+
+</h4>
+<h3 class="Heading2">
+ <a name="1022345"> </a>DU.4 The <code>LookupLocatorDiscovery</code> Utility
+</h3>
+<h4 class="Heading3">
+ <a name="1022346"> </a>DU.4.1 Overview
+</h4>
+<p class="Body">
+ <a name="1022347"> </a>The <a href="discovery-spec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>, states that the "unicast discovery protocol is a simple request-response protocol." In a Jini application environment, the entities that participate in this protocol are a discovering entity (Jini client or service) and a Jini lookup service that acts as the entity to be discovered. The discovering entity sends unicast discovery requests to the lookup service, and the lookup service reacts to those requests by sending unicast discovery responses to the interested discovering entity.
+</p>
+<p class="Body">
+ <a name="1022348"> </a>The <code>LookupLocatorDiscovery</code> helper utility (belonging to the package <code>net.jini.discovery</code>) 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>
+<p class="Body">
+ <a name="1022349"> </a>Because the <code>LookupLocatorDiscovery</code> helper utility class will participate in only the unicast discovery protocol, and because the unicast discovery protocol imposes no restriction on the physical location of a service or client relative to a lookup service, this utility can be used to discover lookup services running on hosts that are located far from, or near to, the hosts on which the service is running. This lack of a restriction on location brings with it a requirement that the discovering entity supply specific information about the desired lookup services to the <code>LookupLocatorDiscovery</code> utility; namely, the location of the device(s) hosting each lookup service. This information is supplied through an instance of the <code>LookupLocator</code> utility, defined in the <a href="discovery-spec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>, or through an instance of <code>ConstrainableLookupLocator<
/code>, defined later in this document.
+</p>
+<p class="Body">
+ <a name="1022350"> </a>It may be of value to note the difference between <code>LookupLocatorDiscovery</code> and the <code>LookupDiscovery</code> helper utility for group discovery (defined earlier). Although both are non-remote utility classes that entities can use to discover at least one lookup service, the <code>LookupLocatorDiscovery</code> utility is designed to provide discovery capabilities that satisfy different needs than those satisfied by the <code>LookupDiscovery</code> utility. These two utilities differ in the following ways:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1022351"> </a>Whereas the <code>LookupLocatorDiscovery</code> utility is used to discover lookup services by their <em class="Emphasis">locators</em>, employing the unicast discovery protocol, the <code>LookupDiscovery</code> utility uses the multicast discovery protocols to discover lookup services by the <em class="Emphasis">groups</em> to which the lookup services belong.<p>
+ <li class="SmartList1"><a name="1022352"> </a>Whereas the <code>LookupLocatorDiscovery</code> utility requires that the discovering entity supply the specific location--or address--of the desired lookup service(s) in the form of a <code>LookupLocator</code> object, the <code>LookupDiscovery</code> utility imposes no such restriction on the discovering entity.<p>
+ <li class="SmartList1"><a name="1022353"> </a>Whereas the <code>LookupLocatorDiscovery</code> utility can be used by a discovering entity to discover lookup services that are both "near" and "far," the <code>LookupDiscovery</code> utility can be used to discover only those lookup services that are located within the same multicast radius as that of the discovering entity.
+</ul>
+
+<h4 class="Heading3">
+ <a name="1022354"> </a>DU.4.2 Other Types
+</h4>
+<p class="Body">
+ <a name="1022355"> </a>The types defined in the specification of the <code>LookupLocatorDiscovery</code> utility class are in the <code>net.jini.discovery</code> package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
+</p>
+<pre class="Preformatted">
+net.jini.core.discovery.LookupLocator
+net.jini.config.Configuration
+net.jini.config.ConfigurationException
+net.jini.discovery.DiscoveryManagement
+net.jini.discovery.DiscoveryLocatorManagement
+</code></pre>
+<h4 class="Heading3">
+ <a name="1022357"> </a>DU.4.3 The Interface
+</h4>
+<p class="Body">
+ <a name="1022358"> </a>The public methods provided by the <code>LookupLocatorDiscovery</code> class are as follows:
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public class LookupLocatorDiscovery
+ implements DiscoveryManagement
+ DiscoveryLocatorManagement
+{
+ public LookupLocatorDiscovery
+ (LookupLocator[] locators) {...}
+ public LookupLocatorDiscovery
+ (LookupLocator[] locators,
+ ConFiguration config)
+ throws ConfigurationException {...}
+ public LookupLocator[] getDiscoveredLocators() {...}
+ public LookupLocator[] getUndiscoveredLocators() {...}
+}
+</code></pre>
+<h4 class="Heading3">
+ <a name="1022360"> </a>DU.4.4 The Semantics
+</h4>
+<p class="Body">
+ <a name="1025242"> </a>Including the constructor, the <code>LookupLocatorDiscovery</code> helper utility class defines three new public methods. All other public methods are inherited from the <code>DiscoveryManagement</code> and <code>DiscoveryLocatorManagement</code> interfaces.
+</p>
+<p class="Body">
+ <a name="1022361"> </a>Each instance of the <code>LookupLocatorDiscovery</code> class must behave as if it operates independently of all other instances.
+</p>
+<p class="Body">
+ <a name="1022362"> </a>The <code>equals</code> method for this class returns <code>true</code> if and only if two instances of this class refer to the same object. That is, <code>x</code> and <code>y</code> are equal instances of this class if and only if <code>x</code> <code>==</code> <code>y</code> has the value <code>true</code>.
+</p>
+<p>
+The constructor for the <code>LookupLocatorDiscovery</code> class has two versions. The only difference between the two versions of the constructor is the absence or presence of a parameter of type <code>Configuration</code>, which is used to classify the constructors as either <em>non-configurable</em> or <em>configurable</em>, respectively.
+<p class="Body">
+ <a name="1022363"> </a>The single input parameter shared by both versions of the constructor is a set of locators represented as an array of <code>LookupLocator</code> objects, none of whose elements may be <code>null</code>. Each element in the input set corresponds to a specific lookup service the discovering entity wishes to be discovered. Although it is acceptable to input <code>null</code> for the argument itself, if a non-<code>null</code> array containing at least one <code>null</code> element is input, a <code>NullPointerException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="1022364"> </a>Invoking either version of the constructor with an input array that contains duplicate locators (as determined by <code>LookupLocator.equals</code>) is equivalent to performing the invocation with the duplicates removed from the array.
+</p>
+<p class="Body">
+ <a name="1025707"> </a>Although discovery events will not be sent by this class until a listener is added through an invocation of the <code>addListener</code> method, discovery processing usually starts as soon as an instance of this class is constructed. However, if <code>null</code> or an empty array is passed to the <code>locators</code> argument of either version of the constructor, discovery will not be started until the <code>addLocators</code> or <code>setLocators</code> method is called to change the managed set of locators to a set of locators that is non-<code>null</code> and non-empty.
+</p>
+<p>
+As previously noted, the configurable version of the constructor is characterized by an additional parameter of type <code>Configuration</code>. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting <code>LookupLocatorDiscovery</code> instance. Such customizations are implementation dependent. A <code>NullPointerException</code> is thrown if <code>null</code> is passed as the value of that parameter. A <code>ConfigurationException</code> is thrown to indicate that a problem occurred while attempting to retrieve an item from the given <code>Configuration</code>.
+<p>
+Creating a <code>LookupLocatorDiscovery</code> object using the non-configurable version of the constructor will result in an instance of <code>LookupLocatorDiscovery</code> having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.
+<p class="Body">
+ <a name="1022366"> </a>The <code>getDiscoveredLocators</code> method returns the set of <code>LookupLocator</code> objects representing the desired lookup services that are currently discovered. If the set is empty, this method will return an empty array. This method takes no arguments as input, and will return a new array upon each invocation.
+</p>
+<p class="Body">
+ <a name="1022367"> </a>The <code>getUndiscoveredLocators</code> method returns the set of <code>LookupLocator</code> objects representing the desired lookup services that have not yet been discovered. If the set is empty, this method will return an empty array. This method takes no arguments as input, and will return a new array upon each invocation.
+</p>
+<h4 class="Heading3">
+ <a name="1022368"> </a>DU.4.5 Supporting Interfaces
+</h4>
+<p class="Body">
+ <a name="1022369"> </a>The <code>LookupLocatorDiscovery</code> helper utility class depends on the following interfaces: <code>DiscoveryManagement</code> and <code>DiscoveryLocatorManagement</code>.
+</p>
+<h5 class="Heading4">
+ <a name="1029590"> </a>DU.4.5.1 The DiscoveryManagement Interfaces
+</h5>
+<p class="Body">
+ <a name="1029605"> </a>The <code>LookupLocatorDiscovery</code> class implements the <code>DiscoveryManagement</code> and <code>DiscoveryLocatorManagement</code> interfaces, which together define methods related to the coordination and management of all locator discovery processing. See <a href="discoveryutil-spec.html#1022214">Section DU.2, "The Discovery Management Interfaces"</a> for more information on those interfaces.
+</p>
+<h3 class="Heading2">
+ <a name="1022448"> </a>DU.5 The <code>LookupDiscoveryManager</code> Utility
+</h3>
+<h4 class="Heading3">
+ <a name="1022449"> </a>DU.5.1 Overview
+</h4>
+<p class="Body">
+ <a name="1022450"> </a>Although the goals of any well-behaved Jini client or service are application-specific, the goals of such entities with respect to their interaction with Jini lookup services generally begin with employing the Jini discovery protocols (defined in the <a href="discovery-spec.html"><em class="Emphasis">Jini Discovery and Join Specification</em></a>) to obtain a reference to at least one lookup service. Because the discovery duties performed by such entities may require the management of significant amounts of state information, those duties can become quite tedious.
+</p>
+<p class="Body">
+ <a name="1022451"> </a>The <code>LookupDiscoveryManager</code> is a helper utility class (belonging to the package <code>net.jini.discovery</code>) 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, <code>LookupLocator</code> objects, and <code>DiscoveryListener</code> objects, such an entity can employ this class to provide those facilities on its behalf.
+</p>
+<h4 class="Heading3">
+ <a name="1022453"> </a>DU.5.2 Other Types
+</h4>
+<p class="Body">
+ <a name="1022454"> </a>The types defined in the specification of the <code>LookupDiscoveryManager</code> utility class are in the <code>net.jini.discovery</code> package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
+</p>
+<pre class="Preformatted">
+net.jini.core.discovery.LookupLocator
+net.jini.config.Configuration
+net.jini.config.ConfigurationException
+net.jini.discovery.DiscoveryEvent
+net.jini.discovery.DiscoveryListener
+net.jini.discovery.DiscoveryManagement
+net.jini.discovery.DiscoveryGroupManagement
+net.jini.discovery.DiscoveryLocatorManagement
+java.io.IOException
+</code></pre>
+<h4 class="Heading3">
+ <a name="1022456"> </a>DU.5.3 The Interface
+</h4>
+<p class="Body">
+ <a name="1022457"> </a>The only new public method of the <code>LookupDiscoveryManager</code> helper utility class is the constructor. All other public methods implemented by this class are specified in the discovery management interfaces.
+</p>
+<pre class="Preformatted">
+package net.jini.discovery;
+
+public class LookupDiscoveryManager
+ implements DiscoveryManagement,
+ DiscoveryGroupManagement,
+ DiscoveryLocatorManagement
+{
+ public LookupDiscoveryManager(String[] groups,
+ LookupLocator[] locators,
+ DiscoveryListener listener)
+ throws IOException {...}
+ public LookupDiscoveryManager(String[] groups,
+ LookupLocator[] locators,
+ DiscoveryListener listener,
+ ConFiguration config)
+ throws IOException, ConfigurationException {...}
+}
+</pre>
+<h4 class="Heading3">
+ <a name="1022459"> </a>DU.5.4 The Semantics
+</h4>
+<p class="Body">
+ <a name="1022460"> </a>The <code>equals</code> method for this class returns <code>true</code> if and only if two instances of this class refer to the same object. That is, <code>x</code> and <code>y</code> are equal instances of this class if and only if <code>x</code> <code>==</code> <code>y</code> has the value <code>true</code>.
+</p>
+<p class="Body">
+ <a name="1022461"> </a>The constructor for the <code>LookupDiscoveryManager</code> has two versions. Each version of the constructor throws <code>IOException</code> because construction of a <code>LookupDiscoveryManager</code> may initiate the multicast discovery process, which can throw <code>IOException</code>.
+<p>
+The only difference between the two versions of the constructor is the absence or presence of a parameter of type <code>Configuration</code>, which is used to classify the constructors as either <em>non-configurable</em> or <em>configurable</em>, respectively.
+<p>
+The input parameters shared by both versions of the constructor are as follows:
+</p>
+<ul>
+
+ <li class="SmartList1"><a name="1022462"> </a>A <code>String</code> array, none of whose elements may be <code>null</code>, in which each element is the name of a group whose members are lookup services the entity wishes to be discovered through group discovery<p>
+ <li class="SmartList1"><a name="1022463"> </a>An array of <code>LookupLocator</code> objects, none of whose elements may be <code>null</code>, in which each element corresponds to a specific lookup service the entity wishes to be discovered through locator discovery<p>
+ <li class="SmartList1"><a name="1022464"> </a>A reference to an instance of <code>DiscoveryListener</code> that will be notified when a targeted lookup service is discovered, is discarded, or--under certain conditions--has experienced a change in its group membership
+</ul>
+
+<p class="Body">
+ <a name="1022465"> </a>The <code>LookupDiscoveryManager</code> will, on behalf of any entity that constructs an instance of this utility, employ the Jini discovery protocols defined in the <em class="Emphasis"><a href="discovery-spec.html">Jini Discovery and Join Specification</em></a> to attempt to find all lookup services that satisfy the criteria set forth by the contents of the first two arguments, and it will maintain and manage any lookup services that it does discover.
+</p>
+<p class="Body">
+ <a name="1025812"> </a>If either version of the constructor is invoked with a set of group names and a set of locators in which either or both sets contain duplicate elements (where duplicate locators are determined by <code>LookupLocator.equals</code>), the invocation is equivalent to constructing this class with no duplicates in either set.
+</p>
+<p class="Body">
+ <a name="1029159"> </a>If <code>null</code> (<code>DiscoveryGroupManagement</code>.<code>ALL_GROUPS</code>) is input to the <code>groups</code> argument, then attempts will be made through group discovery to discover all lookup services located within the multicast radius of the entity, regardless of group membership.
+</p>
+<p class="Body">
+ <a name="1029160"> </a>Typically, group discovery is initiated as soon as an instance of this class is created. However, if an empty array (<code>DiscoveryGroupManagement</code>.<code>NO_GROUPS</code>) is passed to the groups argument of the constructor, no lookup service will be discovered through group discovery until the <code>addGroups</code> or <code>setGroups</code> method is called to change the managed set of groups to either a non-empty set, or null (<code>DiscoveryGroupManagement</code>.<code>ALL_GROUPS</code>).
+</p>
+<p class="Body">
+ <a name="1025778"> </a>If at least one element of the <code>groups</code> argument is <code>null</code>, a <code>NullPointerException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="1022467"> </a>Typically, locator discovery processing is initiated as soon as an instance of this class is constructed. However, if an empty or <code>null</code> array is input to the <code>locators</code> argument, no attempt will be made to discover specific lookup services through locator discovery until the <code>addLocators</code> or <code>setLocators</code> method is called to change the managed set of locators to a set of locators that is non-<code>null</code> and non-empty.
+</p>
+<p class="Body">
+ <a name="1025787"> </a>If at least one element of the <code>locators</code> argument is <code>null</code>, a <code>NullPointerException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="1025900"> </a>The third argument to either version of the constructor is a reference to a listener object that will be registered to receive discovery event notifications. If a <code>null</code> reference is input to this argument, then the entity will receive no discovery events until <code>addDiscoveryListener</code> is invoked with a non-<code>null</code> instance of <code>DiscoveryListener</code>.
+</p>
+<p class="Body">
+ <a name="1025890"> </a>Once a listener is registered with the <code>LookupDiscoveryManager</code>, it will be notified of all lookup services discovered through either group or locator discovery, and will be notified whenever those lookup services are discarded. Thus, if an entity wishes to receive discovered and discarded events from the <code>LookupDiscoveryManager</code>, it is the responsibility of the entity to provide an implementation of the <code>DiscoveryListener</code> (or the <code>DiscoveryChangeListener</code>) interface; an implementation that defines the actions to take upon the receipt of those types of events.
+</p>
+<p class="Body">
+ <a name="1025891"> </a>If a listener registered with the <code>LookupDiscoveryManager</code> is also an instance of <code>DiscoveryChangeListener</code>, then in addition to receiving events related to discovered and discarded lookup services, that listener will also be notified of group membership changes that occur in any of the lookup services targeted for at least group discovery. That is, although such listeners are <em class="Emphasis">eligible</em> to receive changed events, they will receive no changed events for lookup services for which the entity has requested <em class="Emphasis">only</em> locator discovery.
+</p>
+<p class="Body">
+ <a name="1025877"> </a>Note that if an entity wishes to receive changed events in addition to the discovered and discarded events it receives from the <code>LookupDiscoveryManager</code>, the entity must provide an implementation of <code>DiscoveryChangeListener</code> that defines the actions to take upon the receipt of any of the three possible discovery event types. That is, if the entity provides only an implementation of <code>DiscoveryListener</code>, the entity will receive no changed events for any of the discovered lookup services, regardless of the discovery mechanism employed for those lookup services.
+</p>
+<p class="Body">
+ <a name="1026110"> </a>Once a lookup service is discovered, there is no longer any need to perform discovery processing with respect to that lookup service. This means that if a lookup service becomes unreachable after it has been discovered, the <code>LookupDiscoveryManager</code> will not know when the lookup service becomes reachable again until that lookup service is discarded.
+</p>
+<p class="Body">
+ <a name="1026146"> </a>Although the <code>LookupDiscoveryManager</code> will monitor the multicast announcements for indications of unavailability, it will discard only those unreachable lookup services for which the entity requested discovery through at least group discovery. That is, if the <code>LookupDiscoveryManager</code> determines that a previously discovered lookup service has become unreachable, but the entity requested that it be discovered by locator discovery alone, then the <code>LookupDiscoveryManager</code> will not discard the lookup service.
+</p>
+<p class="Body">
+ <a name="1026112"> </a>Thus, whenever the entity itself determines that a previously discovered lookup service has become unreachable, it should not rely on the <code>LookupDiscoveryManager</code> to discard the lookup service. Instead, the entity should inform the <code>LookupDiscoveryManager</code>--through the invocation of the <code>discard</code> method--that the previously discovered lookup service is no longer available, and that attempts should be made to re-discover that lookup service. Typically, an entity determines that a lookup service is unavailable when the entity attempts to use the lookup service but receives an exception or error (<code>RemoteException</code>, for example) as a result of the attempt.
+</p>
+<p>
+As previously noted, the configurable version of the constructor is characterized by an additional parameter of type <code>Configuration</code>. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting <code>LookupDiscoveryManager</code> instance. Such customizations are implementation dependent. A <code>NullPointerException</code> is thrown if <code>null</code> is passed as the value of that parameter. A <code>ConfigurationException</code> is thrown to indicate that a problem occurred while attempting to retrieve an item from the given <code>Configuration</code>.
+<p>
+Creating a <code>LookupDiscoveryManager</code> using the non-configurable version of the constructor will result in a <code>LookupDiscoveryManager</code> having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.
+<h4 class="Heading3">
+ <a name="1029676"> </a>DU.5.5 Supporting Interfaces and Classes
+</h4>
+<p class="Body">
+ <a name="1029827"> </a>The <code>LookupDiscoveryManager</code> helper utility class depends on the interfaces <code>DiscoveryManagement</code>, <code>DiscoveryGroupManagement</code>, and <code>DiscoveryLocatorManagement</code>, and on the concrete class <code>DiscoveryPermission</code>.
+</p>
+<h5 class="Heading4">
+ <a name="1025306"> </a>DU.5.5.1 The <code>DiscoveryManagement</code> Interfaces
+</h5>
+<p class="Body">
+ <a name="1029754"> </a>The <code>LookupDiscoveryManager</code> class implements the <code>DiscoveryManagement</code>, the <code>DiscoveryGroupManagement,</code> and the <code>DiscoveryLocatorManagement</code> interfaces, which together define methods related to the coordination and management of all group and locator discovery processing. See <a href="discoveryutil-spec.html#1022214">Section DU.2, "The Discovery Management Interfaces"</a> for more information on those interfaces.
+</p>
+<h5 class="Heading4">
+ <a name="1029787"> </a>DU.5.5.2 Security and Multicast Discovery: The <code>DiscoveryPermission</code> Class
+</h5>
+<p class="Body">
+ <a name="1029788"> </a>As is the case for the <code>LookupDiscovery</code> class, when an instance of the <code>LookupDiscoveryManager</code> class is constructed, the entity that creates the instance must be granted appropriate discovery permission to perform the group discovery duties that instance attempts to perform on behalf of the entity. If appropriate permissions are not granted, the constructor of <code>LookupDiscoveryManager</code>, as well as the methods <code>addGroups</code> and <code>setGroups</code>, will throw a <code>java.lang.SecurityException</code>.
+</p>
+<p class="Body">
+ <a name="1025356"> </a> Discovery permissions are controlled in security policy files using the permission class <code>DiscoveryPermission</code>. The specification of that class, as well as useful examples related to that class, are presented in the specification of the <code>LookupDiscovery</code> utility (see <a href="discoveryutil-spec.html#1022214">Section DU.2, "The Discovery Management Interfaces"</a>).
+</p>
+<h3 class="Heading2">
+ <a name="1000815"> </a>DU.6 The <code>ConstrainableLookupLocator</code> Utility
+</h3>
+<h4 class="Heading3">
+ <a name="1000816"> </a>DU.6.1 Overview
+</h4>
+<p class="Body">
+ <a name="1000817"> </a>The base <code>net.jini.core.discovery.LookupLocator</code> class, described in <a href="discovery-spec.html#45983">Section DJ.6, "<code>LookupLocator</code> Class"</a>, does not provide any means of controlling unicast discovery parameters other than the timeout for reading unicast response data. The <code>ConstrainableLookupLocator</code> utility is a subclass of <code>LookupLocator</code> that supports additional control of unicast discovery through the use of constraints.
+</p>
+<h4 class="Heading3">
+ <a name="1000821"> </a>DU.6.2 Other Types
+</h4>
+<p class="Body">
+ <a name="1000822"> </a>The types defined in the specification of the <code>ConstrainableLookupLocator</code> utility class are in the <code>net.jini.discovery</code> package. The following additional types are also referenced in this specification. Whenever referenced, these object types will be referred to in unqualified form:
+</p>
+<pre class="Preformatted">
+net.jini.core.constraint.MethodConstraints
+net.jini.core.constraint.RemoteMethodControl
+net.jini.io.UnsupportedConstraintException
+net.jini.security.Security
+net.jini.security.TrustVerifier
+java.io.IOException
+java.net.MalformedURLException
+</pre>
+<h4 class="Heading3">
+ <a name="1000825"> </a>DU.6.3 The Interface
+</h4>
+<p class="Body">
[... 741 lines stripped ...]