public class RemoteDiscoveryEvent extends RemoteEvent
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.
RemoteEvent,
ServiceRegistrar,
Serialized Form| Modifier and Type | Field and Description |
|---|---|
protected boolean |
discarded
Flag indicating whether the event is a discovery event or a discard
event.
|
protected Map |
groups
Map from the service IDs of the registrars of this event
to the groups in which each registrar is a member. |
protected ArrayList |
marshalledRegs
List consisting of marshalled proxy objects where each proxy implements
the
ServiceRegistrar interface, and each is a proxy of
one of the recently discovered or discarded lookup service(s); the
lookup service(s) with which this event is associated. |
protected ServiceRegistrar[] |
regs
Array containing a subset of the set of proxies to the lookup
service(s) with which this event is associated.
|
eventID, handback, seqNum, source| Constructor and Description |
|---|
RemoteDiscoveryEvent(Object source,
long eventID,
long seqNum,
MarshalledObject handback,
boolean discarded,
Map groups)
Constructs a new instance of
RemoteDiscoveryEvent. |
| Modifier and Type | Method and Description |
|---|---|
Map |
getGroups()
Returns a set that maps to the service ID of each registrar referenced
by this event, the current set of groups in which each registrar is a
member.
|
ServiceRegistrar[] |
getRegistrars()
Returns an array consisting of instances of the ServiceRegistrar
interface.
|
boolean |
isDiscarded()
Returns the value of the boolean flag that indicates whether this
event is a discovery event or a discard event.
|
getID, getRegistrationObject, getSequenceNumbergetSource, toStringprotected boolean discarded
false, then the lookup services
referenced by this event were just discovered; if true,
then those lookup services were just discarded.protected ArrayList marshalledRegs
ServiceRegistrar interface, and each is a proxy of
one of the recently discovered or discarded lookup service(s); the
lookup service(s) with which this event is associated.
Each proxy in this list is individually marshalled in order to add an additional 'layer' of serialization. Placing this serialization "wrapper" around each element prevents the deserialization mechanism from attempting to deserialize the individual elements in the list. That is, the deserialization mechanism will only deserialize the list itself. After the list itself is successfully deserialized, the client (or a third party, if the client requested that events be sent to a third party such as a mailbox), can then attempt to unmarshal each element separately. This allows each success to be captured, and each failure to be noted.
If the elements of this list were not each marshalled separately,
then upon encountering failure while attempting to deserialize any
one element of the list, the deserialization mechanism's
readObject method will throw an IOException;
resulting in the loss of all of the elements of the list, even those
that could be successfully deserialized.
protected ServiceRegistrar[] regs
marshalledRegs
array that were successfully unmarshalled (at least once) as a result
of one or more invocations of the getRegistrars method
of this event. Upon deserializing this event, this array is empty,
but of the same size as marshalledRegs; and will be
populated when the recipient of this event retrieves the registrars
corresponding to the elements of marshalledRegs.protected Map groups
Map from the service IDs of the registrars of this event
to the groups in which each registrar is a member.public RemoteDiscoveryEvent(Object source, long eventID, long seqNum, MarshalledObject handback, boolean discarded, Map groups) throws IOException
RemoteDiscoveryEvent.source - reference to the lookup discovery service that
generated the eventeventID - the event identifier that maps a particular
registration to its listener and targeted groups
and locatorsseqNum - the sequence number of this eventhandback - the client handback (null may be input)discarded - flag indicating whether the event being constructed
is a discovery event or a discard eventgroups - mapping from the registrars of this event to the
groups in which each registrar is a memberIOException - when serialization failure occurs on
every registrar of this event. That is, if at least one
registrar is successfully serialized, then this exception
will not be thrown.NullPointerException - this exception occurs when
either null is input for the map parameter, or
at least one element of that map is null.IllegalArgumentException - this exception occurs
when an empty set of registrars is input.public boolean isDiscarded()
true if this is a discard event, false
if it is a discovery event.public ServiceRegistrar[] getRegistrars() throws LookupUnmarshalException
When the lookup discovery service sends an instance of this event class to the listener of a client's registration, the set of lookup service proxies contained in the event is sent as a set of marshalled instances of the ServiceRegistrar interface. Thus, in order to construct the return set, this method attempts to unmarshal each element of that set of proxies. Should a failure occur while attempting to unmarshal any of the elements of the set of marshalled proxy objects contained in the current instance of this class, this method will throw an exception of type LookupUnmarshalException.
When a LookupUnmarshalException is thrown by this method, the contents of the exception provides the client with the following useful information: (1) the knowledge that a problem has occurred while unmarshalling at least one of the as yet unmarshalled proxy objects, (2) the set consisting of the proxy objects that were successfully unmarshalled (either on the current invocation of this method or on some previous invocation), (3) the set consisting of the marshalled proxy objects that could not be unmarshalled during the current or any previous invocation of this method, and (4) the set of exceptions corresponding to each failed attempt at unmarshalling during the current invocation of this method.
Typically, the type of exception that occurs when attempting to unmarshal an element of the set of marshalled proxies is either an IOException or a ClassNotFoundException. A ClassNotFoundException occurs whenever a remote field of the marshalled proxy cannot be retrieved (usually because the codebase of one of the field's classes or interfaces is currently 'down'). To address this situation, the client may wish to invoke this method at some later time when the 'down' codebase(s) may be accessible. Thus, the client can invoke this method multiple times until all of the elements of the set of marshalled proxies can be successfully unmarshalled.
Note that once an element of the set of marshalled proxy objects has been successfully unmarshalled on a particular invocation of this method, the resulting unmarshalled proxy is stored for return on all future invocations of this method. That is, once successfully unmarshalled, no attempt will be made to unmarshal that element on any future invocations of this method. Thus, if this method returns successfully without throwing a LookupUnmarshalException, the client is guaranteed that all marshalled proxies have been successfully unmarshalled; and any future invocations of this method will return successfully.
LookupUnmarshalException - this exception
occurs when at least one of the set of lookup service
references cannot be deserialized (unmarshalled).LookupUnmarshalExceptionpublic Map getGroups()
To retrieve the set of member groups corresponding to any element
of the array returned by the getRegistrars method,
simply use the service ID of the desired element from that array as
the key to the get method of the Map object
returned by this method and cast to String[].
Note that the same Map object is returned on every
call to this method; that is, a copy is not made.
Map whose key set consists of the service IDs
of each lookup service with which this event is associated,
and whose values are String[] arrays containing
the names of the groups in which the lookup service having
the corresponding service ID is a member.Copyright © GigaSpaces.