public interface ServiceDiscoveryListener
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:
MarshalledInstance.fullyEquals
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.
LookupCache,
ServiceDiscoveryEvent| 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. |
void serviceAdded(ServiceDiscoveryEvent event)
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.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.void serviceRemoved(ServiceDiscoveryEvent event)
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.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.void serviceChanged(ServiceDiscoveryEvent event)
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.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.Copyright © GigaSpaces.