LookupDiscovery (Apache River v3.0.0 API Documentation)

java.lang.Object
- net.jini.discovery.LookupDiscovery

All Implemented Interfaces:: DiscoveryGroupManagement, DiscoveryManagement

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

Implementation Specifics:

The following implementation-specific items are discussed below:

Configuring LookupDiscovery
Logging

Configuring LookupDiscovery

This implementation of LookupDiscovery supports the following configuration entries; where each configuration entry name is associated with the component name net.jini.discovery.LookupDiscovery. Note that the configuration entries specified here are specific to this implementation of LookupDiscovery. Unless otherwise stated, each entry is retrieved from the configuration only once per instance of this utility, where each such retrieval is performed in the constructor.

• discoveryConstraints
Type: MethodConstraints
Default: null
Description: Constraints to apply to the multicast request, multicast announcement and unicast discovery protocols. Multicast request constraints are derived by calling getConstraints on the obtained MethodConstraints instance with a Method object for the multicastRequest method; multicast announcement and unicast discovery constraints are similarly obtained by passing Method objects for the multicastAnnouncement and unicastDiscovery methods, respectively. A null value is interpreted as mapping all methods to empty constraints.
This class supports the use of the following constraint types to control discovery behavior:

DiscoveryProtocolVersion: this constraint can be used to control which version(s) of the multicast request, multicast announcement and unicast discovery protocols are used.
MulticastMaxPacketSize: this constraint can be used to control the maximum size of multicast request packets to send; it can also be used to specify the size of the buffer used to receive incoming multicast announcement packets.
MulticastTimeToLive: this constraint can be used to control the time to live (TTL) value set on outgoing multicast request packets.
UnicastSocketTimeout: this constraint can be used to control the read timeout set on sockets over which unicast discovery is performed.
ConnectionRelativeTime: this constraint can be used to control the relative connection timeout set on sockets over which unicast discovery is performed.
ConnectionAbsoluteTime: this constraint can be used to control the absolute connection timeout set on sockets over which unicast discovery is performed.
Constraints other than those listed above are passed on to the underlying implementations of versions 1 and 2 of the discovery protocols.

• finalMulticastRequestInterval
Type: long
Default: 2*60*1000 (2 minutes)
Description: With respect to when this utility is started, as well as when the set of groups to discover is changed, this entry represents the number of milliseconds to wait after sending the n-th multicast request where n is equal to the value of the multicastRequestMax entry of this component.

• initialMulticastRequestDelayRange
Type: long
Default: 0 milliseconds
Description: With respect to when this utility is started, this entry controls how long to wait before sending out the first multicast request. If the value is positive, the first request will be delayed by a random value between 0 and initialMulticastRequestDelayRange milliseconds. Subsequent request intervals are controlled by the multicastRequestInterval entry. Note that this entry only has effect when this utility is initialized. The first multicast request is not delayed if the groups to discover are subsequently changed.

• multicastAnnouncementInterval
Type: long
Default: 2*60*1000 (2 minutes)
Description: A lookup service will send out multicast packets announcing its existence every N milliseconds; for some value of N. The value of this entry controls how often this utility examines the multicast announcements from previously discovered lookup services for liveness.

• multicastInterfaceRetryInterval
Type: int
Default: 5*60*1000 (5 minutes)
Description: With respect to any network interface this utility is configured to use to send and receive multicast packets (see entry multicastInterfaces), if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, this utility will retry the failed interface every multicastInterfaceRetryInterval milliseconds until success is encountered.

• multicastInterfaces
Type: NetworkInterface[]
Default: new NetworkInterface[] {all currently supported interfaces}
Description: Each network interface that is represented by an element in the array corresponding to this configuration item will be used to send and receive multicast packets when this utility is participating in the multicast discovery process. When not set, this utility will use all of the network interfaces in the system. When this entry is set to a zero length array, multicast discovery is effectively disabled. And when set to null, the interface to which the operating system defaults will be used.

• multicastRequestHost
Type: String
Default: InetAddress.getLocalHost().getHostAddress()
Description: This entry specifies the host name to include in multicast requests if participating in version 2 of the multicast request protocol. The name cannot be null.

• multicastRequestInterval
Type: long
Default: 5000
Description: With respect to when this utility is started, as well as when the set of groups to discover is changed, this entry represents the number of milliseconds to wait after sending the n-th multicast request, and before sending the (n+1)-st request, where n is less than the value of the multicastRequestMax entry of this component.

• multicastRequestMax
Type: int
Default: 7
Description: The maximum number multicast requests to send when this utility is started for the first time, and whenever the groups to discover is changed.

• registrarPreparer
Type: ProxyPreparer
Default: new BasicProxyPreparer()
Description: Preparer for the proxies to the lookup services that are discovered and used by this utility.
This preparer should perform all operations required to use a newly received proxy to a lookup service, which may including verifying trust in the proxy, granting permissions, and setting constraints.
The following methods of the ServiceRegistrar returned by this preparer are invoked by this implementation of LookupDiscovery:

getServiceID
getGroups
getLocator

• executorService
Type: ExecutorService
Default: new ThreadPoolExecutor( 15, 15, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("LookupDiscovery",false))
Description: The object that pools and manages the various threads executed by this utility. This object should not be shared with other components in the application that employs this utility.

• unicastDelayRange
Type: long
Default: 0 milliseconds
Description: Controls how long this utility will wait before sending out unicast discovery requests. If the value is positive, any unicast discovery request that it initiates will be delayed by a random value between 0 and unicastDelayRange milliseconds. A typical use of this entry would be to achieve a more uniform distribution of unicast discovery requests to a lookup service, when a large number of LookupDiscovery instances simultaneously receive multicast announcements from the lookup service.

• wakeupManager
Type: WakeupManager
Default: new WakeupManager(new WakeupManager.ThreadDesc(null,true))
Description: Object used to schedule unicast discovery requests that are delayed using the unicastDelayRange configuration entry of this utility. This entry is processed only if unicastDelayRange has a positive value.

•	`discoveryConstraints`
	Type:	`MethodConstraints`
	Default:	`null`
	Description:	Constraints to apply to the multicast request, multicast announcement and unicast discovery protocols. Multicast request constraints are derived by calling `getConstraints` on the obtained `MethodConstraints` instance with a `Method` object for the `multicastRequest` method; multicast announcement and unicast discovery constraints are similarly obtained by passing `Method` objects for the `multicastAnnouncement` and `unicastDiscovery` methods, respectively. A `null` value is interpreted as mapping all methods to empty constraints. This class supports the use of the following constraint types to control discovery behavior: `DiscoveryProtocolVersion`: this constraint can be used to control which version(s) of the multicast request, multicast announcement and unicast discovery protocols are used. `MulticastMaxPacketSize`: this constraint can be used to control the maximum size of multicast request packets to send; it can also be used to specify the size of the buffer used to receive incoming multicast announcement packets. `MulticastTimeToLive`: this constraint can be used to control the time to live (TTL) value set on outgoing multicast request packets. `UnicastSocketTimeout`: this constraint can be used to control the read timeout set on sockets over which unicast discovery is performed. `ConnectionRelativeTime`: this constraint can be used to control the relative connection timeout set on sockets over which unicast discovery is performed. `ConnectionAbsoluteTime`: this constraint can be used to control the absolute connection timeout set on sockets over which unicast discovery is performed. Constraints other than those listed above are passed on to the underlying implementations of versions 1 and 2 of the discovery protocols.

•	`finalMulticastRequestInterval`
	Type:	`long`
	Default:	`2601000 (2 minutes)`
	Description:	With respect to when this utility is started, as well as when the set of groups to discover is changed, this entry represents the number of milliseconds to wait after sending the n-th multicast request where n is equal to the value of the `multicastRequestMax` entry of this component.

•	`initialMulticastRequestDelayRange`
	Type:	`long`
	Default:	`0 milliseconds`
	Description:	With respect to when this utility is started, this entry controls how long to wait before sending out the first multicast request. If the value is positive, the first request will be delayed by a random value between `0` and `initialMulticastRequestDelayRange` milliseconds. Subsequent request intervals are controlled by the `multicastRequestInterval` entry. Note that this entry only has effect when this utility is initialized. The first multicast request is not delayed if the groups to discover are subsequently changed.

•	`multicastAnnouncementInterval`
	Type:	`long`
	Default:	`2601000 (2 minutes)`
	Description:	A lookup service will send out multicast packets announcing its existence every N milliseconds; for some value of N. The value of this entry controls how often this utility examines the multicast announcements from previously discovered lookup services for liveness.

•	`multicastInterfaceRetryInterval`
	Type:	`int`
	Default:	`5601000 (5 minutes)`
	Description:	With respect to any network interface this utility is configured to use to send and receive multicast packets (see entry `multicastInterfaces`), if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, this utility will retry the failed interface every `multicastInterfaceRetryInterval` milliseconds until success is encountered.

•	`multicastInterfaces`
	Type:	`NetworkInterface[]`
	Default:	`new` `NetworkInterface[]` `{all currently supported interfaces}`
	Description:	Each network interface that is represented by an element in the array corresponding to this configuration item will be used to send and receive multicast packets when this utility is participating in the multicast discovery process. When not set, this utility will use all of the network interfaces in the system. When this entry is set to a zero length array, multicast discovery is effectively *disabled*. And when set to `null`, the interface to which the operating system defaults will be used.

•	`multicastRequestHost`
	Type:	`String`
	Default:	`InetAddress.getLocalHost().getHostAddress()`
	Description:	This entry specifies the host name to include in multicast requests if participating in *version 2* of the multicast request protocol. The name cannot be `null`.

•	`multicastRequestInterval`
	Type:	`long`
	Default:	`5000`
	Description:	With respect to when this utility is started, as well as when the set of groups to discover is changed, this entry represents the number of milliseconds to wait after sending the n-th multicast request, and before sending the (n+1)-st request, where n is less than the value of the `multicastRequestMax` entry of this component.

•	`multicastRequestMax`
	Type:	`int`
	Default:	`7`
	Description:	The maximum number multicast requests to send when this utility is started for the first time, and whenever the groups to discover is changed.

•	`registrarPreparer`
	Type:	`ProxyPreparer`
	Default:	`new BasicProxyPreparer()`
	Description:	Preparer for the proxies to the lookup services that are discovered and used by this utility. This preparer should perform all operations required to use a newly received proxy to a lookup service, which may including verifying trust in the proxy, granting permissions, and setting constraints. The following methods of the `ServiceRegistrar` returned by this preparer are invoked by this implementation of `LookupDiscovery`: `getServiceID` `getGroups` `getLocator`

•	`executorService`
	Type:	`ExecutorService`
	Default:	`new ThreadPoolExecutor( 15, 15, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("LookupDiscovery",false))`
	Description:	The object that pools and manages the various threads executed by this utility. This object should not be shared with other components in the application that employs this utility.

•	`unicastDelayRange`
	Type:	`long`
	Default:	`0 milliseconds`
	Description:	Controls how long this utility will wait before sending out unicast discovery requests. If the value is positive, any unicast discovery request that it initiates will be delayed by a random value between `0` and `unicastDelayRange` milliseconds. A typical use of this entry would be to achieve a more uniform distribution of unicast discovery requests to a lookup service, when a large number of `LookupDiscovery` instances simultaneously receive multicast announcements from the lookup service.

•	`wakeupManager`
	Type:	`WakeupManager`
	Default:	`new WakeupManager(new WakeupManager.ThreadDesc(null,true))`
	Description:	Object used to schedule unicast discovery requests that are delayed using the `unicastDelayRange` configuration entry of this utility. This entry is processed only if `unicastDelayRange` has a positive value.

Logging

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

net.jini.discovery.LookupDiscovery
Level Description

SEVERE when this utility is configured to use either the default network interface assigned by the system, or a specific list of network interfaces, if one of those interfaces is bad or not configured for multicast, or if a runtime exception occurs while either sending multicast requests, or while configuring one of the interfaces to receive multicast announcements, that fact will be logged at this level

INFO when any exception other than an InterruptedIOException, InterruptedException or UnsupportedConstraintException occurs in a thread or task while attempting to marshal an outgoing multicast request

INFO when any exception other than an InterruptedIOException or SocketTimeoutException occurs in a non-interrupted thread while attempting to receive an incoming multicast packet

INFO when any exception other than an InterruptedIOException occurs while attempting unicast discovery

INFO when this utility is configured to use either the default network interface assigned by the system, or a specific list of network interfaces, with respect to any such interface, if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, the interface will be periodically retried, and successful recovery will be logged at this level

INFO when any exception occurs while attempting to prepare a proxy

CONFIG when the multicastInterfaces entry is configured to be null, multicast packets will be sent and received through the default network interface assigned by the system, and that fact will be logged at this level

CONFIG when the multicastInterfaces entry is configured to be a zero length array, multicast discovery will be disabled, and and that fact will be logged at this level

CONFIG when the multicastInterfaces entry contains a specific list of network interfaces, multicast packets will be sent and received through only the network interfaces contained in that list, and those interfaces will be logged at this level

CONFIG when the multicastInterfaces entry is excluded from the configuration, multicast packets will be sent and received through all interfaces in the system, and those interfaces will be logged at this level

FAILED when an UnknownHostException occurs while determining the multicastRequestHost, but the caller does not have permissions to retrieve the local host name. The original UnknownHostException with the host name information is logged
HANDLED when this utility is configured to use all network interfaces enabled in the system, if one of those interfaces is bad or not configured for multicast, or if a runtime exception occurs while either sending multicast requests, or while configuring one of the interfaces to receive multicast announcements, that fact will be logged at this level

HANDLED when any exception occurs while attempting to unmarshal an incoming multicast announcement

HANDLED when an UnsupportedConstraintException occurs while marshalling an outgoing multicast request, indicating that the provider that threw the exception will not be used for encoding that request

HANDLED when an IOException occurs upon attempting to close the socket after the thread that listens for multicast responses is asked to terminate

HANDLED when an exception is handled during unicast discovery

FINE when this utility is configured to use all network interfaces enabled in the system, with respect to any such interface, if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, the interface will be periodically retried, and successful recovery will be logged at this level

FINEST whenever any thread or task is started

FINEST whenever any thread (except the Notifier thread) or task completes successfully

FINEST whenever a discovered, discarded, or changed event is sent

FINEST whenever a proxy is prepared

**`net.jini.discovery.LookupDiscovery`**
Level	Description
`SEVERE`	when this utility is configured to use either the default network interface assigned by the system, or a specific list of network interfaces, if one of those interfaces is bad or not configured for multicast, or if a runtime exception occurs while either sending multicast requests, or while configuring one of the interfaces to receive multicast announcements, that fact will be logged at this level
`INFO`	when any exception other than an `InterruptedIOException`, `InterruptedException` or `UnsupportedConstraintException` occurs in a thread or task while attempting to marshal an outgoing multicast request
`INFO`	when any exception other than an `InterruptedIOException` or `SocketTimeoutException` occurs in a non-interrupted thread while attempting to receive an incoming multicast packet
`INFO`	when any exception other than an `InterruptedIOException` occurs while attempting unicast discovery
`INFO`	when this utility is configured to use either the default network interface assigned by the system, or a specific list of network interfaces, with respect to any such interface, if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, the interface will be periodically retried, and successful recovery will be logged at this level
`INFO`	when any exception occurs while attempting to prepare a proxy
`CONFIG`	when the `multicastInterfaces` entry is configured to be `null`, multicast packets will be sent and received through the default network interface assigned by the system, and that fact will be logged at this level
`CONFIG`	when the `multicastInterfaces` entry is configured to be a zero length array, multicast discovery will be disabled, and and that fact will be logged at this level
`CONFIG`	when the `multicastInterfaces` entry contains a specific list of network interfaces, multicast packets will be sent and received through only the network interfaces contained in that list, and those interfaces will be logged at this level
`CONFIG`	when the `multicastInterfaces` entry is excluded from the configuration, multicast packets will be sent and received through all interfaces in the system, and those interfaces will be logged at this level
`FAILED`	when an `UnknownHostException` occurs while determining the `multicastRequestHost`, but the caller does not have permissions to retrieve the local host name. The original `UnknownHostException` with the host name information is logged
`HANDLED`	when this utility is configured to use all network interfaces enabled in the system, if one of those interfaces is bad or not configured for multicast, or if a runtime exception occurs while either sending multicast requests, or while configuring one of the interfaces to receive multicast announcements, that fact will be logged at this level
`HANDLED`	when any exception occurs while attempting to unmarshal an incoming multicast announcement
`HANDLED`	when an `UnsupportedConstraintException` occurs while marshalling an outgoing multicast request, indicating that the provider that threw the exception will not be used for encoding that request
`HANDLED`	when an `IOException` occurs upon attempting to close the socket after the thread that listens for multicast responses is asked to terminate
`HANDLED`	when an exception is handled during unicast discovery
`FINE`	when this utility is configured to use all network interfaces enabled in the system, with respect to any such interface, if failure is encountered upon the initial attempt to set the interface or join the desired multicast group, the interface will be periodically retried, and successful recovery will be logged at this level
`FINEST`	whenever any thread or task is started
`FINEST`	whenever any thread (except the `Notifier` thread) or task completes successfully
`FINEST`	whenever a discovered, discarded, or changed event is sent
`FINEST`	whenever a proxy is prepared

Field Summary
- Fields inherited from interface net.jini.discovery.DiscoveryGroupManagement
  ALL_GROUPS, NO_GROUPS

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

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

- 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:
    
    DiscoveryGroupManagement.NO_GROUPS, DiscoveryGroupManagement.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:
    
    DiscoveryGroupManagement.NO_GROUPS, DiscoveryGroupManagement.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:
    
    DiscoveryGroupManagement.NO_GROUPS, DiscoveryGroupManagement.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, DiscoveryGroupManagement.ALL_GROUPS, DiscoveryGroupManagement.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[])

Class LookupDiscovery

Field Summary

Fields inherited from interface net.jini.discovery.DiscoveryGroupManagement

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface net.jini.discovery.DiscoveryManagement

Methods inherited from interface net.jini.discovery.DiscoveryGroupManagement

Constructor Detail

LookupDiscovery

LookupDiscovery

Method Detail

addDiscoveryListener

removeDiscoveryListener

getRegistrars

discard

terminate

getGroups

addGroups

setGroups

removeGroups