LD.2. The Interface

The LookupDiscoveryService interface defines the service—referred to as the lookup discovery service—previously introduced in this specification. Through this interface, other Jini services and clients may request that discovery processing be performed on their behalf. This interface belongs to the net.jini.discovery package, and any service implementing this interface must comply with the definition of a Jini service. This interface is not a remote interface; each implementation of this service exports a front-end proxy object that implements this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server (the back end). All of the proxy methods must obey normal Java Remote Method Invocation (RMI) remote interface semantics except where explicitly noted. Two proxy objects are equal (using the equals method) if they are proxies for the same lookup discovery service.

The one method defined in this interface throws a RemoteException, and requires only the default serialization semantics so that this interface can be implemented directly using Java RMI.

package net.jini.discovery; 

public interface LookupDiscoveryService {
    public LookupDiscoveryRegistration register(
                              String[] groups, 
                              LookupLocator[] locators, 
                              RemoteEventListener listener, 
                              MarshalledObject handback, 
                              long leaseDuration) 
                                      throws RemoteException; 
} 

When requesting a registration with the lookup discovery service, the client indicates the lookup services it is interested in discovering by submitting two sets of objects. Each set may contain zero or more elements. One set consists of the names of the groups whose members are lookup services the client wishes to be discovered. The other set consists of LookupLocator objects, each corresponding to a specific lookup service the client wishes to be discovered.

For each successful registration the lookup discovery service will manage both the set of group names and the set of locators submitted. These sets will be referred to as the managed set of groups and the managed set of locators, respectively. The managed set of groups associated with a particular registration contains the names of the groups whose members consist of lookup services that the client wishes to be discovered through multicast discovery. Similarly, the managed set of locators contains instances of LookupLocator, each corresponding to a specific lookup service that the client wishes to be discovered through unicast discovery. The references to the lookup services that have been discovered will be maintained in a set referred to as the managed set of lookup services (or managed set of registrars).

Note that when the general term managed set is used, it should be clear from the context whether groups, locators, or registrars are being discussed. Furthermore, when the term group discovery or locator discovery is used, it should be taken to mean, respectively, the employment of either the multicast discovery protocols or the unicast discovery protocol to discover lookup services that correspond to members of the appropriate managed set.