DU.2. The Discovery Management Interfaces

DU.2.1. Overview

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.

The interfaces collectively referred to as the discovery management 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 Jini application environment). 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 net.jini.discovery:

• DiscoveryManagement

• DiscoveryGroupManagement

• DiscoveryLocatorManagement

The DiscoveryManagement 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.

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

The DiscoveryLocatorManagement interface defines methods related to the management of the set of lookup services that are to be discovered using the uni cast discovery protocol (as defined in the Jini Discovery and Join Specification). The methods of this interface define how an entity accesses or modifies the contents of the set of LookupLocator objects corresponding to the specific lookup services the entity has targeted for locator discovery.

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.

For example, a class may wish to implement the functionality defined in DiscoveryManagement, 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 DiscoveryManagement.

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 DiscoveryGroupManagement and DiscoveryLocatorManagement, but not DiscoveryManagement.

A specific example of a class that implements only a subset of the set of interfaces specified here is the LookupDiscovery utility class defined later in this specification. That class implements both the DiscoveryManagement and DiscoveryGroupManagement interfaces, but not the DiscoveryLocatorManagement interface.

Throughout this discussion of the discovery management interfaces, the phrase implementation class refers to any concrete class that implements one or more of those interfaces. The phrase implementation object should be understood to mean an instance of such an implementation class. Additionally, whenever a description refers to the discovering entity (or simply, the entity), 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.

DU.2.2. Other Types

The types defined in the specification of the discovery management interfaces 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.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 

DU.2.3. The DiscoveryManagement Interface

The public methods specified by the DiscoveryManagement interface are:

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(); 
} 

DU.2.3.1. The Semantics

The DiscoveryManagement interface defines methods related to the discovery event mechanism and discovery process termination. Through this interface, an entity can register or un-register DiscoveryListener objects to receive discovery events (instances of DiscoveryEvent), 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.

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 terminate method additionally should cancel all leases held by the implementation object and terminate all lease management being performed on behalf of the entity.

For information on any additional semantics imposed on a method of this interface, refer to the specification of the particular implementation class.

The DiscoveryEvent, DiscoveryListener, and DiscoveryChangeListener classes are defined later in this specification.

The addDiscoveryListener method adds a listener to the set of objects listening for discovery events. This method takes a single argument as input: an instance of DiscoveryListener corresponding to the listener to add to the set.

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.

If the added listener is also an instance of DiscoveryChangeListener (a subclass of DiscoveryListener), 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.

If null is input to this method, a NullPointerException is thrown. If the listener input to this method duplicates (using the equals method) another element in the set of listeners, no action is taken.

Implementations of the DiscoveryManagement interface must guarantee reentrancy with respect to DiscoveryListener objects registered through this method. Should the instance of DiscoveryManagement invoke a method on a registered listener (a local call), calls from that method to any method of the DiscoveryManagement instance are guaranteed not to result in a deadlock condition.

The removeDiscoveryListener method removes a listener from the set of objects listening for discovery events. This method takes a single argument as input: an instance of DiscoveryListener corresponding to the listener to remove from the set.

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.

The getRegistrars method returns an array consisting of instances of the ServiceRegistrar 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.

The discard 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 ServiceRegistrar interface corresponding to the proxy to the lookup service to discard.

If the proxy input to this method is null, or if it matches (using the equals method) none of the lookup services in the managed set, this method takes no action.

Currently, there exist utilities such as the LookupDiscovery and LookupDiscoveryManager 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 discard 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 result 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.

Invoking the discard method defined by the DiscoveryManagement interface will result in the flushing of the lookup service from the appropriate cache, ultimately causing a discard notification—referred to as a discarded event—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.

The terminate method ends all discovery processing being performed on behalf of the entity. This method takes no input arguments.

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.

Any additional termination semantics must be defined by the implementation class.

DU.2.4. The DiscoveryGroupManagement Interface

The public methods specified by the DiscoveryGroupManagement interface are as follows:

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); 
} 

DU.2.4.1. The Semantics

The DiscoveryGroupManagement 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.

The methods that modify the managed set of groups each take a single input parameter: a String array, none of whose elements may be null. Each of these methods throws a NullPointerException when at least one element of the input array is null.

The empty set is denoted by an empty array, and “no set” is indicated by null. 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.

The ALL_GROUPS and the NO_GROUPS constants are defined for convenience, and represent no set and the empty set respectively.

The getGroups 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.

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 (ALL_GROUPS) is returned, indicating that any lookup service within range—even those that have no group affiliation—are to be discovered.

If an empty array is returned, that array is guaranteed to be referentially equal to the NO_GROUPS constant; that is, the array returned from that method and the NO_GROUPS constant can be tested for equality using the == operator.

This method takes no arguments as input and, provided the managed set of groups currently exists, will return a new array upon each invocation.

The addGroups 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.

This method throws IOException because an invocation of this method may result in the re-initiation of the discovery process, which can throw IOException when socket allocation occurs.

This method throws an UnsupportedOperationException if there is no managed set of groups to augment, and it throws a NullPointerException if null (ALL_GROUPS) is input. If an empty array (NO_GROUPS) is input, the managed set of groups will not change.

The setGroups 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.

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.

If null (ALL_GROUPS) is input to setGroups, then attempts will be made to discover all (as yet) undiscovered lookup services located within the multicast radius (Section DU.3, “LookupDiscovery Utility”) of the implementation object, regardless of group membership.

If an empty array (NO_GROUPS) is input to setGroups, then group discovery will be halted until the managed set of groups is changed—through a subsequent call to this method or to addGroups—to a set that is either a non-empty set of group names or null (ALL_GROUPS).

This method throws IOException. This is because an invocation of this method may result in the re-initiation of the discovery process, a process that can throw IOException when socket allocation occurs.

The removeGroups 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.

This method throws an UnsupportedOperationException if there is no managed set of groups from which to remove elements. If null (ALL_GROUPS)is input to removeGroups, a NullPointerException will be thrown.

If any element of the set of groups to be removed is not contained in the managed set, removeGroups takes no action with respect to that element. If an empty array (NO_GROUPS) is input, the managed set of groups will not change.

Once a new group name is added to the managed set as a result of an invocation of either addGroups or setGroups, 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.

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 setGroups or removeGroups will be discarded and will no longer be eligible for discovery, but only if that lookup service satisfies both of the following conditions:

• the lookup service is not a member of any group in the new managed set that resulted from the invocation of setGroups or removeGroups, and

• the lookup service is not currently eligible for discovery through other means (such as locator discovery).

DU.2.5. The DiscoveryLocatorManagement Interface

The public methods specified by the DiscoveryLocatorManagement interface are as follows:

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); 
} 

DU.2.5.1. The Semantics

The DiscoveryLocatorManagement interface defines methods related to the management of the set of LookupLocator 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.

The methods that modify the managed set of locators each take a single input parameter: an array of LookupLocator objects, none of whose elements may be null. Each of these methods throws a NullPointerException when at least one element of the input array is null.

Invoking any of these methods 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.

The getLocators method returns an array containing the set of LookupLocator 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.

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.

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.

The addLocators method adds a set of locators to the managed set. The array input to this method contains the set of LookupLocator objects to add to the managed set.

If null is input to addLocators, a NullPointerException will be thrown. If an empty array is input, the managed set of locators will not change.

The setLocators method replaces all of the locators in the managed set with LookupLocator objects from a new set. The array input to this method contains the set of LookupLocator objects with which to replace the current locators in the managed set.

If null is input to setLocators, a NullPointerException will be thrown.

If an empty array is input to setLocators, then locator discovery will be halted until the managed set of locators is changed—through a subsequent call to this method or to addLocators—to a set that is nonnull and non-empty.

The removeLocators method deletes a set of locators from the managed set. The array input to this method contains the set of LookupLocator objects to remove from the managed set.

If null is input to removeLocators, a NullPointerException will be thrown.

If any element of the set of locators to remove is not contained in the managed set, removeLocators takes no action with respect to that element. If an empty array is input, the managed set of locators will not change.

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 setLocators or removeLocators, 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).

DU.2.6. Supporting Interfaces and Classes

Discovery management depends on the interfaces DiscoveryListener and DiscoveryChangeListener, and on the concrete class DiscoveryEvent.

DU.2.6.1. The DiscoveryListener Interface

The public methods specified by the DiscoveryListener interface are as follows:

package net.jini.discovery; 

public interface DiscoveryListener extends EventListener {
    public void discovered(DiscoveryEvent e); 
    public void discarded(DiscoveryEvent e); 
} 

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 discovery utility— to notify the entity when a desired lookup service is either discovered or discarded. The DiscoveryListener 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 DiscoveryEvent class, which encapsulate the required information associated with the desired notifications.

The Semantics

The events received by listeners implementing the DiscoveryListener 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 DiscoveryEvent class).

The discovered method is called whenever a new lookup service is discovered or a discarded lookup service is re-discovered.

The discarded 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 active discard) or the discovery utility employed by the entity (a passive discard).

This interface makes the following concurrency guarantee. For any given listener object that implements this interface or any sub-interface, no two methods (either the same two methods or different methods) defined by the interface (or sub-interface) can be invoked at the same time. For example, the discovered method must not be invoked while the invocation of another listener’s discarded method is in progress.

DU.2.6.2. The DiscoveryChangeListener Interface

The DiscoveryChangeListener interface specifies only one public method:

package net.jini.discovery; 

public interface DiscoveryChangeListener 
                 extends DiscoveryListener 
{
    public void changed(DiscoveryEvent e); 
} 

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 DiscoveryChangeListener interface defines an extension to the DiscoveryListener interface, providing a mechanism through which an entity may receive these additional notifications— referred to as changed events. As with the DiscoveryListener 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 DiscoveryEvent class.

The Semantics

When the entity receives a DiscoveryEvent object through an instance of the DiscoveryChangeListener 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.

The changed method is called whenever the discovery utility encounters changes in the set of groups in which a previously discovered lookup service is a member.

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 only 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 discovering the lookup service through its group membership, it must also have no interest in any changes 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.

DU.2.6.3. The DiscoveryEvent Class

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

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() {...} 
} 

The DiscoveryEvent 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 ServiceRegistrar 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:

• Each lookup service referenced in the event has been discovered for the first time, or re-discovered after having been discarded.

• Each lookup service referenced in the event has been either actively or passively discarded.

• For each lookup service referenced in the event, the set of groups in which the lookup service is a member has changed.

The DiscoveryEvent class is a subclass of EventObject, adding the following additional items of abstract state: a set of ServiceRegistrar instances (registrars) 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.

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 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 discovered, discarded, or changed 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.

Depending on the constructor employed, the second parameter is one of the following:

• A Map instance in which each element of the map’s key set is a ServiceRegistrar 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 String array, containing the names of the groups in which the corresponding lookup service is a member.

• An array of ServiceRegistrar instances in which each element references one of the lookup services to be associated with the event being constructed.

  It is important to note that when this form of the constructor is used to construct a DiscoveryEvent, although the resulting event contains a non-null registrars array, the registrars-to-groups map is null. Therefore, discovery utilities should no longer use this constructor to instantiate the events they send.

The getGroups 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 ServiceRegistrar instances, this method will return null.

The returned map’s key set is made up of ServiceRegistrar 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 String array, containing the names of the member groups of the corresponding lookup service.

On each invocation of this method, the same Map object is returned; that is, a copy is not made.

The getRegistrars method returns an array of ServiceRegistrar instances, in which each element references one of the lookup services for which the event was constructed and sent.

On each invocation of this method, the same array is returned; that is, a copy is not made.

DU.2.7. Serialized Forms