net.jini.discovery

Class RemoteDiscoveryEvent

java.lang.Object

java.util.EventObject

net.jini.core.event.RemoteEvent

net.jini.discovery.RemoteDiscoveryEvent

All Implemented Interfaces:

Serializable

public class RemoteDiscoveryEvent
extends RemoteEvent

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 Also:

RemoteEvent, ServiceRegistrar, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	discarded Flag indicating whether the event is a discovery event or a discard event.
protected Map<ServiceID,String>	groups Map from the service IDs of the registrars of this event to the groups in which each registrar is a member.
protected List<MarshalledObject>	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

Constructors

Constructor and Description
RemoteDiscoveryEvent(Object source, long eventID, long seqNum, MarshalledObject handback, boolean discarded, Map<ServiceRegistrar,String> groups) Constructs a new instance of RemoteDiscoveryEvent.

Method Summary

Modifier and Type	Method and Description
Map<ServiceID,String>	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, getSource

Methods inherited from class java.util.EventObject

toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

discarded

protected boolean discarded

Flag indicating whether the event is a discovery event or a discard event. If this variable is false, then the lookup services referenced by this event were just discovered; if true, then those lookup services were just discarded.

marshalledRegs

protected List<MarshalledObject> 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.

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.

regs

protected ServiceRegistrar[] regs

Array containing a subset of the set of proxies to the lookup service(s) with which this event is associated. The elements of this array correspond to those elements of the 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<ServiceID,String> 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<ServiceRegistrar,String> groups)
                     throws IOException

Constructs a new instance of RemoteDiscoveryEvent.

Parameters:

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

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<ServiceID,String> 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.