net.jini.discovery

Interface LookupDiscoveryService

public interface LookupDiscoveryService

Defines the interface to the lookup discovery service. This interface is not a remote interface; each implementation of this service exports proxy objects that implement the LookupDiscoveryService interface local to the client, using an implementation-specific protocol to communicate with the actual remote server. All of the proxy methods obey normal RMI remote interface semantics except where explicitly noted. Two proxy objects are equal if they are proxies for the same lookup discovery service.

Author:

Sun Microsystems, Inc.

See Also:

LookupDiscoveryRegistration

Method Summary

Modifier and Type	Method and Description
LookupDiscoveryRegistration	register(String[] groups, LookupLocator[] locators, RemoteEventListener listener, MarshalledObject handback, long leaseDuration) Register with the lookup discovery service.

Method Detail

register

LookupDiscoveryRegistration register(String[] groups,
                                     LookupLocator[] locators,
                                     RemoteEventListener listener,
                                     MarshalledObject handback,
                                     long leaseDuration)
                              throws RemoteException

Register with the lookup discovery service. When a client invokes this method, it requests that the lookup discovery service perform discovery processing on its behalf.

An invocation of this method produces an object - referred to as a registration object (or simply, a registration) - that is mutable. Because the registration produced by this method is mutable, each invocation of this method produces a new registration object. Thus, this method is not idempotent.

To register with the lookup discovery service, the client must indicate the lookup services it is interested in discovering. It does this by submitting two sets of of objects. 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. The state information managed by the lookup discovery service contains no knowledge of the clients that register. Thus, there is no requirement that the client identify itself during the registration process.

Registration with the lookup discovery service includes registration with the event mechanism of the lookup discovery service. That is, for each registration created as a result of an invocation of this method, an event identifier will be generated that uniquely maps the registration to the listener object and to the set of groups and locators input to this method. This event identifier is returned as a part of the registration object, and is unique across all other active registrations with the lookup discovery service.

While the registration is in effect, whenever the lookup discovery service finds a lookup service matching the discovery criteria of one or more of its registrations, an instance of net.jini.discovery.RemoteDiscoveryEvent will be sent to the listener corresponding to each such registration. The event sent to each listener will contain the appropriate event identifier.

Any registration granted as a result of an invocation of this method is leased. The initial duration of the lease granted to a client by the lookup discovery service will be less than or equal to the requested duration input to this method. Any registration with the lookup discovery service is persistent across restarts (crashes) of the lookup discovery service until the lease on the registration expires or is cancelled.

Parameters:

groups - String array, none of whose elements may be null, consisting of zero or more names of groups to which lookup services to discover belong. A value of null (net.jini.discovery.LookupDiscovery.ALL_GROUPS) is acceptable. If null is passed to this argument, the lookup discovery service will attempt to discover all lookup services located within the multicast radius of the host on which the lookup discovery service is running. If an empty array (net.jini.discovery.LookupDiscovery.NO_GROUPS) is passed to this argument, then no group discovery will be performed for the associated registration until the client, through one of the registration's methods, populates the managed set of groups.

locators - array of zero or more non-null LookupLocator objects, each corresponding to a specific lookup service to discover. If either the empty array or null is passed to this argument, then no locator discovery will be performed for the associated registration until the client, through one of the registration's methods, populates the managed set of locators.

listener - a non-null instance of RemoteEventListener. This argument specifies the entity that will receive events notifying the registration that a lookup service of interest has been discovered. A non-null value must be passed to this argument, otherwise a NullPointerException will be thrown and the registration will not succeed.

handback - null or an instance of MarshalledObject. This argument specifies an object that will be included in the notification event that the lookup discovery service sends to the registered listener.

leaseDuration - long value representing the amount of time (in milliseconds) for which the resources of the lookup discovery service are being requested.

Returns:

an instance of the LookupDiscoveryRegistration interface.

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration may or may not have completed successfully.

NullPointerException - this exception occurs when null is input to the listener parameter, as well as when one or more of the elements of the groups parameter is null.

IllegalArgumentException - this exception occurs when the value input to the leaseDuration parameter is neither positive, Lease.FOREVER, nor Lease.ANY.