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.
|Modifier and Type||Field and Description|
Flag indicating whether the event is a discovery event or a discard event.
List consisting of marshalled proxy objects where each proxy implements the
Array containing a subset of the set of proxies to the lookup service(s) with which this event is associated.
|Constructor and Description|
Constructs a new instance of
|Modifier and Type||Method and Description|
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.
Returns an array consisting of instances of the ServiceRegistrar interface.
Returns the value of the boolean flag that indicates whether this event is a discovery event or a discard event.
getID, getRegistrationObject, getSequenceNumber, getSource
protected boolean discarded
false, then the lookup services referenced by this event were just discovered; if
true, then those lookup services were just discarded.
protected List<MarshalledObject> marshalledRegs
ServiceRegistrarinterface, 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
resulting in the loss of all of the elements of the list, even those
that could be successfully deserialized.
protected ServiceRegistrar regs
array that were successfully unmarshalled (at least once) as a result of one or more invocations of the
getRegistrarsmethod of this event. Upon deserializing this event, this array is empty, but of the same size as
; and will be populated when the recipient of this event retrieves the registrars corresponding to the elements of
public RemoteDiscoveryEvent(Object source, long eventID, long seqNum, MarshalledObject handback, boolean discarded, Map<ServiceRegistrar,String> groups) throws IOException
source- reference to the lookup discovery service that generated the event
eventID- the event identifier that maps a particular registration to its listener and targeted groups and locators
seqNum- the sequence number of this event
handback- the client handback (null may be input)
discarded- flag indicating whether the event being constructed is a discovery event or a discard event
groups- mapping from the registrars of this event to the groups in which each registrar is a member
IOException- 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
nullis input for the map parameter, or at least one element of that map is
IllegalArgumentException- this exception occurs when an empty set of registrars is input.
public boolean isDiscarded()
trueif this is a discard event,
falseif 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).
To retrieve the set of member groups corresponding to any element
of the array returned by the
simply use the service ID of the desired element from that array as
the key to the
get method of the
returned by this method and cast to
Note that the same
Map object is returned on every
call to this method; that is, a copy is not made.
Mapwhose 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 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.