net.jini.lookup

Interface ServiceDiscoveryListener

public interface ServiceDiscoveryListener

The ServiceDiscoveryListener interface defines the methods used by objects such as a LookupCache to notify an entity that events of interest related to the elements of the cache have occurred. It is the responsibility of the entity wishing to be notified of the occurrence of such events to construct an object that implements the ServiceDiscoveryListener interface and then register that object with the cache's event mechanism. Any implementation of this interface must define the actions to take upon receipt of an event notification. The action taken is dependent on both the application and the particular event that has occurred.

When the cache receives from one of the managed lookup services, an event signaling the registration of a service of interest for the first time (or for the first time since the service has been discarded), the cache applies any requested filtering and, if the service of interest passes the filter (or if no filtering was requested), the cache invokes the serviceAdded method on all instances of ServiceDiscoveryListener that are registered with the cache. Invoking the serviceAdded method notifies the entity that a service of interest that matches any additional selection criteria has been discovered, and is safe to use (if proxy preparation was requested).

When the cache receives, from a managed lookup service, an event signaling the removal of a service of interest from the last such lookup service with which it was registered, the cache invokes the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that a service of interest has been discarded.

In addition to the scenarios just described, the cache may also receive, from a managed lookup service, a notification indicating that one of the following events has occurred:

• The service has changed in some fundamental way (for example, the service is replaced with a new version), as determined by MarshalledInstance.fullyEquals
• The attributes of interest (across the attribute sets of all references to the service) have been uniquely modified

Note that that when determining whether the proxy referenced in the event is fundamentally different from the corresponding proxy held by the cache (the proxy that references the same service as the proxy from the event), the cache applies MarshalledInstance.fullyEquals to the unprepared forms of both proxies.

When the cache receives, from a managed lookup service, a notification indicating that one of the above events has occurred, the cache will first apply any requested filtering to the service referenced by the event; after which the cache will invoke either the serviceChanged method or the serviceRemoved method, possibly followed by the serviceAdded method. Which of those methods the cache ultimately invokes is dependent on the nature of the notification from the lookup service as well as the results of any filtering that is performed.

If the event from the lookup service indicates that attributes of the service have been modified, and if either no filtering is requested or the service referenced by the event passes the filter, then the cache invokes the serviceChanged method on all instances of ServiceDiscoveryListener that are registered with the cache. Invoking the serviceChanged method notifies the entity that the attributes of the previously discovered service have been changed in some way that is still of interest to the entity.

If the event from the lookup service indicates that the previously discovered service itself has changed, then if either filtering is not requested or the service passes the requested filter, the cache invokes the serviceRemoved method and then the serviceAdded method on all instances of ServiceDiscoveryListener that are registered with the cache. Invoking the serviceRemoved method followed by the serviceAdded method notifies the entity that the previously discovered service has been replaced with a new reference.

If, on the other hand, filtering is requested but the service fails the filter, then the cache invokes only the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the cache. In this case, the serviceRemoved method is invoked because the cache has concluded that the previously discovered service has been replaced with a new reference that is either no longer of interest to the entity, or is not safe to use.

Finally, if filtering is requested but the filtering process results in an indefinite state, then the cache first invokes the serviceRemoved method (to indicate to the entity that the service is currently unusable), and then periodically retries the filter for an implementation-dependent amount of time that is likely to exceed the typical service lease duration, until either a failure occurs or a pass occurs. If a pass occurs within the retry time period, the cache invokes the serviceAdded method because the cache has concluded that the previously discovered service has been replaced with a new reference that is still of interest to the entity, and is now safe to use.

The methods just described -- serviceAdded, serviceRemoved, and serviceChanged -- each take a single parameter of type ServiceDiscoveryEvent, which contains references to the service item corresponding to the event, including representations of the service's state both before and after the event.

Except for possible modifications that result from filtering, each method defined by this interface must not modify the contents of the ServiceDiscoveryEvent parameter; doing so can result in unpredictable and undesirable effects on future processing by the ServiceDiscoveryManager. Therefore, the effects of such modifications are undefined.

The ServiceDiscoveryListener interface makes the following concurrency guarantee: for any given listener object that implements this interface or any sub-interface, no two methods defined by the interface or sub-interface will be invoked at the same time by the same cache. This applies to different invocations of the same or different methods, on the same or different listeners registered with a single cache. For example, the serviceRemoved method of one listener will not be invoked while the invocation of another listener's serviceAdded, serviceRemoved, or serviceChanged method is in progress. Similarly, the one listener's serviceRemoved method will not be invoked while that same listener's serviceAdded, or serviceChanged method is in progress.

Note that the intent of the methods of this interface is to allow the recipient of the ServiceDiscoveryEvent to be informed that a service has been added to, removed from, or modified in the cache. Calls to these methods are synchronous to allow the entity that makes the call (for example, a thread that interacts with the various lookup services of interest) to determine whether or not the call succeeded. However, it is not part of the semantics of the call that the notification return can be delayed while the recipient of the call reacts to the occurrence of the event. Thus, it is highly recommended that implementations of this interface avoid time consuming operations, and return from the method as quickly as possible. For example, one strategy might be to simply note the occurrence of the ServiceDiscoveryEvent, and perform any time consuming event handling asynchronously.

Author:

Sun Microsystems, Inc.

See Also:

LookupCache, ServiceDiscoveryEvent

Method Summary

Modifier and Type	Method and Description
void	serviceAdded(ServiceDiscoveryEvent event) When the cache receives from one of the managed lookup services, an event signaling the registration of a service of interest for the first time (or for the first time since the service has been discarded), the cache invokes the serviceAdded method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that a service of interest has been discovered.
void	serviceChanged(ServiceDiscoveryEvent event) When the cache receives, from a managed lookup service, an event signaling the unique modification of the attributes of a service of interest (across the attribute sets of all references to the service), the cache invokes the serviceChanged method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that the state of a service of interest has changed.
void	serviceRemoved(ServiceDiscoveryEvent event) When the cache receives, from a managed lookup service, an event signaling the removal of a service of interest from the last such lookup service with which it was registered, the cache invokes the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that a service of interest has been discarded.

Method Detail

serviceAdded

void serviceAdded(ServiceDiscoveryEvent event)

When the cache receives from one of the managed lookup services, an event signaling the registration of a service of interest for the first time (or for the first time since the service has been discarded), the cache invokes the serviceAdded method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that a service of interest has been discovered.

Parameters:

event - an instance of ServiceDiscoveryEvent containing references to the service item corresponding to the event, including representations of the service's state both before and after the event.

serviceRemoved

void serviceRemoved(ServiceDiscoveryEvent event)

When the cache receives, from a managed lookup service, an event signaling the removal of a service of interest from the last such lookup service with which it was registered, the cache invokes the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that a service of interest has been discarded.

Parameters:

event - a ServiceDiscoveryEvent object containing references to the service item corresponding to the event, including representations of the service's state both before and after the event.

serviceChanged

void serviceChanged(ServiceDiscoveryEvent event)

When the cache receives, from a managed lookup service, an event signaling the unique modification of the attributes of a service of interest (across the attribute sets of all references to the service), the cache invokes the serviceChanged method on all instances of ServiceDiscoveryListener that are registered with the cache; doing so notifies the entity that the state of a service of interest has changed.

Parameters:

event - a ServiceDiscoveryEvent object containing references to the service item corresponding to the event, including representations of the service's state both before and after the event.