|
GigaSpaces XAP 10.0.1 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.util.EventObject
net.jini.core.event.RemoteEvent
net.jini.discovery.RemoteDiscoveryEvent
public class RemoteDiscoveryEvent
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.
RemoteEvent
,
ServiceRegistrar
,
Serialized FormField Summary | |
---|---|
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. |
Fields inherited from class net.jini.core.event.RemoteEvent |
---|
eventID, handback, seqNum, source |
Constructor Summary | |
---|---|
RemoteDiscoveryEvent(Object source,
long eventID,
long seqNum,
MarshalledObject handback,
boolean discarded,
Map groups)
Constructs a new instance of RemoteDiscoveryEvent . |
Method Summary | |
---|---|
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. |
Methods inherited from class net.jini.core.event.RemoteEvent |
---|
getID, getRegistrationObject, getSequenceNumber |
Methods inherited from class java.util.EventObject |
---|
getSource, toString |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
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 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.
groups
protected Map groups
Map
from the service IDs of the registrars of this event
to the groups in which each registrar is a member.
Constructor Detail
RemoteDiscoveryEvent
public RemoteDiscoveryEvent(Object source,
long eventID,
long seqNum,
MarshalledObject handback,
boolean discarded,
Map groups)
throws IOException
- Constructs a new instance of
RemoteDiscoveryEvent
.
- Parameters:
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 member
- Throws:
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 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.
Method Detail
isDiscarded
public boolean isDiscarded()
- Returns the value of the boolean flag that indicates whether this
event is a discovery event or a discard event.
- Returns:
true
if this is a discard event, false
if it is a discovery event.
getRegistrars
public ServiceRegistrar[] getRegistrars()
throws LookupUnmarshalException
- Returns an array consisting of instances of the ServiceRegistrar
interface. Each element in the returned set is a proxy to one of
the newly discovered or discarded lookup service(s) that caused
the current instance of this event class to be sent to the listener
of the client's registration. Note that a new array is returned
on every call.
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.
- Returns:
- an array consisting of references to the discovered or discarded
lookup service(s) corresponding to this event.
- Throws:
LookupUnmarshalException
- this exception
occurs when at least one of the set of lookup service
references cannot be deserialized (unmarshalled).- See Also:
LookupUnmarshalException
getGroups
public 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.
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.
- Returns:
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.
Overview
Package
Class
Use
Tree
Deprecated
Index
Help
GigaSpaces XAP 10.0.1 API
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
Copyright © GigaSpaces.