DU.4. The LookupLocatorDiscovery Utility

DU.4.1. Overview

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

The LookupLocatorDiscovery helper utility (belonging to the package net.jini.discovery) 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.

Because the LookupLocatorDiscovery 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 LookupLocatorDiscovery utility; namely, the location of the device(s) hosting each lookup service. This information is supplied through an instance of the LookupLocator utility, defined in The Jini Technology Core Platform Specification, “Discovery and Join”.

It may be of value to note the difference between LookupLocatorDiscovery and the LookupDiscovery 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 LookupLocatorDiscovery utility is designed to provide discovery capabilities that satisfy different needs than those satisfied by the LookupDiscovery utility. These two utilities differ in the following ways:

• Whereas the LookupLocatorDiscovery utility is used to discover lookup services by their locators, employing the unicast discovery protocol, the LookupDiscovery utility uses the multicast discovery protocols to discover lookup services by the groups to which the lookup services belong.

• Whereas the LookupLocatorDiscovery utility requires that the discovering entity supply the specific location—or address—of the desired lookup service(s) in the form of a LookupLocator object, the LookupDiscovery utility imposes no such restriction on the discovering entity.

• Whereas the LookupLocatorDiscovery utility can be used by a discovering entity to discover lookup services that are both “near” and “far,” the LookupDiscovery utility can be used to discover only those lookup services that are located within the same multicast radius as that of the discovering entity.

DU.4.2. Other Types

The types defined in the specification of the LookupLocatorDiscovery 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.DiscoveryManagement 
net.jini.discovery.DiscoveryLocatorManagement 

DU.4.3. The Interface

The public methods provided by the LookupLocatorDiscovery class are as follows:

package net.jini.discovery; 

public class LookupLocatorDiscovery 
                     implements DiscoveryManagement 
                                DiscoveryLocatorManagement 
{
    public LookupLocatorDiscovery 
                            (LookupLocator[] locators) {...} 
    public LookupLocator[] getDiscoveredLocators() {...} 
    public LookupLocator[] getUndiscoveredLocators() {...} 
} 

DU.4.4. The Semantics

Including the constructor, the LookupLocatorDiscovery helper utility class defines three new public methods. All other public methods are inherited from the DiscoveryManagement and DiscoveryLocatorManagement interfaces.

Each instance of the LookupLocatorDiscovery class must behave as if it operates independently of all other instances.

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 of the LookupLocatorDiscovery class takes a single input parameter: a set of locators represented as an array of LookupLocator objects, none of whose elements may be null. 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 null, if a nonnull array containing at least one null element is input, a NullPointerException will be thrown.

Invoking the constructor with an input array that contains duplicate locators (as determined by LookupLocator.equals) is equivalent to performing the invocation with the duplicates removed from the array.

Although discovery events will not be sent by this class until a listener is added through an invocation of the addListener method, discovery processing usually starts as soon as an instance of this class is constructed. However, if null or an empty array is passed to the constructor, discovery will not be started 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.

The getDiscoveredLocators method returns the set of LookupLocator 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.

The getUndiscoveredLocators method returns the set of LookupLocator 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.

DU.4.5. Supporting Interfaces

The LookupLocatorDiscovery helper utility class depends on the following interfaces: DiscoveryManagement and DiscoveryLocatorManagement.

DU.4.5.1. The DiscoveryManagement Interfaces

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