Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.discovery
Class LookupDiscoveryManager

    java.lang.Object
      net.jini.discovery.LookupDiscoveryManager

All Implemented Interfaces:
  DiscoveryGroupManagement, DiscoveryLocatorManagement, DiscoveryManagement

public 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.

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

  Currently, there are no loggers directly supported by this implementation of `LookupDiscoveryManager`. All logging information produced when using this utility is controlled by the loggers supported by the following utilities:

  - `LookupDiscovery`
  - `LookupLocatorDiscovery`

  For information about how to obtain logging information when using this implementation of `LookupDiscoveryManager`, please refer to the documentation provided with the discovery utilities listed above.

Field Summary
`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
`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
`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 come 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`

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 `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.

  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.

  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 come from.

  Parameters:
    `proxy` - a ServiceRegistrar object
  Returns:
    an `int` indicating whether the proxy was obtained through group or locator discovery.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved