GigaSpaces XAP 9.5 API

net.jini.discovery
Class LookupDiscovery

java.lang.Object
  extended by net.jini.discovery.LookupDiscovery
All Implemented Interfaces:
DiscoveryGroupManagement, DiscoveryManagement

public class LookupDiscovery
extends Object
implements DiscoveryManagement, DiscoveryGroupManagement

This class is a helper utility class that encapsulates the functionality required of an entity that wishes to employ multicast discovery to find lookup services located within the entity's "multicast radius" (roughly, the number of hops beyond which neither the multicast requests from the entity, nor the multicast announcements from the lookup service, will propagate). This class helps make the process of acquiring references to lookup services - based on no information other than lookup service group membership - much simpler for both services and clients.

Author:
Sun Microsystems, Inc.
See Also:
ServiceRegistrar, DiscoveryChangeListener, DiscoveryManagement, DiscoveryGroupManagement, DiscoveryListener, DiscoveryEvent, DiscoveryPermission

Field Summary
static String[] ALL_GROUPS
          Convenience constant used to request that attempts be made to discover all lookup services that are within range, and which belong to any group.
static String[] NO_GROUPS
          Convenience constant used to request that discovery by group membership be halted (or not started, if the group discovery mechanism is simply being instantiated).
 
Constructor Summary
LookupDiscovery(String[] groups)
          Construct a new lookup discovery object, set to discover the given set of groups.
LookupDiscovery(String[] groups, Configuration config)
          Constructs a new lookup discovery object, set to discover the given set of groups, and having the given Configuration.
 
Method Summary
 void addDiscoveryListener(DiscoveryListener l)
          Register a listener as interested in receiving DiscoveryEvent notifications.
 void addGroups(String[] newGroups)
          Add a set of groups to the set to be discovered.
 void discard(ServiceRegistrar reg)
          Discard a registrar from the set of registrars already discovered.
 String[] getGroups()
          Return the set of group names this LookupDiscovery instance is trying 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 l)
          Indicate that a listener is no longer interested in receiving DiscoveryEvent notifications.
 void removeGroups(String[] oldGroups)
          Remove a set of groups from the set to be discovered.
 void setGroups(String[] newGroups)
          Change the set of groups to be discovered to correspond to the given set.
 void terminate()
          Terminate the discovery process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALL_GROUPS

public static final String[] ALL_GROUPS
Convenience constant used to request that attempts be made to discover all lookup services that are within range, and which belong to any group. Must define this constant here as well as in DiscoveryGroupManagement for compatibility with earlier releases.


NO_GROUPS

public static final String[] NO_GROUPS
Convenience constant used to request that discovery by group membership be halted (or not started, if the group discovery mechanism is simply being instantiated). Must define this constant here as well as in DiscoveryGroupManagement for compatibility with earlier releases.

Constructor Detail

LookupDiscovery

public LookupDiscovery(String[] groups)
                throws IOException
Construct a new lookup discovery object, set to discover the given set of groups. The set is represented as an array of strings. This array may be empty, which is taken as the empty set, and discovery is not performed. The reference passed in may be null, which is taken as no set, and in which case discovery of all reachable lookup services is performed. Otherwise, the array contains the names of groups to discover. The caller must have DiscoveryPermission for each group (or for all groups, if the array is null).

Parameters:
groups - the set of group names to discover (null for no set, empty for no discovery)
Throws:
NullPointerException - input array contains at least one null element
IOException - an exception occurred in starting discovery
See Also:
NO_GROUPS, ALL_GROUPS, setGroups(java.lang.String[]), DiscoveryPermission

LookupDiscovery

public LookupDiscovery(String[] groups,
                       Configuration config)
                throws IOException,
                       ConfigurationException
Constructs a new lookup discovery object, set to discover the given set of groups, and having the given Configuration.

The set of groups to discover is represented as an array of strings. This array may be empty, which is taken as the empty set, and discovery is not performed. The reference passed in may be null, which is taken as no set, and in which case discovery of all reachable lookup services is performed. Otherwise, the array contains the names of groups to discover. The caller must have DiscoveryPermission for each group (or for all groups, if the array is null).

Parameters:
groups - the set of group names to discover (null for no set, empty for no discovery)
config - an instance of Configuration, used to obtain the objects needed to configure the current instance of this class
Throws:
NullPointerException - input array contains at least one null element or null is input for the configuration
IOException - an exception occurred in starting discovery
ConfigurationException - indicates an exception occurred while retrieving an item from the given Configuration
See Also:
NO_GROUPS, ALL_GROUPS, setGroups(java.lang.String[]), DiscoveryPermission, Configuration, ConfigurationException
Method Detail

addDiscoveryListener

public void addDiscoveryListener(DiscoveryListener l)
Register a listener as interested in receiving DiscoveryEvent notifications.

Specified by:
addDiscoveryListener in interface DiscoveryManagement
Parameters:
l - the listener to register
Throws:
NullPointerException - this exception occurs when null is input to the listener parameter l.
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
DiscoveryEvent, removeDiscoveryListener(net.jini.discovery.DiscoveryListener)

removeDiscoveryListener

public void removeDiscoveryListener(DiscoveryListener l)
Indicate that a listener is no longer interested in receiving DiscoveryEvent notifications.

Specified by:
removeDiscoveryListener in interface DiscoveryManagement
Parameters:
l - the listener to unregister
Throws:
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
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
Throws:
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
ServiceRegistrar, DiscoveryManagement.removeDiscoveryListener(net.jini.discovery.DiscoveryListener)

discard

public void discard(ServiceRegistrar reg)
Discard a registrar from the set of registrars already discovered. This does not prevent that registrar from being rediscovered; it is intended to be used to clear unreachable entries from the set.

If the registrar has been discovered using this LookupDiscovery object, each listener registered with this object will have its discarded method called with the given registrar as parameter.

Specified by:
discard in interface DiscoveryManagement
Parameters:
reg - the registrar to discard
Throws:
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
DiscoveryListener.discarded(net.jini.discovery.DiscoveryEvent)

terminate

public void terminate()
Terminate the discovery process.

Specified by:
terminate in interface DiscoveryManagement

getGroups

public String[] getGroups()
Return the set of group names this LookupDiscovery instance is trying to discover. If this method returns the empty array, that value is guaranteed to be referentially equal to LookupDiscovery.NO_GROUPS.

Specified by:
getGroups in interface DiscoveryGroupManagement
Returns:
the set of groups to be discovered (null for all, empty for no discovery)
Throws:
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
NO_GROUPS, ALL_GROUPS, setGroups(java.lang.String[])

addGroups

public void addGroups(String[] newGroups)
               throws IOException
Add a set of groups to the set to be discovered. The caller must have DiscoveryPermission for each group.

Specified by:
addGroups in interface DiscoveryGroupManagement
Parameters:
newGroups - the groups to add
Throws:
IOException - the multicast request protocol failed to start
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
UnsupportedOperationException - there is no set of groups to add to
See Also:
DiscoveryPermission

setGroups

public void setGroups(String[] newGroups)
               throws IOException
Change the set of groups to be discovered to correspond to the given set. The set is represented as an array of strings. This array may be empty, which is taken as the empty set, and discovery is not performed. The reference passed in may be null, which is taken as no set, and in which case discovery of all reachable lookup services is performed. Otherwise, the array contains the names of groups to discover. The caller must have DiscoveryPermission for each group (or for all groups, if the array is null).

Specified by:
setGroups in interface DiscoveryGroupManagement
Parameters:
newGroups - the new set of groups to discover (null for all, empty array for no discovery)
Throws:
IOException - an exception occurred when starting multicast discovery
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
See Also:
LookupDiscovery(java.lang.String[], net.jini.config.Configuration), ALL_GROUPS, NO_GROUPS, DiscoveryPermission, getGroups()

removeGroups

public void removeGroups(String[] oldGroups)
Remove a set of groups from the set to be discovered.

Specified by:
removeGroups in interface DiscoveryGroupManagement
Parameters:
oldGroups - groups to remove
Throws:
IllegalStateException - this exception occurs when this method is called after the terminate method has been called.
UnsupportedOperationException - there is no set of groups from which to remove
See Also:
DiscoveryGroupManagement.addGroups(java.lang.String[])

GigaSpaces XAP 9.5 API

Copyright © GigaSpaces.