DU - Jini^TM Discovery Utilities Specification

DU.1 Introduction

Each discovering entity in a Java^TM virtual machine (JVM)¹ on a given host is independently responsible for obtaining references to lookup services. In this specification we first cover a set of discovery management interfaces 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.

DU.1.1 Dependencies

This specification relies on the following other specifications:

• Java^TM Object Serialization Specification

• Jini^TM Discovery and Join Specification

• Jini^TM Lookup Service Specification

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 Discovery and Join Specification). 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 unicast 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 non-null 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).

The DiscoveryGroupManagement 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 DiscoveryManagement instance. For example, the discovered method of one listener will not be invoked while the invocation of another listener's discovered or discarded method is in progress. Similarly, the one listener's discovered method will not be invoked while that same listener's discard 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

Class	serialVersionUID	Serialized Fields
DiscoveryEvent	5280303374696501479L	ServiceRegistrar[] regs Map groups

DU.3 LookupDiscovery Utility

DU.3.1 Overview

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 discovering entity (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 Jini Discovery and Join Specification.

The LookupDiscovery helper utility in the package net.jini.discovery encapsulates the functionality required of an entity that wishes to employ multicast discovery to discover a lookup service located within the entity's multicast radius (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.

DU.3.2 Other Types

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

DU.3.3 The Interface

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

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

}

DU.3.4 The Semantics

The only new public method of the LookupDiscovery helper utility class is the constructor. All other public methods implemented by this class are specified in the DiscoveryManagement and the DiscoveryGroupManagement interfaces.

Each instance of the LookupDiscovery 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.

For convenience, this class defines the constants ALL_GROUPS and NO_GROUPS, which represent no set and the empty set respectively. For more information on these constants, refer to the specification of the DiscoveryGroupManagement interface.

The constructor for the LookupDiscovery class has two versions. Each version of the constructor throws IOException because construction of a LookupDiscovery object can cause the initiation of the multicast discovery process, a process that can throw IOException.

The only difference between the two versions of the constructor is the absence or presence of a parameter of type Configuration, which is used to classify the constructors as either non-configurable or configurable, respectively.

The single input parameter shared by both versions of the constructor is a String array, none of whose elements may be null. If at least one element of that input array is null, a NullPointerException is thrown.

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.

If null (ALL_GROUPS) 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.

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 an empty array (NO_GROUPS) is passed to the constructor, discovery will not be started until the addGroups or setGroups method is called to change the initial empty set of groups to either a non-empty set, or null (ALL_GROUPS).

As noted, the configurable version of the constructor is characterized by an additional parameter of type Configuration. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting LookupDiscovery instance. Such customizations are implementation dependent. A NullPointerException is thrown if null is passed as the value of that parameter. A ConfigurationException is thrown to indicate that a problem occurred while attempting to retrieve an item from the given Configuration.

Creating a LookupDiscovery object using the non-configurable version of the constructor will result in an instance of LookupDiscovery having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.

DU.3.5 Supporting Interfaces and Classes

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

DU.3.5.1 The DiscoveryManagement Interfaces

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

DU.3.5.2 Security and Multicast Discovery: The DiscoveryPermission Class

When an instance of the LookupDiscovery class is constructed, the entity that creates the instance must be granted appropriate discovery permission. For example, if the instance of LookupDiscovery is currently configured to discover a non-empty, non-null 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 null (ALL_GROUPS), then the entity must have permission to attempt discovery of all possible groups. If appropriate permissions are not granted, the constructor of LookupDiscovery, 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 public methods provided by the DiscoveryPermission class are as follows:

package net.jini.discovery;

public final class DiscoveryPermission extends Permission
                                       implements Serializable
{
    public DiscoveryPermission(String group) {...}
    public DiscoveryPermission(String group, 
                               String actions) {...}
}

The DiscoveryPermission class is a subclass of Permission, adding no additional items of abstract state.

The Semantics

The equals method for this class returns true if and only if two instances of this class have the same group name.

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 String representing one or more group names for which to allow discovery.

The second parameter of the second form of the constructor is a String value that is currently ignored because there are no actions associated with a discovery permission.

DiscoveryPermission Examples

A number of examples that illustrate the use of this permission are presented. Note that each example represents a line in a policy file.

permission net.jini.discovery.DiscoveryPermission "*";
Grant the entity permission to attempt discovery of all possible groups

permission net.jini.discovery.DiscoveryPermission "";
Grant the entity permission to attempt discovery of only the "public" group

permission net.jini.discovery.DiscoveryPermission "foo";
Grant the entity permission to attempt discovery of the group named "foo"

permission net.jini.discovery.DiscoveryPermission "*.sun.com";
Grant the entity permission to attempt discovery of all groups whose names end with the substring ".sun.com"

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:

• The name "*" grants permission to attempt discovery of all possible groups.

• A name beginning with "*." grants permission to attempt discovery of all groups that match the remainder of that name; for example, the name "*.example.org" would match a group named "foonly.example.org" and also a group named "sf.ca.example.org".

• The empty name "" denotes the public group.

• All other names are treated as individual groups and must match exactly.

Finally, it is important to note that a restriction of the Java2 platform security model requires that appropriate DiscoveryPermission be granted to the Jini technology infrastructure software codebase itself, in addition to any codebases that may use Jini technology infrastructure software classes.

DU.3.6 Serialized Forms

Class	serialVersionUID	Serialized Fields
DiscoveryPermission	-3036978025008149170L	none

DU.4 The LookupLocatorDiscovery Utility

DU.4.1 Overview

The Jini Discovery and Join Specification, 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 Discovery and Join Specification, or through an instance of ConstrainableLookupLocator, defined later in this document.

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.config.Configuration
net.jini.config.ConfigurationException
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 LookupLocatorDiscovery
                            (LookupLocator[] locators,
                             ConFiguration config)
                         throws ConfigurationException {...}
    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 for the LookupLocatorDiscovery class has two versions. The only difference between the two versions of the constructor is the absence or presence of a parameter of type Configuration, which is used to classify the constructors as either non-configurable or configurable, respectively.

The single input parameter shared by both versions of the constructor is 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 for the argument itself, if a non-null array containing at least one null element is input, a NullPointerException is thrown.

Invoking either version of 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 locators argument of either version of 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 non-null and non-empty.

As previously noted, the configurable version of the constructor is characterized by an additional parameter of type Configuration. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting LookupLocatorDiscovery instance. Such customizations are implementation dependent. A NullPointerException is thrown if null is passed as the value of that parameter. A ConfigurationException is thrown to indicate that a problem occurred while attempting to retrieve an item from the given Configuration.

Creating a LookupLocatorDiscovery object using the non-configurable version of the constructor will result in an instance of LookupLocatorDiscovery having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.

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.

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 Discovery and Join Specification) 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.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

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 {...}
    public LookupDiscoveryManager(String[] groups,
                                  LookupLocator[] locators,
                                  DiscoveryListener listener,
                                  ConFiguration config)
               throws IOException, ConfigurationException {...}
}

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 has two versions. Each version of the constructor throws IOException because construction of a LookupDiscoveryManager may initiate the multicast discovery process, which can throw IOException.

The only difference between the two versions of the constructor is the absence or presence of a parameter of type Configuration, which is used to classify the constructors as either non-configurable or configurable, respectively.

The input parameters shared by both versions of the constructor are as follows:

• 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 conditions--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 Discovery and Join Specification 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 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 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 non-null and non-empty.

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

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 null reference is input to this argument, then the entity will receive no discovery events until addDiscoveryListener is invoked with a non-null 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 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 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.

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.

As previously noted, the configurable version of the constructor is characterized by an additional parameter of type Configuration. Through that parameter, the configurable version of the constructor can be used to customize the behavior of the resulting LookupDiscoveryManager instance. Such customizations are implementation dependent. A NullPointerException is thrown if null is passed as the value of that parameter. A ConfigurationException is thrown to indicate that a problem occurred while attempting to retrieve an item from the given Configuration.

Creating a LookupDiscoveryManager using the non-configurable version of the constructor will result in a LookupDiscoveryManager having only basic, default behavior. Thus, the use of the configurable version of the constructor is strongly encouraged.

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").

DU.6 The ConstrainableLookupLocator Utility

DU.6.1 Overview

The base net.jini.core.discovery.LookupLocator class, described in Section DJ.6, "LookupLocator Class", does not provide any means of controlling unicast discovery parameters other than the timeout for reading unicast response data. The ConstrainableLookupLocator utility is a subclass of LookupLocator that supports additional control of unicast discovery through the use of constraints.

DU.6.2 Other Types

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

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

DU.6.3 The Interface

In order to support constraints, ConstrainableLookupLocator defines constructors that take the same parameters as those of LookupLocator, with the addition of MethodConstraints. All other public members are defined by supertypes: the public getRegistrar, getRegistrar(int), getHost, and getPort methods, along with the protected host and port fields, are defined by the LookupLocator class, while the public getConstraints and setConstraints methods are defined by the RemoteMethodControl interface.

 public final class ConstrainableLookupLocator
    extends LookupLocator implements RemoteMethodControl
{
    public ConstrainableLookupLocator
                         (String url,
                          MethodConstraints constraints)
                   throws MalformedURLException {...}
    public ConstrainableLookupLocator
                         (String host,
                          int port,
                          MethodConstraints constraints) {...}
}

DU.6.4 The Semantics

The first constructor listed in Section DU.6.3 accepts the following parameters as input:

• A non-null String containing a URL, which must be a URL of scheme "jini" as described in the Jini Discovery and Join Specification
• A MethodConstraints instance containing the constraints to be applied to unicast discovery, or null, indicating an empty set of constraints

A ConstrainableLookupLocator instance created with this constructor will attempt unicast discovery to the indicated TCP host and port when one of its getRegistrar methods is called. This constructor invokes the one argument superclass constructor, passing it to the input URL parameter. Any exception thrown by the superclass constructor is rethrown.

The second constructor listed in Section DU.6.3 accepts the following parameters as input:

• A non-null String containing the name of the host to which to attempt unicast discovery
• An int value indicating the number of the port to connect to when attempting unicast discovery
• A MethodConstraints instance containing the constraints to be applied to unicast discovery, or null, indicating an empty set of constraints

The only difference between this and the previously described constructor is the means by which the target host and port for unicast discovery is specified--rather than a URL string, this constructor accepts explicit host and port values. A ConstrainableLookupLocator instance created with this constructor will attempt unicast discovery to the specified TCP host and port when one of its getRegistrar methods is called. This constructor invokes the two argument superclass constructor, passing to it the input host and port parameters. Any exception thrown by the superclass constructor is rethrown.

The getHost, getPort, equals, and hashCode methods of this class behave in the same way as those of the base LookupLocator class.

The setConstraints and getConstraints methods of this class behave as specified by the RemoteMethodControl interface. Note that the only methods for which constraints are obtained from supplied MethodConstraints instances are the getRegistrar and getRegistrar(int) methods of the LookupLocator class.

The getRegistrar(int) method of this class behaves as specified by the LookupLocator class, except that it also takes into account the constraints (if any) attached for it to the ConstrainableLookupLocator instance on which the method is invoked. Consequently, this method throws UnsupportedConstraintException (which is a subclass of IOException) if the specified constraints cannot be satisfied. The specified timeout value is interpreted as an additional required constraint; if this value conflicts with other constraints specified for the getRegistrar(int) method, then an UnsupportedConstraintException will be thrown.

The getRegistrar() method, like the getRegistrar(int) method, takes into account the constraints (if any) for it. Additionally, as with the getRegistrar(int) method, it throws UnsupportedConstraintException if the specified constraints cannot be satisfied. If no timeout constraints are specified, this method assumes a default timeout of 60 seconds. It performs unicast discovery as specified by the LookupLocator class, however it does not invoke the getRegistrar(int) method. Moreover, a non-default timeout can only be specified through the supplied constraints; the net.jini.discovery.timeout system property is ignored. ConstrainableLookupLocator implements this method to use the values of the host and port fields in determining the host and port to which to connect.

DU.6.5 Supporting Interfaces and Classes

The ConstrainableLookupLocator class depends on the LookupLocator class, which it subclasses, and the RemoteMethodControl interface, which it implements. It is also associated with the ConstrainableLookupLocatorTrustVerifier class, described in the following sub-section.

DU.6.5.1 The ConstrainableLookupLocatorTrustVerifier Class

The ConstrainableLookupLocatorTrustVerifier class is used for verifying trust in ConstrainableLookupLocator instances acquired from untrusted sources; it is intended to be specified in a resource to configure the operation of the Security.verifyObjectTrust method. ConstrainableLookupLocatorTrustVerifier implements the TrustVerifier interface and defines a single no-argument constructor:

 public class ConstrainableLookupLocatorTrustVerifier
    implements TrustVerifier
{
    public ConstrainableLookupLocatorTrustVerifier() {...}
}

The constructor creates a new ConstrainableLookupLocatorTrustVerifier instance. Note that all ConstrainableLookupLocatorTrustVerifier instances are functionally equivalent, since they do not contain any state.

The isTrustedObject method of the ConstrainableLookupLocatorTrustVerifier class follows the method's general contract, specified by the TrustVerifier interface: it returns true if its Object argument is known to be trusted to correctly implement its contract, and returns false otherwise. More specifically, it returns true if the given argument is an instance of ConstrainableLookupLocator (which rules out untrusted classes, since ConstrainableLookupLocator is a final class), and returns false otherwise.

DU.6.6 Serialized Form

Class	serialVersionUID	Serialized Fields
ConstrainableLookupLocator	7061417093114347317L	none

DU.7 Low-Level Discovery Protocol Utilities

The utilities presented in this section of the specification are useful when implementing higher-level utilities or other entities or components that will be involved in the Jini discovery process. These utilities encapsulate functionality that allow one to exercise more control when interacting with the Jini discovery protocols. Anyone wishing to provide their own implementation of the Jini lookup service or their own implementation of the discovery utilities presented previously in this specification, may find the utilities presented in this section useful when creating those alternate implementations.

Note that these utilities only support version 1 of the discovery protocol, as defined in the Jini Discovery and Join Specification.

DU.7.1 The Constants Class

DU.7.1.1 Overview

The Constants class provides easy access to defined constants that may be useful when participating in the discovery process.

DU.7.1.2 Other Types

The types defined in the specification of the Constants 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:

java.net.InetAddress
java.net.UnknownHostException

DU.7.1.3 The Class Definition

The public constants defined by the Constants class are as follows:

package net.jini.discovery;

public class Constants {
    public static final short discoveryPort = 4160;
    public static final InetAddress getRequestAddress()
        throws UnknownHostException {...}
    public static final InetAddress getAnnouncementAddress()
        throws UnknownHostException {...}
}

DU.7.1.4 The Semantics

The Constants class cannot be instantiated. This class has one public variable and two public accessor methods; each is static and final. The constant value associated with the variable, as well as the values returned by the methods, may be useful in the discovery process.

The value of the discoveryPort constant serves two purposes:

• The UDP port number over which the multicast request and announcement protocols operate

• The TCP port number over which the unicast discovery protocol operates by default

The getRequestAddress method returns an instance of InetAddress that contains the address of the multicast group over which the multicast request protocol takes place.

The getAnnouncementAddress method returns an instance of InetAddress that contains the address of the multicast group over which the multicast announcement protocol takes place.

Note that either getRequestAddress or getAnnouncementAddress may throw an UnknownHostException if called in a circumstance under which multicast address resolution is not permitted.

DU.7.2 The OutgoingMulticastRequest Utility

DU.7.2.1 Overview

The OutgoingMulticastRequest class provides facilities for marshalling multicast discovery requests into a form suitable for transmission over a network for the purposes of announcing one's interest in discovering a lookup service. This class is useful when building components that participate in the multicast request protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit multicast requests in order to discover a lookup service belonging to a set of groups in which the entity is interested.

DU.7.2.2 Other Types

The types defined in the specification of the OutgoingMulticastRequest 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.ServiceID
java.io.IOException
java.net.DatagramPacket
java.net.InetAddress

DU.7.2.3 The Interface

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

package net.jini.discovery;

public class OutgoingMulticastRequest {
    public static DatagramPacket[] marshal(int port, 
                                           String[] groups, 
                                           ServiceID[] heard)
            throws IOException {...}
}

DU.7.2.4 The Semantics

The OutgoingMulticastRequest class cannot be instantiated. This class has only one public method, which is static.

The marshal method takes as input the following arguments, none of which may be null:

• The port to which respondents should connect in order to start unicast discovery

• A String array, none of whose elements may be null, in which each element is the name of a group the requesting entity is interested in discovering

• An array of ServiceID objects, none of whose elements may be null, in which each element corresponds to a lookup service the requesting entity has already heard from

Since implementations are not required to check for duplicated elements, the arguments represented as arrays must not contain such elements.

The marshal method returns an array whose elements are instances of DatagramPacket. The array returned will always contain at least one element, and will contain more if the request is not small enough to fit in a single packet. The array returned by this method is fully initialized; it contains a multicast request as payload and is ready to send over the network.

In the event of error, the marshal method may throw an IOException if marshalling fails. In some instances the exception thrown may be a more specific subclass of that exception.

DU.7.3 The IncomingMulticastRequest Utility

DU.7.3.1 Overview

The IncomingMulticastRequest class provides facilities that are useful when a requesting entity's announced interest in discovering a lookup service is received. The facilities provided by this class encapsulate the details of the process of unmarshalling such received multicast discovery requests into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the multicast request protocol as part of a group discovery mechanism, where an entity that uses such a component wishes to receive multicast requests in order to be discovered through its group membership; for example, an entity such as a lookup service.

DU.7.3.2 Other Types

The types defined in the specification of the IncomingMulticastRequest 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.ServiceID
java.io.IOException
java.net.DatagramPacket
java.net.InetAddress

DU.7.3.3 The Interface

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

package net.jini.discovery;

public class IncomingMulticastRequest {
    public IncomingMulticastRequest(DatagramPacket dgram)
        throws IOException {...}
    public InetAddress getAddress() {...}
    public int getPort() {...}
    public String[] getGroups() {...}
    public ServiceID[] getServiceIDs() {...}
}

DU.7.3.4 The Semantics

Including the constructor, the IncomingMulticastRequest class defines five new public methods.

The equals method for this class returns true if and only if two instances of this class have the same address, port, groups, and service ID values.

The constructor of the IncomingMulticastRequest class takes a single input parameter: an instance of DatagramPacket. The payload of this parameter is assumed to contain nothing but a marshalled discovery request.

If the marshalled request contained in the input parameter is corrupt, an IOException or a ClassNotFoundException will be thrown. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.

The getAddress method returns an instance of InetAddress that represents the address of the host to contact in order to start unicast discovery.

The getPort method returns an int value that is the port number to connect to on the remote host in order to start unicast discovery.

The getGroups method returns an array consisting of the names of the groups in which the requesting entity (the originator of this request) is interested. The array returned by this method may be of zero length, none of its elements will be null, and elements in the returned array may or may not be duplicated. Furthermore, the set reflected in the returned array may not be complete, but other incoming packets should contain the rest of the set.

The getServiceIDs method returns an array of ServiceID instances in which each element of the array corresponds to a lookup service from which the requesting entity has already heard. The array returned by this method may be of zero length, none of its elements will be null, and elements in the returned array may or may not be duplicated. Furthermore, the set returned by this method may not be complete. That is, there may be more lookup services from which the requesting entity has already heard, but the set returned by this method will not exceed the capacity of a packet.

DU.7.4 The OutgoingMulticastAnnouncement Utility

DU.7.4.1 Overview

The OutgoingMulticastAnnouncement class encapsulates the details of the process of marshalling multicast discovery announcements into a form suitable for transmission over a network for the purposes of announcing the availability of a lookup service to interested parties. This class is useful when building components that participate in the multicast announcement protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit multicast announcements in order to be discovered as a lookup service belonging to a set of groups in which other discovering entities may be interested.

DU.7.4.2 Other Types

The types defined in the specification of the OutgoingMulticastAnnouncement 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.core.discovery.ServiceID
java.io.IOException
java.net.DatagramPacket

DU.7.4.3 The Interface

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

package net.jini.discovery;

public class OutgoingMulticastAnnouncement {
    public static DatagramPacket[] marshal(ServiceID id, 
                                           LookupLocator loc,
                                           String[]groups)
        throws IOException {...}
}

DU.7.4.4 The Semantics

The OutgoingMulticastAnnouncement class cannot be instantiated. This class has only one public method, which is static.

The marshal method takes as input the following arguments, none of which may be null:

• The instance of ServiceID that corresponds to the lookup service being advertised

• The instance of LookupLocator through which the lookup service being advertised may be discovered through unicast discovery

• A non-null String array, none of whose elements may be null, in which each element is the name of a group in which the lookup service being advertised is a member

The marshal method returns an array whose elements are instances of DatagramPacket, the contents of which represents a marshalled multicast announcement. The packets created by this method, as represented by the elements of the returned array, are guaranteed to contain all of the groups in which the lookup service being advertised is a member. Note that the set of groups reflected in the returned collection of datagram packets may be distributed among those packets.

Each element of the array returned by this method is initialized such that it is ready for transmission to the appropriate multicast address and UDP port.

In the event of error, the marshal method may throw an IOException if marshalling fails. In some instances, the exception thrown may be a more specific subclass of that exception.

DU.7.5 The IncomingMulticastAnnouncement Utility

DU.7.5.1 Overview

The IncomingMulticastAnnouncement class encapsulates the details of the process of unmarshalling multicast discovery announcements into a form in which the individual parameters of the announcement may be easily accessed. This class is useful when building components that participate in the multicast announcement protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to receive multicast announcements in order to discover a lookup service belonging to a set of groups in which the entity is interested.

DU.7.5.2 Other Types

The types defined in the specification of the IncomingMulticastAnnouncement 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.core.discovery.ServiceID
java.io.IOException
java.net.DatagramPacket

DU.7.5.3 The Interface

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

package net.jini.discovery;

public class IncomingMulticastAnnouncement {
    public IncomingMulticastAnnouncement(DatagramPacket p)
        throws IOException {...}
    public ServiceID getServiceID() {...}
    public LookupLocator getLocator() {...}
    public String[] getGroups() {...}
}

DU.7.5.4 The Semantics

Including the constructor, the IncomingMulticastAnnouncement class defines four new public methods.

The equals method for this class returns true if and only if two instances of this class have the same service ID values.

The constructor of the IncomingMulticastAnnouncement class takes a single input parameter: an instance of DatagramPacket. The constructor attempts to unmarshal the input parameter, storing the results in the various fields of this class.

If the contents of the datagram packet cannot be successfully unmarshalled, either an IOException or a ClassNotFoundException is thrown. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.

The getServiceID method returns the ServiceID instance corresponding to the lookup service that sent the announcement.

The getLocator method returns the LookupLocator instance corresponding to the lookup service that sent the announcement. It is through the object returned by this method that the lookup service may be discovered via unicast discovery.

The getGroups method returns an array consisting of the names of the groups in which the lookup service that sent the announcement is a member. The array returned by this method is never null, will contain no null elements, or may be empty. Additionally, elements in the returned array may or may not be duplicated.

DU.7.6 The OutgoingUnicastRequest Utility

DU.7.6.1 Overview

The OutgoingUnicastRequest class encapsulates the details of the process of marshalling unicast discovery requests into a form suitable for transmission over a network to attempt discovery of a specific lookup service. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit unicast requests in order to discover a specific lookup service in which the entity is interested.

DU.7.6.2 Other Types

The types defined in the specification of the OutgoingUnicastRequest 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:

java.io.IOException
java.io.OutputStream

DU.7.6.3 The Interface

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

package net.jini.discovery;

public class OutgoingUnicastRequest {
    public static void marshal(OutputStream str)
        throws IOException {...}
}

DU.7.6.4 The Semantics

The OutgoingUnicastRequest class cannot be instantiated. This class has only one public method, which is static.

The marshal method takes only one parameter as input: an instance of OutputStream, which is the stream to which the unicast request is written. After the unicast request is written to the stream, the stream is flushed.

In the event of error, the marshal method may throw an IOException if writing to the stream fails. In some instances, the exception thrown may be a more specific subclass of that exception.

DU.7.7 The IncomingUnicastRequest Utility

DU.7.7.1 Overview

The IncomingUnicastRequest class encapsulates the details of the process of unmarshalling unicast discovery requests into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity--such as a lookup service--that wishes to receive unicast requests in order to be discovered through direct, unicast communication.

DU.7.7.2 Other Types

The types defined in the specification of the IncomingUnicastRequest 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:

java.io.InputStream
java.io.IOException

DU.7.7.3 The Interface

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

package net.jini.discovery;

public class IncomingUnicastRequest {
    public IncomingUnicastRequest(InputStream str)
        throws IOException {...}
}

DU.7.7.4 The Semantics

The only new public method defined by the IncomingUnicastRequest class is the constructor.

The constructor of the IncomingUnicastRequest class takes a single input parameter: an instance of InputStream, which is the stream from which the unicast request is read.

In the event of error, an IOException may be thrown if reading from the stream fails. In some instances, the exception thrown may be a more specific subclass of that exception.

DU.7.8 The OutgoingUnicastResponse Utility

DU.7.8.1 Overview

The OutgoingUnicastResponse class encapsulates the details of the process of marshalling a unicast discovery response into a form suitable for transmission over a network to respond to a unicast discovery request. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of a entity--such as a lookup service--that wishes to transmit responses to unicast requests in order to be discovered through direct, unicast communication.

DU.7.8.2 Other Types

The types defined in the specification of the OutgoingUnicastResponse 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.lookup.ServiceRegistrar
java.io.IOException
java.io.OutputStream

DU.7.8.3 The Interface

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

package net.jini.discovery;

public class OutgoingUnicastResponse {
    public static void marshal(OutputStream s, 
                               ServiceRegistrar reg
                               String[] groups)
                                    throws IOException {...}
}

DU.7.8.4 The Semantics

The OutgoingUnicastResponse class cannot be instantiated. This class has only one public method, which is static.

The marshal method takes as input the following arguments, none of which may be null:

• An instance of OutputStream, which is the stream to which the unicast response is written.

• An instance of ServiceRegistrar that references the proxy to the lookup service that will be marshalled and written to the stream.

• A non-null String array, none of whose elements may be null, in which each element is the name of a group in which the lookup service referenced by the reg parameter is a member. Note that duplicate elements are allowed in this parameter.

The marshal method marshals the reg parameter and writes the result to the stream. It then writes each element of the groups parameter to the stream. After the complete unicast response is written to the stream, the stream is flushed.

This method may throw an IOException if a failure occurs while marshalling or writing to the stream. In some instances, the exception thrown may be a more specific subclass of that exception.

DU.7.9 The IncomingUnicastResponse Utility

DU.7.9.1 Overview

The IncomingUnicastResponse class encapsulates the details of the process of unmarshalling a unicast discovery response into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to receive unicast responses in order to discover lookup services through direct, unicast communication.

DU.7.9.2 Other Types

The types defined in the specification of the IncomingUnicastResponse 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.lookup.ServiceRegistrar
java.io.InputStream
java.io.IOException

DU.7.9.3 The Interface

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

package net.jini.discovery;

public class IncomingUnicastResponse {
    public IncomingUnicastResponse(InputStream s)
        throws IOException, ClassNotFoundException {...}
    public ServiceRegistrar getRegistrar() {...}
    public String[] getGroups() {...}
}

DU.7.9.4 The Semantics

Including the constructor, the IncomingUnicastResponse class defines three new methods.

The equals method for this class returns true if and only if two instances of this class reference the same lookup service proxy (registrar).

The constructor of the IncomingUnicastResponse class takes a single input parameter: an instance of InputStream, which is the stream from which the contents of the unicast response is read.

An IOException may be thrown if reading from the stream fails. A ClassNotFoundException may be thrown if failure occurs while unmarshalling the proxy to the lookup service contained in the unicast response. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.

The getRegistrar method returns an instance of ServiceRegistrar that references the proxy to the lookup service sent in the unicast response.

The getGroups method returns an array consisting of the names of the groups in which the lookup service referenced in the response is a member. The array returned by this method is never null, will contain no null elements, or may be empty. Additionally, elements in the returned array may or may not be duplicated.

DU.8 History

Version	Change
v1.0	Initial release of this specification.
v2.0	New constructors added to accommodate configuration, along with supporting text. Added section specifying the ConstrainableLookupLocator. Miscellaneous corrections.
v3.0	Clarify ConstrainableLookupLocator URL parsing, remove reference to LookupLocator toString

¹ The terms "Java virtual machine" and "JVM" mean a virtual machine for the Java platform.

License

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

http://www.apache.org/licenses/LICENSE-2.0