public class LookupLocatorDiscovery extends Object implements DiscoveryManagement, DiscoveryLocatorManagement
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
.
LookupLocator
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 • |
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
|
  | 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
|
• |
taskManager
| |
---|---|---|
  | Type: | TaskManager
|
  | Default: | new
|
  | Description: | The object that pools and manages the various threads executed by this utility. The default manager creates a maximum of 15 threads, waits 15 seconds before removing idle threads, and uses a load factor of 1.0 when determining whether to create a new thread. This object should not be shared with other components in the application that employs this utility. |
• |
wakeupManager
| |
---|---|---|
  | Type: | WakeupManager
|
  | Default: | new
|
  | Description: | Object that pools and manages the various tasks that are
initially executed by the object corresponding to the
taskManager entry
of this component, but which fail during that initial execution.
This object schedules the re-execution of such a failed task -
in the taskManager
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:
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.
Modifier and Type | Class and Description |
---|---|
private class |
LookupLocatorDiscovery.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 class |
LookupLocatorDiscovery.LocatorReg
Wrapper class in which each instance corresponds to a lookup service
to discover via unicast discovery.
|
private class |
LookupLocatorDiscovery.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 |
LookupLocatorDiscovery.NotifyTask
Data structure containing task data processed by the Notifier Thread
|
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 ArrayList |
discoveredLocators
Stores LookupLocators that have been discovered
|
private boolean |
discoverLocatorsCalled |
private TaskManager |
discoveryTaskMgr
Task manager 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 ArrayList |
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 LookupLocatorDiscovery.Notifier |
notifierThread
Thread that handles pending notifications.
|
private LinkedList |
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 HashSet |
undiscoveredLocators
Stores LookupLocators that have not been discovered yet.
|
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 . |
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.
|
private void |
addNotify(ArrayList notifies,
Map 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.
|
private void |
addToMap(LookupLocatorDiscovery.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.
|
private void |
beginDiscovery(LookupLocator[] locators,
Configuration config)
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 |
deepCopy(HashMap 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 LookupLocatorDiscovery.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 void |
init(Configuration config) |
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 void |
printMap() |
private boolean |
regTryGetProxy(LookupLocatorDiscovery.LocatorReg reg)
Convenience method called from within the DiscoveryTask.
|
private LookupLocatorDiscovery.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. |
private static final String COMPONENT_NAME
private static final Logger logger
private static final int MAX_N_TASKS
private static final int DEFAULT_SOCKET_TIMEOUT
private static final Method getRegistrarMethod
private TaskManager discoveryTaskMgr
TaskManager
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
TaskManager
.private WakeupManager discoveryWakeupMgr
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.private final HashSet undiscoveredLocators
private final ArrayList discoveredLocators
private LookupLocatorDiscovery.Notifier notifierThread
private LinkedList pendingNotifies
private final ArrayList listeners
private boolean terminated
private ProxyPreparer registrarPreparer
private Discovery protocol2
private long initialUnicastDelayRange
private boolean discoverLocatorsCalled
public LookupLocatorDiscovery(LookupLocator[] locators)
LookupLocatorDiscovery
),
with an initial array of LookupLocator
s to be managed.
For each managed LookupLocator
, unicast discovery is
performed to obtain a ServiceRegistrar
proxy for that
lookup service.locators
- the locators to discoverNullPointerException
- input array contains at least
one null
elementpublic LookupLocatorDiscovery(LookupLocator[] locators, Configuration config) throws ConfigurationException
Configuration
.
For each managed LookupLocator
, unicast discovery is
performed to obtain a ServiceRegistrar
proxy for that
lookup service.
locators
- the locators to discoverconfig
- an instance of Configuration
, used to
obtain the objects needed to configure the current
instance of this classConfigurationException
- 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 configurationpublic void addDiscoveryListener(DiscoveryListener l)
addDiscoveryListener
in interface DiscoveryManagement
l
- the new DiscoveryListener to addNullPointerException
- 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.removeDiscoveryListener(net.jini.discovery.DiscoveryListener)
public void removeDiscoveryListener(DiscoveryListener l)
removeDiscoveryListener
in interface DiscoveryManagement
l
- the existing DiscoveryListener to removeIllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.addDiscoveryListener(net.jini.discovery.DiscoveryListener)
public ServiceRegistrar[] getRegistrars()
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.getRegistrars
in interface DiscoveryManagement
ServiceRegistrar
, each
corresponding to a proxy to one of the currently discovered
lookup servicesIllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.ServiceRegistrar
,
DiscoveryManagement.removeDiscoveryListener(net.jini.discovery.DiscoveryListener)
public void discard(ServiceRegistrar proxy)
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.discard
in interface DiscoveryManagement
proxy
- the instance of ServiceRegistrar
to discard
from the managed set of lookup servicesIllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.ServiceRegistrar
,
DiscoveryManagement.discard(net.jini.core.lookup.ServiceRegistrar)
public void terminate()
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.
terminate
in interface DiscoveryManagement
DiscoveryManagement.terminate()
public LookupLocator[] getLocators()
LookupLocator
in
which each instance corresponds to a specific lookup service to
discover. The returned set will include both the set of
LookupLocator
s 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.getLocators
in interface DiscoveryLocatorManagement
LookupLocator
array consisting of the elements
of the managed set of locatorsIllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.DiscoveryLocatorManagement.getLocators()
,
setLocators(net.jini.core.discovery.LookupLocator[])
public void addLocators(LookupLocator[] locators)
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.addLocators
in interface DiscoveryLocatorManagement
locators
- LookupLocator
array consisting of the
locators to add to the managed set.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.DiscoveryLocatorManagement.addLocators(net.jini.core.discovery.LookupLocator[])
,
removeLocators(net.jini.core.discovery.LookupLocator[])
public void setLocators(LookupLocator[] locators)
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.
setLocators
in interface DiscoveryLocatorManagement
locators
- LookupLocator
array consisting of the
locators that will replace the current locators in the
managed set.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.DiscoveryLocatorManagement.setLocators(net.jini.core.discovery.LookupLocator[])
,
getLocators()
public void removeLocators(LookupLocator[] locators)
If the empty array is input, this method takes no action.
removeLocators
in interface DiscoveryLocatorManagement
locators
- LookupLocator
array consisting of the
locators that will be removed from the managed set.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.DiscoveryLocatorManagement.removeLocators(net.jini.core.discovery.LookupLocator[])
,
addLocators(net.jini.core.discovery.LookupLocator[])
public LookupLocator[] getDiscoveredLocators()
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.LookupLocator
array consisting of the elements
from the managed set of locators that correspond to lookup
services that have already been discovered.IllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.public LookupLocator[] getUndiscoveredLocators()
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.LookupLocator
array consisting of the elements
from the managed set of locators that correspond to lookup
services that have not yet been discovered.IllegalStateException
- this exception occurs when
this method is called after the terminate
method has been called.private void discoverLocators(LookupLocator[] lcts)
private LookupLocatorDiscovery.LocatorReg findReg(LookupLocator lct)
private LookupLocator findRegFromProxy(ServiceRegistrar proxy)
private boolean regTryGetProxy(LookupLocatorDiscovery.LocatorReg reg)
true
; otherwise false
is returned.private ServiceRegistrar[] buildServiceRegistrar()
private void addToMap(LookupLocatorDiscovery.LocatorReg reg)
private boolean isDiscovered(LookupLocator lct)
private void addNotify(ArrayList notifies, Map groupsMap, boolean discard)
private LookupLocatorDiscovery.LocatorReg removeDiscoveredLocator(LookupLocator lct)
private void terminateTaskMgr()
private boolean isArrayContains(Object[] a, Object obj)
private void printMap()
private void testSetForNull(LookupLocator[] locatorSet)
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.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
.private Map deepCopy(HashMap groupsMap)
groupsMap
- mapping from a set of registrars to the member groups
of each registrarprivate Map mapRegToGroups(ServiceRegistrar reg, String[] curGroups)
ServiceRegistrar
instance to a set of groups.reg
- instance of ServiceRegistrar
corresponding to the registrar to use as the key
to the mappingcurGroups
- String
array containing the current
member groups of the registrar referenced by the
reg
parameter; and which is used
as the value of the mappingMap
instance containing a single mapping from
a given registrar to its current member groupsprivate void beginDiscovery(LookupLocator[] locators, Configuration config) throws ConfigurationException
Configuration
, initializes the current
instance of this utility, and initiates the discovery process for
the given set of locators.locators
- the set of locators to discoverconfig
- an instance of Configuration
, used to
obtain the objects needed to configure this utilityConfigurationException
- 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 configurationprivate void init(Configuration config) throws ConfigurationException
ConfigurationException
Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.