Whenever the lookup discovery service discovers or discards a lookup service matching the discovery/discard criteria of one or more of its registrations, the lookup discovery service sends an instance of this class to the listener corresponding to each such registration.
For each registration created by the lookup discovery service, an event identifier is generated. That event identifier uniquely maps the registration to the listener (submitted by the client to the lookup discovery service during the registration process) and to the set of groups and locators the client is interested in discovering. The event identifier is unique across all other active registrations with the lookup discovery service, and is sent to the listener as part of the event.
Because clients of the lookup discovery service need to know not only when a targeted lookup service has been discovered, but also when it has been discarded, the lookup discovery service uses an instance of this class to notify a client's registration(s) when either of these events occurs.
This class extends RemoteEvent, adding the following additional items of abstract state: a boolean indicating whether the lookup services referenced by the event have been discovered or discarded; and a set consisting of proxy objects where each proxy is a marshalled instance of the ServiceRegistrar interface, and each is a proxy of one of the recently discovered or discarded lookup service(s). Methods are defined through which this additional state may be retrieved upon receipt of an instance of this class.
The sequence numbers for a given event identifier are "strictly increasing". This means that when any two such successive events have sequence numbers differing by only a value of 1, then it is guaranteed that no events have been missed. On the other hand, when viewing the set of received events in order, if the difference between the sequence numbers of two successive events is greater than 1, then one or more events may or may not have been missed. For example, a difference greater than 1 could occur if the lookup discovery service crashes, even if no events are lost because of the crash. When two successive events have sequence numbers whose difference is greater than 1, there is said to be a "gap" between the events.
When a gap occurs between events, the state of the locally managed set of lookup services may or may not fall "out of sync" with the corresponding remote state. For example, if the gap corresponds to a missed event representing the (initial) discovery of a targeted lookup service, the remote state will reflect this discovery whereas the local state will not. When such a situation occurs, clients may wish to employ the methods of the corresponding registration object to query the current remote state in order to update the current local state.
Thus, clients typically use this class to determine if conditions are right for a loss of synchronization (by verifying the existence of a gap in the event sequence). Clients then typically use the methods provided by the registration object to both determine if a loss of synchronization has actually occurred, and to correct such a situation when it does occur.
@author Sun Microsystems, Inc.
@see net.jini.core.event.RemoteEvent
@see net.jini.core.lookup.ServiceRegistrar