net.jini.discovery

Class LookupDiscoveryManager

java.lang.Object

net.jini.discovery.LookupDiscoveryManager

All Implemented Interfaces:

DiscoveryGroupManagement, DiscoveryLocatorManagement, DiscoveryManagement

public final class LookupDiscoveryManager
extends Object
implements DiscoveryManagement, DiscoveryGroupManagement, DiscoveryLocatorManagement

This class is a helper utility class that organizes and manages all discovery-related activities on behalf of a client or service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to group names, LookupLocator objects, and DiscoveryListener objects, clients and services can employ this class to provide those facilities on their behalf.

Author:

Sun Microsystems, Inc.

See Also:

DiscoveryManagement, DiscoveryGroupManagement, DiscoveryLocatorManagement

Implementation Specifics:

The following implementation-specific items are discussed below:

• Configuring LookupDiscoveryManager
• Logging

Configuring LookupDiscoveryManager

Currently, there are no configuration entries directly supported by this implementation of LookupDiscoveryManager. All configuration entries affecting the operation of this utility are retrieved by either the LookupDiscovery utility, or the LookupLocatorDiscovery utility. Please refer to the documentation provided with those utilities when configuring the behavior of LookupDiscoveryManager.

Logging

With one exception, all logging information produced when using this utility is controlled by the loggers supported by the following utilities:

• LookupDiscovery
• LookupLocatorDiscovery

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

net.jini.discovery.LookupDiscoveryManager

Level	Description
HANDLED	when this utility asynchronously invokes a DiscoveryListener implementation and that listener throws and unchecked exception. If the listener throws in a synchronous path (namely, via addDiscoveryListener(DiscoveryListener)) then the exception is not trapped and will instead throw back to the caller.

Field Summary

Fields

Modifier and Type	Field and Description
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

Fields inherited from interface net.jini.discovery.DiscoveryGroupManagement

ALL_GROUPS, NO_GROUPS

Constructor Summary

Constructors

Constructor and Description
LookupDiscoveryManager(String[] groups, LookupLocator[] locators, DiscoveryListener listener) Constructs an instance of this class that will organize and manage all discovery-related activities on behalf of the client or service that instantiates this class.
LookupDiscoveryManager(String[] groups, LookupLocator[] locators, DiscoveryListener listener, Configuration config) Constructs an instance of this class, using the given Configuration, that will organize and manage all discovery-related activities on behalf of the client or service that instantiates 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.
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.
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.
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.
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

Methods inherited from interface net.jini.discovery.DiscoveryManagement

addDiscoveryListener, discard, getRegistrars, removeDiscoveryListener, terminate

Methods inherited from interface net.jini.discovery.DiscoveryGroupManagement

addGroups, getGroups, removeGroups, setGroups

Methods inherited from interface net.jini.discovery.DiscoveryLocatorManagement

addLocators, getLocators, removeLocators, setLocators

Field Detail

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

Constructor Detail

LookupDiscoveryManager

public LookupDiscoveryManager(String[] groups,
                              LookupLocator[] locators,
                              DiscoveryListener listener)
                       throws IOException

Constructs an instance of this class that will organize and manage all discovery-related activities on behalf of the client or service that instantiates this class.

If null (DiscoveryGroupManagement.ALL_GROUPS) is input to the groups parameter, then attempts will be made via group discovery to discover all lookup services located within range of the entity that constructs this class. If the empty array (DiscoveryGroupManagement.NO_GROUPS) is input to that parameter, no group discovery will be performed until the set of groups to discover is populated.

If an empty array or a null reference is input to the locators parameter, no locator discovery will be performed until the set of locators to discover is populated.

Parameters:

groups - String array, none of whose elements may be null, consisting of the names of the groups whose members are lookup services the client or service wishes to discover.

locators - array of instances of LookupLocator, none of whose elements may be null, and in which each element corresponds to a specific lookup service the client or service wishes to discover via locator discovery.

listener - a reference to DiscoveryListener object that will be notified when a targeted lookup service is discovered or discarded.

Throws:

IOException - because construction of this class may initiate the discovery process, which can throw an IOException when socket allocation occurs.

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

See Also:

LookupLocator, DiscoveryListener

LookupDiscoveryManager

public LookupDiscoveryManager(String[] groups,
                              LookupLocator[] locators,
                              DiscoveryListener listener,
                              Configuration config)
                       throws IOException,
                              ConfigurationException

Constructs an instance of this class, using the given Configuration, that will organize and manage all discovery-related activities on behalf of the client or service that instantiates this class.

If null (DiscoveryGroupManagement.ALL_GROUPS) is input to the groups parameter, then attempts will be made via group discovery to discover all lookup services located within range of the entity that constructs this class. If the empty array (DiscoveryGroupManagement.NO_GROUPS) is input to that parameter, no group discovery will be performed until the set of groups to discover is populated.

If an empty array or a null reference is input to the locators parameter, no locator discovery will be performed until the set of locators to discover is populated.

Parameters:

groups - String array, none of whose elements may be null, consisting of the names of the groups whose members are lookup services the client or service wishes to discover.

locators - array of instances of LookupLocator, none of whose elements may be null, and in which each element corresponds to a specific lookup service the client or service wishes to discover via locator discovery.

listener - a reference to DiscoveryListener object that will be notified when a targeted lookup service is discovered or discarded.

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

Throws:

IOException - because construction of this class may initiate the discovery process, which can throw an IOException when socket allocation occurs.

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

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

See Also:

LookupLocator, DiscoveryListener, Configuration

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.