net.jini.discovery

Class AbstractLookupLocatorDiscovery

java.lang.Object

net.jini.discovery.AbstractLookupLocatorDiscovery

All Implemented Interfaces:

DiscoveryLocatorManagement, DiscoveryManagement

Direct Known Subclasses:

LookupLocatorDiscovery

abstract class AbstractLookupLocatorDiscovery
extends Object
implements DiscoveryManagement, DiscoveryLocatorManagement

This package private superclass of LookupLocatorDiscovery exists for safe construction of LookupLocatorDiscovery's state, while retaining backward compatibility of the API. See www.securecoding.cert.org TSM01-J and OBJ11-J

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	AbstractLookupLocatorDiscovery.DiscoveryTask Task which retrieves elements from the set of undiscoveredLocators and attempts, through the unicast discovery protocol, to discover the lookup service having the LookupLocator referenced by the element.
private static class	AbstractLookupLocatorDiscovery.FutureFactory
private static class	AbstractLookupLocatorDiscovery.Initializer
private class	AbstractLookupLocatorDiscovery.LocatorReg Wrapper class in which each instance corresponds to a lookup service to discover via unicast discovery.
private class	AbstractLookupLocatorDiscovery.Notifier Thread that retrieves data structures of type NotifyTask from a queue and, based on the contents of the data structure, sends the appropriate event (discovered/discarded) to each registered listener.
private static class	AbstractLookupLocatorDiscovery.NotifyTask Data structure containing task data processed by the Notifier Thread

Field Summary

Fields

Modifier and Type	Field and Description
private static String	COMPONENT_NAME
private static int	DEFAULT_SOCKET_TIMEOUT Default timeout to set on sockets used for unicast discovery.
private List<AbstractLookupLocatorDiscovery.LocatorReg>	discoveredLocators Stores LookupLocators that have been discovered
private boolean	discoverLocatorsCalled
private java.util.concurrent.ExecutorService	discoveryExecutor ExecutorService for the discovery tasks.
private WakeupManager	discoveryWakeupMgr Wakeup manager for the discovery tasks.
private static Method	getRegistrarMethod LookupLocator.getRegistrar method, used for looking up client constraints of contained lookup locators.
private long	initialUnicastDelayRange
private List<DiscoveryListener>	listeners Stores DiscoveryListeners
private static Logger	logger
private static int	MAX_N_TASKS Maximum number of concurrent tasks that can be run in any task manager created by this class.
private AbstractLookupLocatorDiscovery.Notifier	notifierThread Thread that handles pending notifications.
private java.util.concurrent.BlockingDeque<AbstractLookupLocatorDiscovery.NotifyTask>	pendingNotifies Notifications to be sent to listeners.
private Discovery	protocol2
private ProxyPreparer	registrarPreparer
private boolean	terminated Flag indicating whether or not this class is still functional.
private Set<AbstractLookupLocatorDiscovery.LocatorReg>	undiscoveredLocators Stores LookupLocators that have not been discovered yet.

Constructor Summary

Constructors

Modifier	Constructor and Description
(package private)	AbstractLookupLocatorDiscovery() Creates an instance of this class
private	AbstractLookupLocatorDiscovery(AbstractLookupLocatorDiscovery.Initializer init)
(package private)	AbstractLookupLocatorDiscovery(Configuration config) Constructs a new lookup locator discovery object, having the given Configuration.

Method Summary

Modifier and Type	Method and Description
private void	addAndQueueDiscoveryTaskIfAbsent(AbstractLookupLocatorDiscovery.LocatorReg reg) Adds the given LocatorReg object to the set containing the objects corresponding to the locators of desired lookup services that have not yet been discovered, and queues a DiscoveryTask to attempt, through unicast discovery, to discover the associated lookup service.
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.
private void	addNotify(List<DiscoveryListener> notifies, Map<ServiceRegistrar,String[]> groupsMap, boolean discard) Add a notification task to the pending queue, and start an instance of the Notifier thread if one isn't already running.
(package private) void	beginDiscovery(LookupLocator[] locators) Using the given Configuration, initializes the current instance of this utility, and initiates the discovery process for the given set of locators.
private ServiceRegistrar[]	buildServiceRegistrar() From each element of the set of LocatorReg objects that correspond to lookup services that have been discovered, this method extracts the ServiceRegistrar reference and returns all of the references in an array of ServiceRegistrar.
private Map<ServiceRegistrar,String[]>	deepCopy(Map<ServiceRegistrar,String[]> groupsMap) Creates and returns a deep copy of the input parameter.
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.
private void	discoverLocators(LookupLocator[] lcts) Initiates the discovery process for the lookup services having the given locators.
private AbstractLookupLocatorDiscovery.LocatorReg	findReg(LookupLocator lct) From the sets of elements corresponding to yet-to-be-discovered locators, this methods finds and returns the instance of LocatorReg corresponding to the given LookupLocator.
private LookupLocator	findRegFromProxy(ServiceRegistrar proxy) This method searches the set of discovered LocatorReg objects for the element that contains the given ServiceRegistrar object.
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.
private static AbstractLookupLocatorDiscovery.Initializer	init(Configuration config)
private static AbstractLookupLocatorDiscovery.Initializer	initEmptyConfig()
private boolean	isArrayContains(Object[] a, Object obj) Determines if the given Object is an element of the given array.
private boolean	isDiscovered(LookupLocator lct) Determines whether or not the lookup service associated with the given LookupLocator has already been discovered.
private Map	mapRegToGroups(ServiceRegistrar reg, String[] curGroups) Convenience method that creates and returns a mapping of a single ServiceRegistrar instance to a set of groups.
private boolean	regTryGetProxy(AbstractLookupLocatorDiscovery.LocatorReg reg) Convenience method called from within the DiscoveryTask.
private AbstractLookupLocatorDiscovery.LocatorReg	removeDiscoveredLocator(LookupLocator lct) Convenience method used to remove the LocatorReg - corresponding to the given LookupLocator - from the set of LocatorReg objects that correspond to lookup services that have already 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.
private void	terminateTaskMgr() Convenience method that removes all pending and active tasks from the TaskManager, and removes all pending tasks from the WakeupManager.
private void	testSetForNull(LookupLocator[] locatorSet) This method is used by the public methods of this class that are specified to throw a NullPointerException when the set of locators is either null or contains one or more null elements; in either case, this method throws a NullPointerException which should be allowed to propagate outward.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

COMPONENT_NAME

private static final String COMPONENT_NAME

See Also:

Constant Field Values

logger

private static final Logger logger

MAX_N_TASKS

private static final int MAX_N_TASKS

Maximum number of concurrent tasks that can be run in any task manager created by this class.

See Also:

Constant Field Values

DEFAULT_SOCKET_TIMEOUT

private static final int DEFAULT_SOCKET_TIMEOUT

Default timeout to set on sockets used for unicast discovery.

See Also:

Constant Field Values

getRegistrarMethod

private static final Method getRegistrarMethod

LookupLocator.getRegistrar method, used for looking up client constraints of contained lookup locators.

discoveryExecutor

private final java.util.concurrent.ExecutorService discoveryExecutor

ExecutorService for the discovery tasks. On the first attempt to discover each locator, the tasks used to perform those discoveries are managed by this ExecutorService so that the number of concurrent threads can be bounded. If one or more of those attempts fails, a WakeupManager is used (through the use of a RetryTask) to schedule - at a later time (employing a "backoff strategy") - the re-execution of each failed task in this ExecutorService.

discoveryWakeupMgr

private final WakeupManager discoveryWakeupMgr

Wakeup manager for the discovery tasks. For any locator, after an initial failure to discover the locator, the task used to perform all future discovery attempts is managed by this WakeupManager; which schedules the re-execution of the failed task - in the task manager - at various times in the future until the locator is successfully discovered. This wakeup manager is supplied to the RetryTask) that performs the actual discovery attempt(s) so that when termination of this lookup locator discovery utility is requested, all tasks scheduled for retry by this wakeup manager can be cancelled.

undiscoveredLocators

private final Set<AbstractLookupLocatorDiscovery.LocatorReg> undiscoveredLocators

Stores LookupLocators that have not been discovered yet.

discoveredLocators

private final List<AbstractLookupLocatorDiscovery.LocatorReg> discoveredLocators

Stores LookupLocators that have been discovered

notifierThread

private final AbstractLookupLocatorDiscovery.Notifier notifierThread

Thread that handles pending notifications.

pendingNotifies

private final java.util.concurrent.BlockingDeque<AbstractLookupLocatorDiscovery.NotifyTask> pendingNotifies

Notifications to be sent to listeners.

listeners

private final List<DiscoveryListener> listeners

Stores DiscoveryListeners

terminated

private volatile boolean terminated

Flag indicating whether or not this class is still functional.

registrarPreparer

private final ProxyPreparer registrarPreparer

protocol2

private final Discovery protocol2

initialUnicastDelayRange

private final long initialUnicastDelayRange

discoverLocatorsCalled

private volatile boolean discoverLocatorsCalled

Constructor Detail

AbstractLookupLocatorDiscovery

AbstractLookupLocatorDiscovery()

Creates an instance of this class

AbstractLookupLocatorDiscovery

AbstractLookupLocatorDiscovery(Configuration config)
                        throws ConfigurationException

Constructs a new lookup locator discovery object, having the given Configuration.

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

Parameters:

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 - null is input for the configuration

AbstractLookupLocatorDiscovery

private AbstractLookupLocatorDiscovery(AbstractLookupLocatorDiscovery.Initializer init)

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.

discoverLocators

private void discoverLocators(LookupLocator[] lcts)

Initiates the discovery process for the lookup services having the given locators.

findReg

private AbstractLookupLocatorDiscovery.LocatorReg findReg(LookupLocator lct)

From the sets of elements corresponding to yet-to-be-discovered locators, this methods finds and returns the instance of LocatorReg corresponding to the given LookupLocator. This method searches the set of undiscoveredLocators, and upon finding a matching LocatorReg object, that object is returned; otherwise, null is returned.

findRegFromProxy

private LookupLocator findRegFromProxy(ServiceRegistrar proxy)

This method searches the set of discovered LocatorReg objects for the element that contains the given ServiceRegistrar object. Upon finding such an element, the corresponding LookupLocator is returned; otherwise, null is returned.

regTryGetProxy

private boolean regTryGetProxy(AbstractLookupLocatorDiscovery.LocatorReg reg)

Convenience method called from within the DiscoveryTask. Employing unicast discovery, this method attempts to discover the lookup service associated with the given LocatorReg. After successfully discovering the desired lookup service, this method queues the appropriate event for dissemination to the registered listeners, and then returns true; otherwise false is returned.

buildServiceRegistrar

private ServiceRegistrar[] buildServiceRegistrar()

From each element of the set of LocatorReg objects that correspond to lookup services that have been discovered, this method extracts the ServiceRegistrar reference and returns all of the references in an array of ServiceRegistrar.

addAndQueueDiscoveryTaskIfAbsent

private void addAndQueueDiscoveryTaskIfAbsent(AbstractLookupLocatorDiscovery.LocatorReg reg)

Adds the given LocatorReg object to the set containing the objects corresponding to the locators of desired lookup services that have not yet been discovered, and queues a DiscoveryTask to attempt, through unicast discovery, to discover the associated lookup service.

isDiscovered

private boolean isDiscovered(LookupLocator lct)

Determines whether or not the lookup service associated with the given LookupLocator has already been discovered.

addNotify

private void addNotify(List<DiscoveryListener> notifies,
                       Map<ServiceRegistrar,String[]> groupsMap,
                       boolean discard)

Add a notification task to the pending queue, and start an instance of the Notifier thread if one isn't already running.

removeDiscoveredLocator

private AbstractLookupLocatorDiscovery.LocatorReg removeDiscoveredLocator(LookupLocator lct)

Convenience method used to remove the LocatorReg - corresponding to the given LookupLocator - from the set of LocatorReg objects that correspond to lookup services that have already been discovered.

terminateTaskMgr

private void terminateTaskMgr()

Convenience method that removes all pending and active tasks from the TaskManager, and removes all pending tasks from the WakeupManager.

isArrayContains

private boolean isArrayContains(Object[] a,
                                Object obj)

Determines if the given Object is an element of the given array.

toString

public String toString()

Overrides:

toString in class Object

testSetForNull

private void testSetForNull(LookupLocator[] locatorSet)

This method is used by the public methods of this class that are specified to throw a NullPointerException when the set of locators is either null or contains one or more null elements; in either case, this method throws a NullPointerException which should be allowed to propagate outward.

Throws:

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

deepCopy

private Map<ServiceRegistrar,String[]> deepCopy(Map<ServiceRegistrar,String[]> groupsMap)

Creates and returns a deep copy of the input parameter. This method assumes the input map is a HashMap of the registrar-to-groups mapping; and returns a clone not only of the map, but of each key-value pair contained in the mapping.

Parameters:

groupsMap - mapping from a set of registrars to the member groups of each registrar

Returns:

clone of the input map, and of each key-value pair contained in the input map

mapRegToGroups

private Map mapRegToGroups(ServiceRegistrar reg,
                           String[] curGroups)

Convenience method that creates and returns a mapping of a single ServiceRegistrar instance to a set of groups.

Parameters:

reg - instance of ServiceRegistrar corresponding to the registrar to use as the key to the mapping

curGroups - String array containing the current member groups of the registrar referenced by the reg parameter; and which is used as the value of the mapping

Returns:

Map instance containing a single mapping from a given registrar to its current member groups

beginDiscovery

void beginDiscovery(LookupLocator[] locators)

Using the given Configuration, initializes the current instance of this utility, and initiates the discovery process for the given set of locators.

Parameters:

locators - the set of locators to discover

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

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

initEmptyConfig

private static AbstractLookupLocatorDiscovery.Initializer initEmptyConfig()

init

private static AbstractLookupLocatorDiscovery.Initializer init(Configuration config)
                                                        throws ConfigurationException

Throws:

ConfigurationException