AbstractLookupDiscovery (Apache River v3.0.0 API Documentation (internals))

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

All Implemented Interfaces:

DiscoveryGroupManagement, DiscoveryManagement

Direct Known Subclasses:

LookupDiscovery
```
abstract class AbstractLookupDiscovery
extends Object
implements DiscoveryManagement, DiscoveryGroupManagement
```
This package private superclass of LocatorDiscovery exists for safe construction of LocatorDiscovery's state, while retaining backward compatibility of the API. See www.securecoding.cert.org TSM01-J and OBJ11-J

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`AbstractLookupDiscovery.AnnouncementInfo` Holder class for the time and sequence number of the last received announcement.
`private class`	`AbstractLookupDiscovery.AnnouncementListener` Thread that listens for multicast announcements from lookup services.
`private class`	`AbstractLookupDiscovery.AnnouncementTimerThread` This thread monitors the multicast announcements sent from the lookup service(s) that have already been discovered by this class, looking for indications that those announcements have terminated.
`private static class`	`AbstractLookupDiscovery.CheckGroupsMarker` Marker object placed in pendingDiscoveries set to indicate to UnicastDiscoveryTask that the groups of the lookup service which sent the contained announcement need to be verified.
`private static class`	`AbstractLookupDiscovery.CheckReachabilityMarker` Marker object placed in pendingDiscoveries set to indicate to UnicastDiscoveryTask that reachability of the lookup service which sent the contained unicast response needs to be verified.
`private class`	`AbstractLookupDiscovery.DecodeAnnouncementTask` Task which decodes received multicast announcement packets.
`private static class`	`AbstractLookupDiscovery.Initializer`
`private class`	`AbstractLookupDiscovery.Notifier` Thread that retrieves data structures of type NotifyTask from a queue and, based on the contents of the data structure, sends the appropriate event (discovered/discarded/changed) to each registered listener.
`private static class`	`AbstractLookupDiscovery.NotifyTask` Data structure containing task data processed by the Notifier Thread
`private class`	`AbstractLookupDiscovery.Requestor` Thread that periodically sends out multicast requests for a limited period of time, and then exits.
`private class`	`AbstractLookupDiscovery.ResponseListener` Thread that listens for multicast responses to the multicast requests sent out by the Requestor Thread class.
`private class`	`AbstractLookupDiscovery.UnicastDiscoveryTask` Task which retrieves elements from the set of pendingDiscoveries and performs the appropriate processing based on the object type of the element.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`all_groups` If groups passed to constructor are null -- ALL_GROUPS, writes synchronised on registrars
`private AbstractLookupDiscovery.AnnouncementListener`	`announceeThread` Thread that handles incoming multicast announcements.
`private AbstractLookupDiscovery.AnnouncementTimerThread`	`announcementTimerThread` Thread that monitors multicast announcements from already-discovered lookup services and, upon determining that those announcements have stopped, queues a reachability test with the UnicastDiscoveryTask which will ultimately result in the lookup service being discarded if the reachability test indicates that the lookup service is actually down.
`private static int`	`CHANGED`
`private static String`	`COMPONENT_NAME`
`private static int`	`DEFAULT_MAX_PACKET_SIZE` Default maximum size of multicast packets to send and receive.
`private static int`	`DEFAULT_MULTICAST_TTL` Default time to live value to use for sending multicast packets.
`private static int`	`DEFAULT_SOCKET_TIMEOUT` Default timeout to set on sockets used for unicast discovery.
`private static int`	`DISCARDED`
`private static int`	`DISCOVERED` Constants used to tell the notifierThread the type of event to send
`private WakeupManager`	`discoveryWakeupMgr`
`private java.util.concurrent.ExecutorService`	`executor` ExecutorService for running UnicastDiscoveryTasks and DecodeAnnouncementTasks.
`private long`	`finalMulticastRequestInterval`
`private Set<String>`	`groups` The groups to discover.
`private long`	`initialMulticastRequestDelayRange`
`private boolean`	`initialRequestorStarted`
`private boolean`	`isDefaultWakeupMgr`
`private List<DiscoveryListener>`	`listeners` Set of listeners to be sent discovered/discarded/changed events.
`private static Logger`	`logger`
`private static int`	`MAX_N_TASKS` Maximum number of concurrent tasks that can be run in any executor created by this class.
`private DiscoveryConstraints`	`multicastAnnouncementConstraints`
`private long`	`multicastAnnouncementInterval`
`private DiscoveryConstraints`	`multicastRequestConstraints`
`private String`	`multicastRequestHost`
`private long`	`multicastRequestInterval`
`private int`	`multicastRequestMax`
`private int`	`nicRetryInterval`
`private NetworkInterface[]`	`nics`
`private static int`	`NICS_USE_ALL` Constants used to indicate the set of network interfaces being used
`private static int`	`NICS_USE_LIST`
`private static int`	`NICS_USE_NONE`
`private static int`	`NICS_USE_SYS`
`private int`	`nicsToUse` Flag that indicates how the set of network interfaces was configured
`private AbstractLookupDiscovery.Notifier`	`notifierThread` Thread that handles pending notifications.
`private Set`	`pendingDiscoveries` Set that takes one of the following: Socket (discovery from multicast request/response exchange) LookupLocator (discovery from multicast announcement) CheckGroupsMarker (discarded/changed from announcement) CheckReachabilityMarker (announcements stopped, tests reachability) Each element of this set represents a potential (or pending) discovered, discarded, or changed event.
`private java.util.concurrent.BlockingDeque<AbstractLookupDiscovery.NotifyTask>`	`pendingNotifies` Notifications to be sent to listeners.
`private Discovery`	`protocol2`
`private InvocationConstraints`	`rawUnicastDiscoveryConstraints`
`private java.util.concurrent.ConcurrentMap<ServiceID,AbstractLookupDiscovery.AnnouncementInfo>`	`regInfo` Map from ServiceID to multicast announcement time stamps; used by the process that monitors multicast announcements from already-discovered lookup services, and determines when those announcements have stopped.
`private ProxyPreparer`	`registrarPreparer`
`private Map<ServiceID,UnicastResponse>`	`registrars` Map from ServiceID to UnicastResponse.
`private Collection<Thread>`	`requestors` Collection that contains instances of the Requestor Thread class, each of which participate in multicast discovery by periodically sending out multicast discovery requests for a finite period of time.
`private AbstractLookupDiscovery.ResponseListener`	`respondeeThread` Thread that manages incoming multicast responses.
`private SecurityContext`	`securityContext` Security context that contains the access control context to restore for callbacks, etc.
`private boolean`	`started`
`private boolean`	`terminated` Flag indicating whether or not this class is still functional.
`private Exception`	`thrown`
`private List<WakeupManager.Ticket>`	`tickets`
`private long`	`unicastDelayRange`

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

Constructor Summary

Constructors
Modifier	Constructor and Description
`(package private)`	`AbstractLookupDiscovery(String[] groups)` Construct a new lookup discovery object, set to discover the given set of groups.
`private`	`AbstractLookupDiscovery(String[] groups, AbstractLookupDiscovery.Initializer init)`
`(package private)`	`AbstractLookupDiscovery(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 Static 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.
`private void`	`addNotify(List<DiscoveryListener> notifies, Map<ServiceRegistrar,String[]> groupsMap, int eventType)` Add a notification task to the pending queue, and wake up the Notifier.
`private void`	`checkAnnouncementConstraints(MulticastAnnouncement ann)`
`private static void`	`checkGroups(String[] groups)` Determines if the caller has discovery permission for each group.
`private static String[]`	`collectionToStrings(Collection c)` Converts a collection to an array of strings.
`private MulticastAnnouncement`	`decodeMulticastAnnouncement(DatagramPacket pkt)` Decodes received multicast announcement packet.
`private Map<ServiceRegistrar,String[]>`	`deepCopy(Map<ServiceRegistrar,String[]> groupsMap)` Creates and returns a deep copy of the input parameter.
`void`	`discard(ServiceRegistrar reg)` Discard a registrar from the set of registrars already discovered.
`private UnicastResponse`	`doUnicastDiscovery(Socket socket, DiscoveryConstraints unicastDiscoveryConstraints)`
`private UnicastResponse`	`doUnicastDiscovery(Socket socket, DiscoveryConstraints unicastDiscoveryConstraints, Discovery disco)` Performs unicast discovery over given socket based on protocol in use, applying configured security constraints (if any).
`private DatagramPacket[]`	`encodeMulticastRequest(MulticastRequest req)` Encodes outgoing multicast requests based on protocol in use, applying configured security constraints (if any).
`private String[]`	`getActualGroups(ServiceRegistrar reg)` This method retrieves from the given `ServiceRegistrar`, the current groups in which that registrar is a member.
`private Discovery`	`getDiscovery(int version)` Returns Discovery instance for the given version, or throws DiscoveryProtocolException if the version is unsupported.
`String[]`	`getGroups()` Return the set of group names this LookupDiscovery instance is trying to discover.
`private static String`	`getLocalHost()` Returns the local host name.
`ServiceRegistrar[]`	`getRegistrars()` Returns an array of instances of `ServiceRegistrar`, each corresponding to a proxy to one of the currently discovered lookup services.
`private ServiceID[]`	`getServiceIDs()` Returns the service IDs of the lookup service(s) discovered to date.
`private static boolean`	`groupSetsEqual(String[] groupSet0, String[] groupSet1)` Determines if two sets of registrar member groups have identical contents.
`private boolean`	`groupsOverlap(String[] possibilities)` Indicate whether any of the group names in the given array match any of the groups of interest.
`(package private) static AbstractLookupDiscovery.Initializer`	`init(Configuration config)`
`(package private) static AbstractLookupDiscovery.Initializer`	`initEmptyConf()`
`private Map<ServiceRegistrar,String[]>`	`mapRegToGroups(ServiceRegistrar reg, String[] curGroups)` Convenience method that creates and returns a mapping of a single `ServiceRegistrar` instance to a set of groups.
`private void`	`maybeAddNewRegistrar(UnicastResponse resp)` If the lookup service associated with the given UnicastResponse is not in the set of already-discovered lookup services, this method adds it to that set, and each registered listener is notified.
`private void`	`maybeDiscardRegistrars()` Determine if any of the already-discovered registrars are no longer members of any of the groups to discover, and discard those registrars that are no longer members of any of those groups.
`private void`	`maybeSendEvent(UnicastResponse response, String[] newGroups)` After a possible change in the member groups of the `ServiceRegistrar` corresponding to the given `UnicastResponse` parameter, this method determines whether or not the registrar's member groups have changed in such a way that either a changed event or a discarded event is warranted.
`private void`	`notifyOnGroupChange(ServiceRegistrar reg, String[] oldGroups, String[] newGroups)` After a possible change in the member groups of the given `ServiceRegistrar` parameter, this method compares the registrar's original set of member groups to its new set of member groups.
`private void`	`nukeThreads()` Terminates (interrupts) all currently-running threads.
`private static void`	`prepareSocket(Socket s, DiscoveryConstraints dc)`
`private static boolean`	`registrarsEqual(UnicastResponse resp1, UnicastResponse resp2)` Returns true if the registrars contained in the given (possibly null) UnicastResponse instances are equals() to one another.
`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.
`private boolean`	`removeGroupsInt(String[] oldGroups)` Remove the specified groups from the set of groups to discover, and return true if any were actually removed.
`private void`	`requestGroups(Collection req)` Called at startup and whenever the set of groups to discover is changed.
`private void`	`restoreContextAddTask(Runnable t)`
`private WakeupManager.Ticket`	`restoreContextScheduleRunnable(AbstractLookupDiscovery.UnicastDiscoveryTask t)`
`private void`	`sendChanged(ServiceRegistrar reg, String[] curGroups)` Convenience method that sends a changed event containing only one registrar to all registered listeners that are interested in such events.
`private void`	`sendDiscarded(ServiceRegistrar reg, String[] curGroups)` Convenience method that sends a discarded event containing only one registrar to all registered listeners.
`private static void`	`sendPacket(MulticastSocket mcSocket, DatagramPacket[] packet)` Sends the given packet data on the given `MulticastSocket` through the network interface that is currently set.
`private void`	`sendPacketByNIC(MulticastSocket mcSocket, DatagramPacket[] packet)` Sends the given packet data on the given `MulticastSocket` through each of the network interfaces corresponding to elements of the array configured when this utility was constructed.
`void`	`setGroups(String[] newGroups)` Change the set of groups to be discovered to correspond to the given set.
`(package private) void`	`start()` In previous releases threads were started in the constructor, however this violates safe construction according to the JMM.
`void`	`terminate()` Terminate the discovery process.
`private void`	`terminateTaskMgr()` This method removes all pending and active tasks from the TaskManager for this instance.
`private static void`	`testArrayForNullElement(String[] groupArray)` This method is used by the public methods of this class that are specified to throw a `NullPointerException` when the given array of group names contains one or more `null` elements; in which case, this method throws a `NullPointerException` which should be allowed to propagate outward.
`(package private) static String[]`	`verifyGroups(String[] groups)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - COMPONENT_NAME
```
private static final String COMPONENT_NAME
```
    See Also:
    
    Constant Field Values
  - logger
```
private static final Logger logger
```
  - MAX_N_TASKS
```
private static final int MAX_N_TASKS
```
    Maximum number of concurrent tasks that can be run in any executor created by this class.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_PACKET_SIZE
```
private static final int DEFAULT_MAX_PACKET_SIZE
```
    Default maximum size of multicast packets to send and receive.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MULTICAST_TTL
```
private static final int DEFAULT_MULTICAST_TTL
```
    Default time to live value to use for sending multicast packets.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_SOCKET_TIMEOUT
```
private static final int DEFAULT_SOCKET_TIMEOUT
```
    Default timeout to set on sockets used for unicast discovery.
    
    See Also:
    
    Constant Field Values
  - terminated
```
private volatile boolean terminated
```
    Flag indicating whether or not this class is still functional.
  - listeners
```
private final List<DiscoveryListener> listeners
```
    Set of listeners to be sent discovered/discarded/changed events. Access sync on registrars
  - groups
```
private final Set<String> groups
```
    The groups to discover. Empty set -- NO_GROUPS, access synchronised on registrars
  - all_groups
```
private volatile boolean all_groups
```
    If groups passed to constructor are null -- ALL_GROUPS, writes synchronised on registrars
  - registrars
```
private final Map<ServiceID,UnicastResponse> registrars
```
    Map from ServiceID to UnicastResponse.
  - pendingDiscoveries
```
private final Set pendingDiscoveries
```
    Set that takes one of the following:
    - Socket (discovery from multicast request/response exchange)
    - LookupLocator (discovery from multicast announcement)
    - CheckGroupsMarker (discarded/changed from announcement)
    - CheckReachabilityMarker (announcements stopped, tests reachability)
    Each element of this set represents a potential (or pending) discovered, discarded, or changed event. Instances of UnicastDiscoveryTask retrieve the next available element from this set and, based on the object type of the element, determines the processing to perform and what event type to send to the registered listeners.
  - notifierThread
```
private final AbstractLookupDiscovery.Notifier notifierThread
```
    Thread that handles pending notifications.
  - pendingNotifies
```
private final java.util.concurrent.BlockingDeque<AbstractLookupDiscovery.NotifyTask> pendingNotifies
```
    Notifications to be sent to listeners. Synchronised access with lock notify
  - executor
```
private final java.util.concurrent.ExecutorService executor
```
    ExecutorService for running UnicastDiscoveryTasks and DecodeAnnouncementTasks.
  - discoveryWakeupMgr
```
private final WakeupManager discoveryWakeupMgr
```
  - isDefaultWakeupMgr
```
private final boolean isDefaultWakeupMgr
```
  - tickets
```
private final List<WakeupManager.Ticket> tickets
```
  - announceeThread
```
private final AbstractLookupDiscovery.AnnouncementListener announceeThread
```
    Thread that handles incoming multicast announcements.
  - requestors
```
private final Collection<Thread> requestors
```
    Collection that contains instances of the Requestor Thread class, each of which participate in multicast discovery by periodically sending out multicast discovery requests for a finite period of time. Access synchronised.
  - respondeeThread
```
private volatile AbstractLookupDiscovery.ResponseListener respondeeThread
```
    Thread that manages incoming multicast responses. Runs only when there are Requestor threads running. Writes synchronised on requestors.
  - securityContext
```
private final SecurityContext securityContext
```
    Security context that contains the access control context to restore for callbacks, etc.
  - regInfo
```
private final java.util.concurrent.ConcurrentMap<ServiceID,AbstractLookupDiscovery.AnnouncementInfo> regInfo
```
    Map from ServiceID to multicast announcement time stamps; used by the process that monitors multicast announcements from already-discovered lookup services, and determines when those announcements have stopped. Access synchronised on registrars.
  - announcementTimerThread
```
private final AbstractLookupDiscovery.AnnouncementTimerThread announcementTimerThread
```
    Thread that monitors multicast announcements from already-discovered lookup services and, upon determining that those announcements have stopped, queues a reachability test with the UnicastDiscoveryTask which will ultimately result in the lookup service being discarded if the reachability test indicates that the lookup service is actually down.
  - registrarPreparer
```
private final ProxyPreparer registrarPreparer
```
  - protocol2
```
private final Discovery protocol2
```
  - multicastRequestMax
```
private final int multicastRequestMax
```
  - multicastRequestInterval
```
private final long multicastRequestInterval
```
  - finalMulticastRequestInterval
```
private final long finalMulticastRequestInterval
```
  - multicastRequestHost
```
private final String multicastRequestHost
```
  - multicastRequestConstraints
```
private final DiscoveryConstraints multicastRequestConstraints
```
  - nics
```
private final NetworkInterface[] nics
```
  - nicRetryInterval
```
private final int nicRetryInterval
```
  - multicastAnnouncementInterval
```
private final long multicastAnnouncementInterval
```
  - unicastDelayRange
```
private final long unicastDelayRange
```
  - initialMulticastRequestDelayRange
```
private final long initialMulticastRequestDelayRange
```
  - initialRequestorStarted
```
private boolean initialRequestorStarted
```
  - multicastAnnouncementConstraints
```
private final DiscoveryConstraints multicastAnnouncementConstraints
```
  - rawUnicastDiscoveryConstraints
```
private final InvocationConstraints rawUnicastDiscoveryConstraints
```
  - DISCOVERED
```
private static final int DISCOVERED
```
    Constants used to tell the notifierThread the type of event to send
    
    See Also:
    
    Constant Field Values
  - DISCARDED
```
private static final int DISCARDED
```
    See Also:
    
    Constant Field Values
  - CHANGED
```
private static final int CHANGED
```
    See Also:
    
    Constant Field Values
  - NICS_USE_ALL
```
private static final int NICS_USE_ALL
```
    Constants used to indicate the set of network interfaces being used
    
    See Also:
    
    Constant Field Values
  - NICS_USE_SYS
```
private static final int NICS_USE_SYS
```
    See Also:
    
    Constant Field Values
  - NICS_USE_LIST
```
private static final int NICS_USE_LIST
```
    See Also:
    
    Constant Field Values
  - NICS_USE_NONE
```
private static final int NICS_USE_NONE
```
    See Also:
    
    Constant Field Values
  - nicsToUse
```
private final int nicsToUse
```
    Flag that indicates how the set of network interfaces was configured
  - thrown
```
private final Exception thrown
```
  - started
```
private boolean started
```
- Constructor Detail
  - AbstractLookupDiscovery
```
AbstractLookupDiscovery(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
  - AbstractLookupDiscovery
```
AbstractLookupDiscovery(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
  - AbstractLookupDiscovery
```
private AbstractLookupDiscovery(String[] groups,
                                AbstractLookupDiscovery.Initializer init)
```
- Method Detail
  - verifyGroups
```
static String[] verifyGroups(String[] groups)
                      throws NullPointerException,
                             SecurityException
```
    Throws:
    
    NullPointerException
    
    SecurityException
  - initEmptyConf
```
static AbstractLookupDiscovery.Initializer initEmptyConf()
                                                  throws IOException
```
    Throws:
    
    IOException
  - init
```
static AbstractLookupDiscovery.Initializer init(Configuration config)
                                         throws IOException,
                                                ConfigurationException
```
    Throws:
    
    IOException
    
    ConfigurationException
  - start
```
void start()
    throws IOException
```
    In previous releases threads were started in the constructor, however this violates safe construction according to the JMM.
    Threads will be started automatically when a DiscoveryListener is added, if start hasn't been called.
    
    Throws:
    
    IOException
    
    Since:
    
    2.2.1
  - 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[])
  - sendPacketByNIC
```
private void sendPacketByNIC(MulticastSocket mcSocket,
                             DatagramPacket[] packet)
                      throws InterruptedIOException
```
    Sends the given packet data on the given MulticastSocket through each of the network interfaces corresponding to elements of the array configured when this utility was constructed.
    
    Parameters:
    
    mcSocket - the MulticastSocket on which the data will be sent
    
    packet - DatagramPacket array whose elements are the data to send
    
    Throws:
    
    InterruptedIOException
  - sendPacket
```
private static void sendPacket(MulticastSocket mcSocket,
                               DatagramPacket[] packet)
                        throws IOException
```
    Sends the given packet data on the given MulticastSocket through the network interface that is currently set.
    
    Parameters:
    
    mcSocket - the MulticastSocket on which the data will be sent
    
    packet - DatagramPacket array whose elements are the data to send
    
    Throws:
    
    IOException
  - getLocalHost
```
private static String getLocalHost()
                            throws UnknownHostException
```
    Returns the local host name.
    
    Throws:
    
    UnknownHostException
  - checkGroups
```
private static void checkGroups(String[] groups)
```
    Determines if the caller has discovery permission for each group.
  - collectionToStrings
```
private static final String[] collectionToStrings(Collection c)
```
    Converts a collection to an array of strings.
  - groupSetsEqual
```
private static boolean groupSetsEqual(String[] groupSet0,
                                      String[] groupSet1)
```
    Determines if two sets of registrar member groups have identical contents. Assumes there are no duplicates, and the sets can never be null.
    
    Parameters:
    
    groupSet0 - String array containing the group names from the first set used in the comparison
    
    groupSet1 - String array containing the group names from the second set used in the comparison
    
    Returns:
    
    true if the contents of each set is identical; false otherwise
  - registrarsEqual
```
private static boolean registrarsEqual(UnicastResponse resp1,
                                       UnicastResponse resp2)
```
    Returns true if the registrars contained in the given (possibly null) UnicastResponse instances are equals() to one another.
  - removeGroupsInt
```
private boolean removeGroupsInt(String[] oldGroups)
```
    Remove the specified groups from the set of groups to discover, and return true if any were actually removed. Must be synchronised on registrars.
  - getServiceIDs
```
private ServiceID[] getServiceIDs()
```
    Returns the service IDs of the lookup service(s) discovered to date.
  - groupsOverlap
```
private boolean groupsOverlap(String[] possibilities)
```
    Indicate whether any of the group names in the given array match any of the groups of interest.
    
    Parameters:
    
    possibilities - the set of group names to compare to the set of groups to discover (must not be null)
  - requestGroups
```
private void requestGroups(Collection req)
                    throws IOException
```
    Called at startup and whenever the set of groups to discover is changed. This method executes the multicast request protocol by starting the ResponseListener thread to listen for multicast responses; and starting a Requestor thread to send out multicast requests for the set of groups contained in the given Collection.
    
    Throws:
    
    IOException
  - prepareSocket
```
private static void prepareSocket(Socket s,
                                  DiscoveryConstraints dc)
                           throws SocketException
```
    Throws:
    
    SocketException
  - maybeAddNewRegistrar
```
private void maybeAddNewRegistrar(UnicastResponse resp)
```
    If the lookup service associated with the given UnicastResponse is not in the set of already-discovered lookup services, this method adds it to that set, and each registered listener is notified.
    
    Parameters:
    
    resp - the UnicastResponse associated with the lookup service to add
  - maybeDiscardRegistrars
```
private void maybeDiscardRegistrars()
```
    Determine if any of the already-discovered registrars are no longer members of any of the groups to discover, and discard those registrars that are no longer members of any of those groups.
  - addNotify
```
private void addNotify(List<DiscoveryListener> notifies,
                       Map<ServiceRegistrar,String[]> groupsMap,
                       int eventType)
```
    Add a notification task to the pending queue, and wake up the Notifier.
  - nukeThreads
```
private void nukeThreads()
```
    Terminates (interrupts) all currently-running threads.
  - terminateTaskMgr
```
private void terminateTaskMgr()
```
    This method removes all pending and active tasks from the TaskManager for this instance. It also clears the set of pendingDiscoveries, and closes all associated sockets.
  - maybeSendEvent
```
private void maybeSendEvent(UnicastResponse response,
                            String[] newGroups)
```
    After a possible change in the member groups of the ServiceRegistrar corresponding to the given UnicastResponse parameter, this method determines whether or not the registrar's member groups have changed in such a way that either a changed event or a discarded event is warranted.
    Note that even if the contents of the new set of groups initially indicate that the corresponding registrar is a candidate for a discarded or a changed event, further analysis must be performed. This is because there is no guarantee that the new set of member groups have not been "split" across the multicast announcements sent by the lookup service; and so there is no guarantee that the contents of the new group set actually reflect a change that warrants an event. To guarantee that the new group set accurately reflects the registrar's member groups, this method makes a remote call to the registrar to retrieve its actual member groups.
    There is one situation where it is not necessary to query the registrar for its current member groups. That situation is when the set of groups input to the newGroups parameter is equivalent to NO_GROUPS. If that new group set is equivalent to NO_GROUPS, it is guaranteed that the registrar's member groups have not been split across the multicast announcements.
    
    Parameters:
    
    response - instance of UnicastResponse corresponding to the registrar whose current and previous member groups are to be compared
    
    newGroups - String array containing the new member groups of the registrar corresponding to the response parameter (just after a possible change)
  - notifyOnGroupChange
```
private void notifyOnGroupChange(ServiceRegistrar reg,
                                 String[] oldGroups,
                                 String[] newGroups)
```
    After a possible change in the member groups of the given ServiceRegistrar parameter, this method compares the registrar's original set of member groups to its new set of member groups.
    If the criteria shown below is satisfied, either a discarded event or a changed event will be sent to any registered listeners. The criteria is based on whether the old and new groups are equal, and whether one or more elements of the new group set also belong to the set of groups to discover (the new groups are "still of interest"). The criteria is as follows:
    if (old groups and new groups)
    - (not equal but stillInterested) --> send a changed event
    - (!stillInterested) --> send a discarded event
    Parameters:
    
    reg - instance of ServiceRegistrar corresponding to the registrar whose current and previous member groups are to be compared; and whose corresponding service ID is used as the key into the various data structures that contain pertinent information about that registrar
    
    oldGroups - String array containing the member groups of the reg parameter prior to being changed
    
    newGroups - String array containing the current member groups of the reg parameter (just after a possible change)
  - sendDiscarded
```
private void sendDiscarded(ServiceRegistrar reg,
                           String[] curGroups)
```
    Convenience method that sends a discarded event containing only one registrar to all registered listeners. This method must be called from within a block that is synchronized on the registrars map.
    
    Parameters:
    
    reg - instance of ServiceRegistrar corresponding to the registrar to include in the event
    
    curGroups - String array containing the current member groups of the registrar referenced by the reg parameter
  - sendChanged
```
private void sendChanged(ServiceRegistrar reg,
                         String[] curGroups)
```
    Convenience method that sends a changed event containing only one registrar to all registered listeners that are interested in such events. This method must be called from within a block that is synchronized on the registrars map.
    
    Parameters:
    
    reg - instance of ServiceRegistrar corresponding to the registrar to include in the event
    
    curGroups - String array containing the current member groups of the registrar referenced by the reg parameter
  - deepCopy
```
private Map<ServiceRegistrar,String[]> deepCopy(Map<ServiceRegistrar,String[]> groupsMap)
```
    Creates and returns a deep copy of the input parameter. This method assumes the input map is a HashMap of the registrar-to-groups mapping; and returns a clone not only of the map, but of each key-value pair contained in the mapping.
    
    Parameters:
    
    groupsMap - mapping from a set of registrars to the member groups of each registrar
    
    Returns:
    
    clone of the input map, and of each key-value pair contained in the input map
  - getActualGroups
```
private String[] getActualGroups(ServiceRegistrar reg)
```
    This method retrieves from the given ServiceRegistrar, the current groups in which that registrar is a member. If the registrar is un-reachable, then this method will discard the registrar.
    
    Parameters:
    
    reg - instance of ServiceRegistrar referencing the registrar whose member groups are to be retrieved and returned
    
    Returns:
    
    String array containing the current member groups of the registrar referenced by the reg parameter
  - mapRegToGroups
```
private Map<ServiceRegistrar,String[]> mapRegToGroups(ServiceRegistrar reg,
                                                      String[] curGroups)
```
    Convenience method that creates and returns a mapping of a single ServiceRegistrar instance to a set of groups.
    
    Parameters:
    
    reg - instance of ServiceRegistrar corresponding to the registrar to use as the key to the mapping
    
    curGroups - String array containing the current member groups of the registrar referenced by the reg parameter; and which is used as the value of the mapping
    
    Returns:
    
    Map instance containing a single mapping from a given registrar to its current member groups
  - testArrayForNullElement
```
private static void testArrayForNullElement(String[] groupArray)
```
    This method is used by the public methods of this class that are specified to throw a NullPointerException when the given array of group names contains one or more null elements; in which case, this method throws a NullPointerException which should be allowed to propagate outward.
    
    Throws:
    
    NullPointerException - this exception occurs when one or more of the elements of the groupArray parameter is null.
  - decodeMulticastAnnouncement
```
private MulticastAnnouncement decodeMulticastAnnouncement(DatagramPacket pkt)
                                                   throws IOException
```
    Decodes received multicast announcement packet. Constraint checking is delayed.
    
    Throws:
    
    IOException
  - checkAnnouncementConstraints
```
private void checkAnnouncementConstraints(MulticastAnnouncement ann)
                                   throws IOException
```
    Throws:
    
    IOException
  - encodeMulticastRequest
```
private DatagramPacket[] encodeMulticastRequest(MulticastRequest req)
                                         throws IOException
```
    Encodes outgoing multicast requests based on protocol in use, applying configured security constraints (if any).
    
    Throws:
    
    IOException
  - restoreContextAddTask
```
private void restoreContextAddTask(Runnable t)
```
  - restoreContextScheduleRunnable
```
private WakeupManager.Ticket restoreContextScheduleRunnable(AbstractLookupDiscovery.UnicastDiscoveryTask t)
```
  - doUnicastDiscovery
```
private UnicastResponse doUnicastDiscovery(Socket socket,
                                           DiscoveryConstraints unicastDiscoveryConstraints,
                                           Discovery disco)
                                    throws IOException,
                                           ClassNotFoundException
```
    Performs unicast discovery over given socket based on protocol in use, applying configured security constraints (if any).
    
    Throws:
    
    IOException
    
    ClassNotFoundException
  - doUnicastDiscovery
```
private UnicastResponse doUnicastDiscovery(Socket socket,
                                           DiscoveryConstraints unicastDiscoveryConstraints)
                                    throws IOException,
                                           ClassNotFoundException
```
    Throws:
    
    IOException
    
    ClassNotFoundException
  - getDiscovery
```
private Discovery getDiscovery(int version)
                        throws DiscoveryProtocolException
```
    Returns Discovery instance for the given version, or throws DiscoveryProtocolException if the version is unsupported.
    
    Throws:
    
    DiscoveryProtocolException

Class AbstractLookupDiscovery

Nested Class Summary

Field Summary

Fields inherited from interface net.jini.discovery.DiscoveryGroupManagement

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

COMPONENT_NAME

logger

MAX_N_TASKS

DEFAULT_MAX_PACKET_SIZE

DEFAULT_MULTICAST_TTL

DEFAULT_SOCKET_TIMEOUT

terminated

listeners

groups

all_groups

registrars

pendingDiscoveries

notifierThread

pendingNotifies

executor

discoveryWakeupMgr

isDefaultWakeupMgr

tickets

announceeThread

requestors

respondeeThread

securityContext

regInfo

announcementTimerThread

registrarPreparer

protocol2

multicastRequestMax

multicastRequestInterval

finalMulticastRequestInterval

multicastRequestHost

multicastRequestConstraints

nics

nicRetryInterval

multicastAnnouncementInterval

unicastDelayRange

initialMulticastRequestDelayRange

initialRequestorStarted

multicastAnnouncementConstraints

rawUnicastDiscoveryConstraints

DISCOVERED

DISCARDED

CHANGED

NICS_USE_ALL

NICS_USE_SYS

NICS_USE_LIST

NICS_USE_NONE

nicsToUse

thrown

started

Constructor Detail

AbstractLookupDiscovery

AbstractLookupDiscovery

AbstractLookupDiscovery

Method Detail

verifyGroups

initEmptyConf

init

start

addDiscoveryListener

removeDiscoveryListener

getRegistrars

discard

terminate

getGroups

addGroups

setGroups

removeGroups

sendPacketByNIC

sendPacket

getLocalHost

checkGroups

collectionToStrings