net.jini.discovery

Class AbstractLookupDiscoveryManager

java.lang.Object

net.jini.discovery.AbstractLookupDiscoveryManager

All Implemented Interfaces:

DiscoveryGroupManagement, DiscoveryLocatorManagement, DiscoveryManagement

Direct Known Subclasses:

LookupDiscoveryManager

abstract class AbstractLookupDiscoveryManager
extends Object
implements DiscoveryManagement, DiscoveryGroupManagement, DiscoveryLocatorManagement

This package private superclass of LookupDiscoverManager exists for safe construction of LookupDiscoveryManager'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	AbstractLookupDiscoveryManager.GroupDiscoveryListener Class that defines the listener that is registered with the LookupDiscovery that performs group discovery on behalf of this LookupDiscoveryManager.
(package private) class	AbstractLookupDiscoveryManager.LocatorDiscoveryListener Class that defines the listener that is registered with the LookupLocatorDiscovery that performs locator discovery on behalf of this LookupDiscoveryManager.
(package private) class	AbstractLookupDiscoveryManager.ProxyReg Wrapper class in which each instance corresponds to a lookup service that has been discovered via either group discovery, locator discovery, or both.

Field Summary

Fields

Modifier and Type	Field and Description
private static int	CHANGED
private static String	COMPONENT_NAME
private static int	DISCARDED
private static int	DISCOVERED Constants used to indicate the type of event to send
private List<AbstractLookupDiscoveryManager.ProxyReg>	discoveredSet Contains instances of the ProxyReg wrapper class.
private java.util.concurrent.locks.Lock	discoveredSetAddLock
static int	FROM_GROUP Constant that indicates the discovery mechanism is group discovery
static int	FROM_LOCATOR Constant that indicates the discovery mechanism is locator discovery
private DiscoveryListener	groupListener The listener that receives discovered, discarded, and changed events from the LookupDiscovery utility that manages group discovery on behalf of this LookupDiscoveryManager.
private Set<DiscoveryListener>	listeners Contains the instances of DiscoveryListener that clients register with the LookupDiscoveryManager.
private LookupLocatorDiscovery	locatorDisc The LookupLocatorDiscovery utility used to manage the locator discovery mechanism.
private DiscoveryListener	locatorListener The listener that receives discovered and discarded events from the LookupLocatorDiscovery utility that manages locator discovery on behalf of this LookupDiscoveryManager.
private static Logger	logger
private LookupDiscovery	lookupDisc The LookupDiscovery utility used to manage the group discovery mechanism.

Fields inherited from interface net.jini.discovery.DiscoveryGroupManagement

ALL_GROUPS, NO_GROUPS

Constructor Summary

Constructors

Constructor and Description
AbstractLookupDiscoveryManager(DiscoveryListener listener, LookupDiscovery lookup, LookupLocatorDiscovery locator) Constructs an instance of this class

Method Summary

Modifier and Type	Method and Description
void	addDiscoveryListener(DiscoveryListener listener) Adds an instance of DiscoveryListener to the set of objects listening for discovery events.
void	addGroups(String[] groups) Adds a set of group names to the managed set of groups.
void	addLocators(LookupLocator[] locators) Adds a set of locators to the managed set of locators.
(package private) void	beginDiscovery() Initiates the discovery process for the given set of groups and the given set of locators.
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 AbstractLookupDiscoveryManager.ProxyReg	findReg(ServiceRegistrar proxy)
int	getFrom(ServiceRegistrar proxy) Return where the proxy came from.
String[]	getGroups() Returns an array consisting of the elements of the managed set of groups; that is, the names of the groups whose members are the lookup services to discover.
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.
private static boolean	groupSetsEqual(String[] groupSet0, String[] groupSet1) Determines if two sets of registrar member groups have identical contents.
private void	notifyListener(DiscoveryListener l, Map<ServiceRegistrar,String[]> groupsMap, int eventType) Notify a specific listener for a discovery event.
private void	notifyListener(Map<ServiceRegistrar,String[]> groupsMap, int eventType) Notify all listeners for a discovery event.
void	removeDiscoveryListener(DiscoveryListener listener) Removes a listener from the set of objects listening for discovery events.
void	removeGroups(String[] groups) Deletes a set of group names from the managed set of groups.
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	setGroups(String[] groups) Replaces all of the group names in the managed set with names from a new set.
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.
private boolean	stillInterested(String[] regGroups, String[] desiredGroups) Determines if at least one member group of a given registrar is contained in the given set of desired groups.
void	terminate() Terminates all threads, ending all 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

Field Detail

COMPONENT_NAME

private static final String COMPONENT_NAME

See Also:

Constant Field Values

logger

private static final Logger logger

FROM_GROUP

public static final int FROM_GROUP

Constant that indicates the discovery mechanism is group discovery

See Also:

Constant Field Values

FROM_LOCATOR

public static final int FROM_LOCATOR

Constant that indicates the discovery mechanism is locator discovery

See Also:

Constant Field Values

DISCOVERED

private static final int DISCOVERED

Constants used to indicate the type of event to send

See Also:

Constant Field Values

DISCARDED

private static final int DISCARDED

See Also:

Constant Field Values

CHANGED

private static final int CHANGED

See Also:

Constant Field Values

discoveredSet

private final List<AbstractLookupDiscoveryManager.ProxyReg> discoveredSet

Contains instances of the ProxyReg wrapper class. This set acts as what is referred to as the "managed set of registrars" or simply, the "managed set". When a registrar is discovered, that registrar and its associated "discovered state" is wrapped in an instance of ProxyReg, which is then placed in this set, which is managed by this LookupDiscoveryManager. As registrars are discovered and discarded, and as the discovered state of those registrars is modified, the contents of this set are modified appropriately. Note that this set is shared across threads; therefore, when accessing or modifying the contents of this set, the appropriate synchronization must be applied. A list is used instead of a Set, because hashCode and equals are remote calls. However we need to avoid duplicates and since this requires list traversal using remote method calls during add, we need a lock to prevent concurrent additions. Removal while an add operation is in progress would be acceptable, since the worst case scenario is the iterator snapshot would contain the removed ProxyReg.

discoveredSetAddLock

private final java.util.concurrent.locks.Lock discoveredSetAddLock

listeners

private final Set<DiscoveryListener> listeners

Contains the instances of DiscoveryListener that clients register with the LookupDiscoveryManager. The elements of this set receive discovered events, discarded events and, when appropriate, changed events.

lookupDisc

private final LookupDiscovery lookupDisc

The LookupDiscovery utility used to manage the group discovery mechanism. Note that this object cannot be accessed outside of this LookupDiscoveryManager.

groupListener

private final DiscoveryListener groupListener

The listener that receives discovered, discarded, and changed events from the LookupDiscovery utility that manages group discovery on behalf of this LookupDiscoveryManager.

locatorDisc

private final LookupLocatorDiscovery locatorDisc

The LookupLocatorDiscovery utility used to manage the locator discovery mechanism. Note that this object cannot be accessed outside of this LookupDiscoveryManager.

locatorListener

private final DiscoveryListener locatorListener

The listener that receives discovered and discarded events from the LookupLocatorDiscovery utility that manages locator discovery on behalf of this LookupDiscoveryManager.

Constructor Detail

AbstractLookupDiscoveryManager

AbstractLookupDiscoveryManager(DiscoveryListener listener,
                               LookupDiscovery lookup,
                               LookupLocatorDiscovery locator)

Constructs an instance of this class

Method Detail

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

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:

UnsupportedOperationException - this exception occurs when there is no managed set of locators to augment. That is, the current managed set of locators is null.

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.

See Also:

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

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:

UnsupportedOperationException - this exception occurs when there is no managed set of locators from which remove elements.

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

See Also:

DiscoveryLocatorManagement.removeLocators(net.jini.core.discovery.LookupLocator[]), addLocators(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 null is input to the locators parameter.

See Also:

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

getGroups

public String[] getGroups()

Returns an array consisting of the elements of the managed set of groups; that is, the names of the groups whose members are the lookup services to discover. If the managed set of groups is empty, this method will return the empty array. If there is no managed set of groups, then null is returned; indicating that all groups are to be discovered. This method returns a new array upon each invocation.

Specified by:

getGroups in interface DiscoveryGroupManagement

Returns:

String array consisting of the elements of the managed set of groups

See Also:

DiscoveryGroupManagement.getGroups(), setGroups(java.lang.String[])

addGroups

public void addGroups(String[] groups)
               throws IOException

Adds a set of group names to the managed set of groups. Elements in the input set that duplicate elements already in the managed set will be ignored. Once a new name is added to the managed set, attempts will be made to discover all (as yet) undiscovered lookup services that are members of the group having that name. If the empty array (DiscoveryGroupManagement.NO_GROUPS) is input, the managed set of groups will not change. Note that any entity that invokes this method must have DiscoveryPermission on each of the groups in the new set, otherwise a SecurityException will be propagated through this method.

Specified by:

addGroups in interface DiscoveryGroupManagement

Parameters:

groups - String array consisting of the group names to add to the managed set.

Throws:

IOException - because an invocation of this method may result in the re-initiation of the discovery process, which can throw an IOException when socket allocation occurs.

UnsupportedOperationException - this exception occurs when there is no managed set of groups to augment. That is, the current managed set of groups is null. If the managed set of groups is null, all groups are being discovered; thus, requesting that a set of groups be added to the set of all groups makes no sense.

NullPointerException - this exception occurs when either null is input to the groups parameter, or one or more of the elements of the groups parameter is null. If a null is input, then the entity is effectively requesting that "all groups" be added to the current managed set of groups; which is not allowed. (Note that if the entity wishes to change the managed set of groups from a finite set of names to "all groups", the setGroups method should be invoked with null input.)

See Also:

DiscoveryGroupManagement.addGroups(java.lang.String[]), removeGroups(java.lang.String[])

removeGroups

public void removeGroups(String[] groups)

Deletes a set of group names from the managed set of groups. If the empty array (DiscoveryGroupManagement.NO_GROUPS) is input, this method takes no action.

Specified by:

removeGroups in interface DiscoveryGroupManagement

Parameters:

groups - String array consisting of the group names that will be removed from the managed set.

Throws:

UnsupportedOperationException - this exception occurs when there is no managed set of groups from which to remove elements.

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

See Also:

DiscoveryGroupManagement.removeGroups(java.lang.String[]), addGroups(java.lang.String[])

setGroups

public void setGroups(String[] groups)
               throws IOException

Replaces all of the group names in the managed set with names from a new set. Once a new group name has been placed in the managed set, if there are lookup services belonging to that group that have already been discovered, no event will be sent to the entity's listener for those particular lookup services. Attempts to discover all (as yet) undiscovered lookup services belonging to that group will continue to be made.

If null (DiscoveryGroupManagement.ALL_GROUPS) is input to this method, then attempts will be made to discover all (as yet) undiscovered lookup services that are within range, and which are members of any group. If the empty array (DiscoveryGroupManagement.NO_GROUPS) is input, then group discovery will cease until this method is invoked with an input parameter that is non-null and non-empty. Note that any entity that invokes this method must have DiscoveryPermission on each of the groups in the new set, otherwise a SecurityException will be propagated through this method.

Specified by:

setGroups in interface DiscoveryGroupManagement

Parameters:

groups - String array consisting of the group names that will replace the current names in the managed set.

Throws:

IOException - because an invocation of this method may result in the re-initiation of the discovery process, which can throw an IOException when socket allocation occurs.

See Also:

DiscoveryGroupManagement.setGroups(java.lang.String[]), getGroups()

addDiscoveryListener

public void addDiscoveryListener(DiscoveryListener listener)

Adds an instance of DiscoveryListener to the set of objects listening for discovery events. Once the listener is registered, it will be notified of all lookup services discovered to date, and will then be notified as new lookup services are discovered or existing lookup services are discarded.

The listener methods may throw Error or RuntimeException subclasses. They will normally be reported only through the log. If the discovered method throws Throwable T during the initial discovery of existing services then this method will also throw T.

If null is input, this method takes no action. If the listener input to this method duplicates (using the equals method) another element in the current set of listeners, no action is taken.

Specified by:

addDiscoveryListener in interface DiscoveryManagement

Parameters:

listener - an instance of DiscoveryListener corresponding to the listener to add to the set of listeners.

Throws:

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

See Also:

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

removeDiscoveryListener

public void removeDiscoveryListener(DiscoveryListener listener)

Removes a listener from the set of objects listening for discovery events. If the listener object input to this method does not exist in the set of listeners, then this method will take no action.

Specified by:

removeDiscoveryListener in interface DiscoveryManagement

Parameters:

listener - an instance of DiscoveryListener corresponding to the listener to remove from the set of listeners.

See Also:

DiscoveryListener, DiscoveryManagement.removeDiscoveryListener(net.jini.discovery.DiscoveryListener), 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

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

See Also:

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

terminate

public void terminate()

Terminates all threads, ending all 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()

getFrom

public int getFrom(ServiceRegistrar proxy)

Return where the proxy came from.

An int restricted to the values 0, 1, 2, and 3. Each value represents a bit (or set of bits) that indicates the mechanism (group discovery, locator discovery, or both) through which the registrar referenced by the current instance of this class (proxy) has currently been (or not been) discovered.

That is, if from
= 0 (no bits set) ==> discovered by neither group nor locator
= 1 (bit 0 set) ==> discovered by only group discovery
= 2 (bit 1 set) ==> discovered by only locator discovery
= 3 (bits 1&2 set) ==> discovered by both group and locator

Parameters:

proxy - a ServiceRegistrar object

Returns:

an int from, indicating whether the proxy was obtained through group or locator discovery.

findReg

private AbstractLookupDiscoveryManager.ProxyReg findReg(ServiceRegistrar proxy)

notifyListener

private void notifyListener(Map<ServiceRegistrar,String[]> groupsMap,
                            int eventType)

Notify all listeners for a discovery event. If a listener's method completes abruptly due to a Throwable, it is logged and processing continues.

Parameters:

groupsMap - mapping from the elements of the registrars of this event to the member groups in which each registrar is a member.

eventType - The type of event.

notifyListener

private void notifyListener(DiscoveryListener l,
                            Map<ServiceRegistrar,String[]> groupsMap,
                            int eventType)

Notify a specific listener for a discovery event. If the listener's method throws a Throwable T, this method will also throw T.

Parameters:

l - The listener to notify.

groupsMap - mapping from the elements of the registrars of this event to the member groups in which each registrar is a member.

eventType - The type of the event.

groupSetsEqual

private static boolean groupSetsEqual(String[] groupSet0,
                                      String[] groupSet1)

Determines if two sets of registrar member groups have identical contents. Assumes there are no duplicates, and the sets can never be null.

Parameters:

groupSet0 - String array containing the group names from the first set used in the comparison

groupSet1 - String array containing the group names from the second set used in the comparison

Returns:

true if the contents of each set is identical; false otherwise

stillInterested

private boolean stillInterested(String[] regGroups,
                                String[] desiredGroups)

Determines if at least one member group of a given registrar is contained in the given set of desired groups.

Parameters:

regGroups - String array containing the member groups of a given registrar (will never be null)

desiredGroups - String array containing the groups to discover (can be null - ALL_GROUPS)

Returns:

true if at least one element of regGroups is contained in desiredGroups; false otherwise

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

beginDiscovery

void beginDiscovery()

Initiates the discovery process for the given set of groups and the given set of locators. Whenever a lookup service is discovered, discarded, or changed, the appropriate notification will be sent to the appropriate listener.