Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

See Also:
  `LookupCache`, `ServiceDiscoveryEvent`

Method Summary
`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

    public 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

    public 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

    public 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved