net.jini.discovery
Class LookupLocatorDiscovery

java.lang.Object
  net.jini.discovery.LookupLocatorDiscovery

All Implemented Interfaces:

DiscoveryLocatorManagement, DiscoveryManagement

public class LookupLocatorDiscovery
extends Object
implements DiscoveryManagement, DiscoveryLocatorManagement

This class 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 lookup services much simpler for both services and clients.

Because this class participates in only the unicast discovery protocol, and because the unicast discovery protocol imposes no restriction on the physical location of the entity 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 host on which the entity is running. This lack of a restriction on location brings with it a requirement that the discovering entity supply this class with specific information about the desired lookup services; namely, the location of the device(s) hosting each lookup service. This information is supplied through an instance of the LookupLocator class.

Author:

Sun Microsystems, Inc.

See Also:

--------------------------------------- Fix 20.7.2007 GigaSpaces issue GS-2216: --------------------------------------- The LookupLocatorDiscovery fix provides the ability to periodically test the reachability of discovered lookup service instances,as well as providing the option to declare retry intervals used to re-establish communication with a failed lookup service. This approach included in this project provides a more responsive unicast discovery approach by declaring the interval(s) the utility will sleep betwen unicast discovery attempts (or retries), and also provides a means to verify lookup service availability by periodically obtaining infomration from the backend implementation. The default behavior of the LookupLocatorDiscovery utility has been modified to create an internal DiscoveryListener that will create a LookAliveTask per discovered LookupService instance. Each LookupAliveTask will periodically invoke the ServiceRegistrar.getLocator() method (resulting in a round trip to the backend implementation). If a non-recoverable exception occurs (ConnectException or otherwise) the LookAliveTask will discard the ServiceRegistrar in question. The periodicity of the LookupAliveTask can be controlled by the com.gigaspaces.unicast.interval system property. The default interval is 1 minute. Example : -Dcom.gigaspaces.unicast.ping=5000 Will cause the LookupLocatorDiscovery utility to wait 5 seconds between invocations of the getLocator() method. The LookupLocatorDiscovery unicast retry (sleep) intervals have been untouched. If the user wishes to tune the unicast retry intervals, the com.gigaspaces.unicast.interval system property is used to control the behavior of this LookupLocatorDiscovery utility. A comma separated list of values defining the intervals to wait between subsequent retries. Values are declared in milliseconds. Example : -Dcom.gigaspaces.unicast.interval=5000 Will cause the LookupLocatorDiscovery utility to wait 5 seconds between retries -Dcom.gigaspaces.unicast.interval=5000,10000 Will cause the LookupLocatorDiscovery utility to first wait 5 seconds, then 10 seconds between retries. This declaration provides a graduating approach (similar in approach to the default settings), increasing the amount of time to wait before the next discovery attempt should be made - upon each invocation, eventually reaching a maximum time interval over which discovery is re-tried. In this way, the network is not flooded with unicast discovery requests referencing a lookup service that may not be available for quite some time (if ever).

Constructor Summary

LookupLocatorDiscovery(LookupLocator[] locators)
Creates an instance of this class (LookupLocatorDiscovery), with an initial array of LookupLocators to be managed.

LookupLocatorDiscovery(LookupLocator[] locators, Configuration config)
Constructs a new lookup locator discovery object, set to discover the given set of locators, and having the given Configuration.

Method Summary

void	addDiscoveryListener(DiscoveryListener l) Add a DiscoveryListener to the listener set.
void	addLocators(LookupLocator[] locators) Adds a set of locators to the managed set of locators.
void	discard(ServiceRegistrar proxy) Removes an instance of ServiceRegistrar from the managed set of lookup services, making the corresponding lookup service eligible for re-discovery.
LookupLocator[]	getDiscoveredLocators() Returns the set of LookupLocator objects representing the desired lookup services that are currently discovered.
LookupLocator[]	getLocators() Returns an array consisting of the elements of the managed set of locators; that is, instances of LookupLocator in which each instance corresponds to a specific lookup service to discover.
ServiceRegistrar[]	getRegistrars() Returns an array of instances of ServiceRegistrar, each corresponding to a proxy to one of the currently discovered lookup services.
LookupLocator[]	getUndiscoveredLocators() Returns the set of LookupLocator objects representing the desired lookup services that have not yet been discovered.
void	removeDiscoveryListener(DiscoveryListener l) Remove a DiscoveryListener from the listener set.
void	removeLocators(LookupLocator[] locators) Deletes a set of locators from the managed set of locators, and discards any already-discovered lookup service that corresponds to a deleted locator.
void	setLocators(LookupLocator[] locators) Replaces all of the locators in the managed set with locators from a new set, and discards any already-discovered lookup service that corresponds to a locator that is removed from the managed set as a result of an invocation of this method.
void	terminate() Terminates all threads, ending all locator discovery processing being performed by the current instance of this class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LookupLocatorDiscovery

public LookupLocatorDiscovery(LookupLocator[] locators)

Creates an instance of this class (LookupLocatorDiscovery), with an initial array of LookupLocators to be managed. For each managed LookupLocator, unicast discovery is performed to obtain a ServiceRegistrar proxy for that lookup service.

Parameters:

locators - the locators to discover

Throws:

NullPointerException - input array contains at least one null element

LookupLocatorDiscovery

public LookupLocatorDiscovery(LookupLocator[] locators,
                              Configuration config)
                       throws ConfigurationException

Constructs a new lookup locator discovery object, set to discover the given set of locators, and having the given Configuration.

For each managed LookupLocator, unicast discovery is performed to obtain a ServiceRegistrar proxy for that lookup service.

Parameters:

locators - the locators to discover

config - an instance of Configuration, used to obtain the objects needed to configure the current instance of this class

Throws:

ConfigurationException - indicates an exception occurred while retrieving an item from the given Configuration

NullPointerException - input array contains at least one null element or null is input for the configuration

Method Detail

addDiscoveryListener

public void addDiscoveryListener(DiscoveryListener l)

Add a DiscoveryListener to the listener set. The listener's discovered method gets called right way with an array of ServiceRegistrars that have already been discovered, and will be called in the future whenever additional lookup services are discovered.

Specified by:

addDiscoveryListener in interface DiscoveryManagement

Parameters:

l - the new DiscoveryListener to add

Throws:

NullPointerException - this exception occurs when null is input to the listener parameter l.

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

removeDiscoveryListener(net.jini.discovery.DiscoveryListener)

removeDiscoveryListener

public void removeDiscoveryListener(DiscoveryListener l)

Remove a DiscoveryListener from the listener set. It does nothing if the DiscoveryListener does not exist in the the listener set.

Specified by:

removeDiscoveryListener in interface DiscoveryManagement

Parameters:

l - the existing DiscoveryListener to remove

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

addDiscoveryListener(net.jini.discovery.DiscoveryListener)

getRegistrars

public ServiceRegistrar[] getRegistrars()

Returns an array of instances of ServiceRegistrar, each corresponding to a proxy to one of the currently discovered lookup services. For each invocation of this method, a new array is returned.

Specified by:

getRegistrars in interface DiscoveryManagement

Returns:

array of instances of ServiceRegistrar, each corresponding to a proxy to one of the currently discovered lookup services

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

ServiceRegistrar, DiscoveryManagement.removeDiscoveryListener(net.jini.discovery.DiscoveryListener)

discard

public void discard(ServiceRegistrar proxy)

Removes an instance of ServiceRegistrar from the managed set of lookup services, making the corresponding lookup service eligible for re-discovery. This method takes no action if the parameter input to this method is null, or if it does not match (using equals) any of the elements in the managed set.

Specified by:

discard in interface DiscoveryManagement

Parameters:

proxy - the instance of ServiceRegistrar to discard from the managed set of lookup services

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

ServiceRegistrar, DiscoveryManagement.discard(net.jini.core.lookup.ServiceRegistrar)

terminate

public void terminate()

Terminates all threads, ending all locator discovery processing being performed by the current instance of this class.

After this method has been invoked, no new lookup services will be discovered, and the effect of any new operations performed on the current instance of this class are undefined.

Specified by:

terminate in interface DiscoveryManagement

See Also:

DiscoveryManagement.terminate()

getLocators

public LookupLocator[] getLocators()

Returns an array consisting of the elements of the managed set of locators; that is, instances of LookupLocator in which each instance corresponds to a specific lookup service to discover. The returned set will include both the set of LookupLocators corresponding to lookup services that have already been discovered as well as the set of those that have not yet been discovered. If the managed set of locators is empty, this method will return the empty array. This method returns a new array upon each invocation.

Specified by:

getLocators in interface DiscoveryLocatorManagement

Returns:

LookupLocator array consisting of the elements of the managed set of locators

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

DiscoveryLocatorManagement.getLocators(), setLocators(net.jini.core.discovery.LookupLocator[])

addLocators

public void addLocators(LookupLocator[] locators)

Adds a set of locators to the managed set of locators. Elements in the input set that duplicate (using the LookupLocator.equals method) elements already in the managed set will be ignored. If the empty array is input, the managed set of locators will not change.

Specified by:

addLocators in interface DiscoveryLocatorManagement

Parameters:

locators - LookupLocator array consisting of the locators to add to the managed set.

Throws:

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

DiscoveryLocatorManagement.addLocators(net.jini.core.discovery.LookupLocator[]), removeLocators(net.jini.core.discovery.LookupLocator[])

setLocators

public void setLocators(LookupLocator[] locators)

Replaces all of the locators in the managed set with locators from a new set, and discards any already-discovered lookup service that corresponds to a locator that is removed from the managed set as a result of an invocation of this method. For any such lookup service that is discarded, a discard notification is sent; and that lookup service will not be eligible for re-discovery (assuming it is not currently eligible for discovery through other means, such as group discovery).

If the empty array is input, locator discovery will cease until this method is invoked with an input parameter that is non-null and non-empty.

Specified by:

setLocators in interface DiscoveryLocatorManagement

Parameters:

locators - LookupLocator array consisting of the locators that will replace the current locators in the managed set.

Throws:

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

DiscoveryLocatorManagement.setLocators(net.jini.core.discovery.LookupLocator[]), getLocators()

removeLocators

public void removeLocators(LookupLocator[] locators)

Deletes a set of locators from the managed set of locators, and discards any already-discovered lookup service that corresponds to a deleted locator. For any lookup service that is discarded as a result of an invocation of this method, a discard notification is sent; and that lookup service will not be eligible for re-discovery (assuming it is not currently eligible for discovery through other means, such as group discovery).

If the empty array is input, this method takes no action.

Specified by:

removeLocators in interface DiscoveryLocatorManagement

Parameters:

locators - LookupLocator array consisting of the locators that will be removed from the managed set.

Throws:

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

See Also:

DiscoveryLocatorManagement.removeLocators(net.jini.core.discovery.LookupLocator[]), addLocators(net.jini.core.discovery.LookupLocator[])

getDiscoveredLocators

public LookupLocator[] getDiscoveredLocators()

Returns the set of LookupLocator objects representing the desired lookup services that are currently discovered. If no lookup services are currently discovered, this method returns the empty array. This method returns a new array upon each invocation.

Returns:

LookupLocator array consisting of the elements from the managed set of locators that correspond to lookup services that have already been discovered.

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.

getUndiscoveredLocators

public LookupLocator[] getUndiscoveredLocators()

Returns the set of LookupLocator objects representing the desired lookup services that have not yet been discovered. If all of the desired lookup services are currently discovered, this method returns the empty array. This method returns a new array upon each invocation.

Returns:

LookupLocator array consisting of the elements from the managed set of locators that correspond to lookup services that have not yet been discovered.

Throws:

IllegalStateException - this exception occurs when this method is called after the terminate method has been called.