Package net.jini.discovery

Class LookupDiscoveryManager

java.lang.Object
net.jini.discovery.LookupDiscoveryManager
All Implemented Interfaces:
DiscoveryGroupManagement, DiscoveryLocatorManagement, DiscoveryManagement
Direct Known Subclasses:
SharedDiscoveryManagement.SharedDiscoveryManager
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.

Author:
Sun Microsystems, Inc.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FROM_GROUP
    Constant that indicates the discovery mechanism is group discovery
    static final int
    FROM_LOCATOR
    Constant that indicates the discovery mechanism is locator discovery

  • Constructor Summary

    Constructors
    Constructor
    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.
    LookupDiscoveryManager(String[] groups, LookupLocator[] locators, DiscoveryListener listener, Configuration config, boolean runningWithinRegistrar)
     

  • Method Summary

    Modifier and Type
    Method
    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.
    DynamicLookupLocatorDiscovery
    getDynamicLocatorDiscovery()
     
    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 Details

    • FROM_GROUP

      public static final int FROM_GROUP
      Constant that indicates the discovery mechanism is group discovery
      See Also:

    • FROM_LOCATOR

      public static final int FROM_LOCATOR
      Constant that indicates the discovery mechanism is locator discovery
      See Also:

  • Constructor Details

    • 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:

    • 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:

    • LookupDiscoveryManager

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

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

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

    • getDynamicLocatorDiscovery

      public DynamicLookupLocatorDiscovery getDynamicLocatorDiscovery()