net.jini.lookup
Class ServiceDiscoveryEvent

java.lang.Object
  java.util.EventObject
      net.jini.lookup.ServiceDiscoveryEvent

All Implemented Interfaces:

Serializable

public class ServiceDiscoveryEvent
extends EventObject

The ServiceDiscoveryEvent class encapsulates the service discovery information made available by the event mechanism of the LookupCache. All listeners that an entity has registered with the cache's event mechanism will receive an event of type ServiceDiscoveryEvent upon the discovery, removal, or modification of one of the cache's services. This class is used by ServiceDiscoveryManager.

Author:

Sun Microsystems, Inc.

See Also:

BackwardsServiceDiscoveryManager, Serialized Form

Field Summary

Fields inherited from class java.util.EventObject

source

Constructor Summary

ServiceDiscoveryEvent(Object source, ServiceItem preEventItem, ServiceItem postEventItem)
The constructor of ServiceDiscoveryEvent takes three arguments: An instance of Object corresponding to the instance of LookupCache from which the given event originated A ServiceItem reference representing the state of the service (associated with the given event) prior to the occurrence of the event A ServiceItem reference representing the state of the service after the occurrence of the event If null is passed as the source parameter for the constructor, a NullPointerException will be thrown.

Method Summary

ServiceItem	getPostEventServiceItem() Returns an instance of a ServiceItem containing the service reference corresponding to the given event.
ServiceItem	getPreEventServiceItem() Returns an instance of a ServiceItem containing the service reference corresponding to the given event.

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

Constructor Detail

ServiceDiscoveryEvent

public ServiceDiscoveryEvent(Object source,
                             ServiceItem preEventItem,
                             ServiceItem postEventItem)

The constructor of ServiceDiscoveryEvent takes three arguments:

An instance of Object corresponding to the instance of LookupCache from which the given event originated

A ServiceItem reference representing the state of the service (associated with the given event) prior to the occurrence of the event

A ServiceItem reference representing the state of the service after the occurrence of the event

If null is passed as the source parameter for the constructor, a NullPointerException will be thrown.

Depending on the nature of the discovery event, a null reference may be passed as one or the other of the remaining parameters, but never both. If null is passed as both the preEventItem and the postEventItem parameters, a NullPointerException will be thrown.

Note that the constructor will not modify the contents of either ServiceItem argument. Doing so can result in unpredictable and undesirable effects on future processing by the ServiceDiscoveryManager. That is why the effects of any such modification to the contents of either input parameter are undefined.

Parameters:

source - an instance of Object corresponding to the instance of LookupCache from which the given event originated.

preEventItem - a ServiceItem reference representing the state of the service (associated with the given event) prior to the occurrence of the event.

postEventItem - a ServiceItem reference representing the state of the service after the occurrence of the event.

Throws:

NullPointerException - if null is passed as the source parameter for the constructor, or if null is passed as both the preEventItem and the postEventItem parameters.

Method Detail

getPreEventServiceItem

public ServiceItem getPreEventServiceItem()

Returns an instance of a ServiceItem containing the service reference corresponding to the given event. The service state reflected in the returned service item is the state of the service prior to the occurrence of the event.

If the event is a discovery event (as opposed to a removal or modification event), then this method will return null because the discovered service had no state in the cache prior to its discovery.

Because making a copy can be a very expensive process, this method does not return a copy of the service reference associated with the given event. Rather, it returns the appropriate service reference from the cache itself. Due to this cost, listeners that receive a ServiceDiscoveryEvent must not modify the contents of the object returned by this method; doing so could cause the state of the cache to become corrupted or inconsistent because the objects returned by this method are also members of the cache. This potential for corruption or inconsistency is why the effects of modifying the object returned by this accessor method are undefined.

Returns:

ServiceItem containing the service reference corresponding to the given event.

getPostEventServiceItem

public ServiceItem getPostEventServiceItem()

Returns an instance of a ServiceItem containing the service reference corresponding to the given event. The service state reflected in the returned service item is the state of the service after the occurrence of the event.

If the event is a removal event, then this method will return null because the discovered service has no state in the cache after it is removed from the cache.

Because making a copy can be a very expensive process, this method does not return a copy of the service reference associated with the given event. Rather, it returns the appropriate service reference from the cache itself. Due to this cost, listeners that receive a ServiceDiscoveryEvent must not modify the contents of the object returned by this method; doing so could cause the state of the cache to become corrupted or inconsistent because the objects returned by this method are also members of the cache. This potential for corruption or inconsistency is why the effects of modifying the object returned by this accessor method are undefined.

Returns:

ServiceItem containing the service reference corresponding to the given event.