DU.5. The LookupDiscoveryManager Utility

DU.5.1. Overview

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 Jini Technology Core Platform Specification, “Discovery and Join”) 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.

The LookupDiscoveryManager is a helper utility class (belonging to the package net.jini.discovery) 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, LookupLocator objects, and DiscoveryListener objects, such an entity can employ this class to provide those facilities on its behalf.

DU.5.2. Other Types

The types defined in the specification of the LookupDiscoveryManager utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:

net.jini.core.discovery.LookupLocator 
net.jini.discovery.DiscoveryEvent 
net.jini.discovery.DiscoveryListener 
net.jini.discovery.DiscoveryManagement 
net.jini.discovery.DiscoveryGroupManagement 
net.jini.discovery.DiscoveryLocatorManagement 
java.io.IOException 

DU.5.3. The Interface

The only new public method of the LookupDiscoveryManager helper utility class is the constructor. All other public methods implemented by this class are specified in the discovery management interfaces.

package net.jini.discovery; 

public class LookupDiscoveryManager 
                        implements DiscoveryManagement, 
                                   DiscoveryGroupManagement, 
                                   DiscoveryLocatorManagement 
{
    public LookupDiscoveryManager(String[] groups, 
                                  LookupLocator[] locators, 
                                  DiscoveryListener listener) 
                                       throws IOException {...} 
} 

DU.5.4. The Semantics

The equals method for this class returns true if and only if two instances of this class refer to the same object. That is, x and y are equal instances of this class if and only if x==y has the value true.

The constructor for the LookupDiscoveryManager takes the following arguments as input:

• A String array, none of whose elements may be null, in which each element is the name of a group whose members are lookup services the entity wishes to be discovered through group discovery

• An array of LookupLocator objects, none of whose elements may be null, in which each element corresponds to a specific lookup service the entity wishes to be discovered through locator discovery

• A reference to an instance of DiscoveryListener that will be notified when a targeted lookup service is discovered, is discarded, or—under certain con-ditions—has experienced a change in its group membership

The LookupDiscoveryManager will, on behalf of any entity that constructs an instance of this utility, employ the Jini discovery protocols defined in The Jini Technology Core Platform Specification, “Discovery and Join” 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.

If 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 LookupLocator.equals), the invocation is equivalent to constructing this class with no duplicates in either set.

If null (DiscoveryGroupManagement. ALL_GROUPS) is input to the groups 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.

Typically, group discovery is initiated as soon as an instance of this class is created. However, if an empty array (DiscoveryGroupManagement.NO_GROUPS) is passed to the groups argument of the constructor, no lookup service will be discovered through group discovery until the addGroups or setGroups method is called to change the managed set of groups to either a non-empty set, or null (DiscoveryGroupManagement. ALL_GROUPS).

If at least one element of the groups argument is null, a NullPointerException is thrown.

Typically, locator discovery processing is initiated as soon as an instance of this class is constructed. However, if an empty or null array is input to the locators argument, no attempt will be made to discover specific lookup services through locator discovery until the addLocators or setLocators method is called to change the managed set of locators to a set of locators that is nonnull and non-empty.

If at least one element of the locators argument is null, a NullPointerException is thrown.

The last argument to the constructor is a reference to a listener object that will be registered to receive discovery event notifications. If a null reference is input to this argument, then the entity will receive no discovery events until addDiscoveryListener is invoked with a nonnull instance of DiscoveryListener.

Once a listener is registered with the LookupDiscoveryManager, 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 LookupDiscoveryManager, it is the responsibility of the entity to provide an implementation of the DiscoveryListener (or the DiscoveryChangeListener) interface; an implementation that defines the actions to take upon the receipt of those types of events.

If a listener registered with the LookupDiscoveryManager is also an instance of DiscoveryChangeListener, then in addition to receiving events related to dis covered 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 eligible to receive changed events, they will receive no changed events for lookup services for which the entity has requested only locator discovery.

Note that if an entity wishes to receive changed events in addition to the discovered and discarded events it receives from the LookupDiscoveryManager, the entity must provide an implementation of DiscoveryChangeListener 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 DiscoveryListener, the entity will receive no changed events for any of the discovered lookup services, regardless of the discovery mechanism employed for those lookup services.

The constructor throws IOException. This is because construction of a LookupDiscoveryManager may initiate the multicast discovery process, which can throw IOException.

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 LookupDiscoveryManager will not know when the lookup service becomes reachable again until that lookup service is discarded.

Although the LookupDiscoveryManager 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 LookupDiscoveryManager determines that a previously discovered lookup service has become unreachable, but the entity requested that it be discovered by locator discovery alone, then the LookupDiscoveryManager will not discard the lookup service.

Thus, whenever the entity itself determines that a previously discovered lookup service has become unreachable, it should not rely on the LookupDiscoveryManager to discard the lookup service. Instead, the entity should inform the LookupDiscoveryManager—through the invocation of the discard 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 (RemoteException, for example) as a result of the attempt.

DU.5.5. Supporting Interfaces and Classes

The LookupDiscoveryManager helper utility class depends on the interfaces DiscoveryManagement, DiscoveryGroupManagement, and DiscoveryLocatorManagement, and on the concrete class DiscoveryPermission.

DU.5.5.1. The DiscoveryManagement Interfaces

The LookupDiscoveryManager class implements the DiscoveryManagement, the DiscoveryGroupManagement, and the DiscoveryLocatorManagement interfaces, which together define methods related to the coordination and management of all group and locator discovery processing. See Section DU.2, “The Discovery Management Interfaces” for more information on those interfaces.

DU.5.5.2. Security and Multicast Discovery: The DiscoveryPermission Class

As is the case for the LookupDiscovery class, when an instance of the LookupDiscoveryManager 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 LookupDiscoveryManager, as well as the methods addGroups and setGroups, will throw a java.lang.SecurityException.

Discovery permissions are controlled in security policy files using the permission class DiscoveryPermission. The specification of that class, as well as useful examples related to that class, are presented in the specification of the LookupDiscovery utility (see Section DU.2, “The Discovery Management Interfaces”).