LookupLocatorDiscovery (River-Internet vtrunk API Documentation)

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

All Implemented Interfaces:: DiscoveryLocatorManagement, DiscoveryManagement

public final 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, or its subclass ConstrainableLookupLocator.

Author:

Sun Microsystems, Inc.

See Also:

LookupLocator

Implementation Specifics:

The following implementation-specific items are discussed below:

Configuring LookupLocatorDiscovery
Logging

Configuring LookupLocatorDiscovery This implementation of LookupLocatorDiscovery supports the following configuration entries; where each configuration entry name is associated with the component name net.jini.discovery.LookupLocatorDiscovery. Note that the configuration entries specified here are specific to this implementation of LookupLocatorDiscovery. Unless otherwise stated, each entry is retrieved from the configuration only once per instance of this utility, where each such retrieval is performed in the constructor.

•	`initialUnicastDelayRange`
	Type:	`long`
	Default:	`0 milliseconds`
	Description:	With respect to when this utility is started, this entry controls how long to wait before attempting unicast discovery. If the value is positive, initial unicast discovery requests will be delayed by a random value between `0` and `initialUnicastDelayRange` milliseconds. Once the wait period is up, the `LookupLocator`s specified at construction time are used for initiating unicast discovery requests, unless the managed `LookupLocator`s have been changed in the interim; in which case, no delayed unicast discovery requests are performed. Note that this entry only has effect when this utility is initialized. It does not delay discovery requests that are initiated if the managed `LookupLocator`s are subsequently changed.

• registrarPreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

•	`registrarPreparer`
	Type:	`ProxyPreparer`
	Default:	`new BasicProxyPreparer()`
	Description:	Preparer for the proxies to the lookup services that are discovered and used by this utility. This preparer should perform all operations required to use a newly received proxy to a lookup service, which may including verifying trust in the proxy, granting permissions, and setting constraints. Currently, none of the methods on the `ServiceRegistrar` returned by this preparer are invoked by this implementation of `LookupLocatorDiscovery`.

Preparer for the proxies to the lookup services that are discovered and used by this utility.

This preparer should perform all operations required to use a newly received proxy to a lookup service, which may including verifying trust in the proxy, granting permissions, and setting constraints.

Currently, none of the methods on the ServiceRegistrar returned by this preparer are invoked by this implementation of LookupLocatorDiscovery.

•	`executorService`
	Type:	`ExecutorService`
	Default:	`new ThreadPoolExecutor( 15, 15, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("LookupLocatorDiscovery", false) )`
	Description:	The object that pools and manages the various threads executed by this utility. This object should not be shared with other components in the application that employs this utility.

•	`wakeupManager`
	Type:	`WakeupManager`
	Default:	`new WakeupManager(new WakeupManager.ThreadDesc(null,true))`
	Description:	Object that pools and manages the various tasks that are initially executed by the object corresponding to the `executorService` entry of this component, but which fail during that initial execution. This object schedules the re-execution of such a failed task - in the `executorService` object - at various times in the future, (employing a "backoff strategy"). The re-execution of the failed task will continue to be scheduled by this object until the task finally succeeds. This object should not be shared with other components in the application that employs this utility.

Logging

This implementation of LookupLocatorDiscovery uses the Logger named net.jini.discovery.LookupLocatorDiscovery to log information at the following logging levels:

**`net.jini.discovery.LookupLocatorDiscovery`**
Level	Description
`INFO`	when any exception occurs in a task or thread, while attempting unicast discovery of a given locator
`INFO`	when any exception occurs while attempting to prepare a proxy
`HANDLED`	when an exception is handled during unicast discovery.
`FINEST`	whenever any thread or task is started
`FINEST`	whenever any thread (except the `Notifier` thread) or task completes successfully
`FINEST`	whenever a discovered or discarded event is sent
`FINEST`	whenever a proxy is prepared
`FINEST`	when an `IOException` occurs upon attempting to close the socket after a unicast discovery attempt has either completed successfully or failed

This implementation of LookupLocatorDiscovery determines the constraints (if any) to apply to unicast discovery for a given LookupLocator instance by calling the getConstraints method of that instance, if it implements the RemoteMethodControl interface. If the LookupLocator instance does not implement RemoteMethodControl, then no constraints are applied to unicast discovery for that instance.

For more information on constraining unicast discovery, refer to the documentation for the ConstrainableLookupLocator class.

Constructor Summary

Constructors
Constructor and Description
`LookupLocatorDiscovery(LookupLocator[] locators)` Creates an instance of this class (`LookupLocatorDiscovery`), with an initial array of `LookupLocator`s 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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.jini.discovery.DiscoveryManagement
addDiscoveryListener, discard, getRegistrars, removeDiscoveryListener, terminate

Methods inherited from interface net.jini.discovery.DiscoveryLocatorManagement
addLocators, getLocators, removeLocators, setLocators

- 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.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class LookupLocatorDiscovery

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface net.jini.discovery.DiscoveryManagement

Methods inherited from interface net.jini.discovery.DiscoveryLocatorManagement

Constructor Detail

LookupLocatorDiscovery

LookupLocatorDiscovery

Method Detail

addDiscoveryListener

removeDiscoveryListener

getRegistrars

discard

terminate

getLocators

addLocators

setLocators

removeLocators

getDiscoveredLocators

getUndiscoveredLocators

toString