public interface ServiceItemFilter
ServiceItemFilter interface defines the methods used by an object such as the
ServiceDiscoveryManager or the LookupCache to apply additional selection criteria when searching
for services in which an entity has registered interest. It is the responsibility of the entity
requesting the application of additional criteria to construct an implementation of this
interface that defines the additional criteria, and to pass the resulting object (referred to as
a filter) into the object that will apply it. The filtering mechanism provided by implementations of this interface is particularly useful to entities that wish to extend the capabilities of the standard template matching scheme. For example, because template matching does not allow one to search for services based on a range of attribute values, this additional matching mechanism can be exploited by the entity to ask the managing object to find all registered printer services that have a resolution attribute between say, 300 dpi and 1200 dpi.
In addition to (or instead of) applying additional matching criteria to candidate service
proxies initially found through template matching, this filtering mechanism can also be used to
extend the selection process so that only proxies that are safe to use are returned to the
entity. To do this, the entity would use this interface to supply the ServiceDiscoveryManager or LookupCache with a filter that, when applied to a candidate proxy,
performs a set of operations that is referred to as proxy preparation. As described in the
documentation for ProxyPreparer, proxy preparation typically includes
operations such as, verifying trust in the proxy, specifying client constraints, and dynamically
granting necessary permissions to the proxy.
BackwardsServiceDiscoveryManager| Modifier and Type | Method and Description |
|---|---|
boolean |
check(ServiceItem item)
This method defines the implementation of the additional selection criteria (additional
matching and/or proxy preparation) to apply to a
ServiceItem object found through standard template matching. |
boolean check(ServiceItem item)
ServiceItem object found through standard template matching. This method takes one argument:
the ServiceItem object to test against the
additional criteria. Neither a null reference nor a ServiceItem object containing null fields will
be passed to this method by the ServiceDiscoveryManager or the LookupCache.
If the
parameter passed to this method is a ServiceItem
object that has non-null fields but is associated with attribute sets containing
null entries, then this method must process that parameter in a reasonable
manner.
Note that although this method returns a boolean, there are actually
three possible return states that can occur. Those states are classified by the value of the
returned boolean in combination with the (possibly modified) contents of the
ServiceItem object that was input to this method.
The three possible return states can be summarized as follows:
true and the
service field of the ServiceItem parameter is either
left unchanged (when proxy preparation is not requested) or is replaced with
the prepared proxy. When this state is returned by this method, it is said that the object
passed (the check method of) the filter; or that the filter returned a
pass condition. SecurityException, then this method returns false. When this state is returned
by this method, it is said that the object failed (the check method of)
the filter; or that the filter returned a failure condition. RemoteException), then this method returns true and
the service field of the ServiceItem parameter is
replaced with null. In this case, the object has neither passed
nor failed the filter. Thus, when this state is returned by this method, it is said that the
results of the filtering process are indefinite. With respect to a remote
operation such as proxy preparation, the term indefinite exception refers to a class
of exception where any such exception does not allow assertions to be made about the
probability of success (or failure) of future attempts to prepare the proxy. A RemoteException caused by a transient communciation failure is one
such example of an exception that can be classified as an indefinite exception. Thus,
whenever this method returns an indefinite result, the object that invoked this method
(either ServiceDiscoveryManager or
LookupCache) will retry the filter by calling this method
again, at a later time, when success may be possible.
Alternatively, the term definite
exception refers to a class of exception where any such exception is indicative of a
permanent failure. That is, when an operation fails as a result of an exception
that can be classified as a definite exception, that exception allows one to assert that any
future attempts to perform the failed operation will also be met with failure. A SecurityException is an example of a definite exception in the
case of proxy preparation. Thus, when this method results in failure, that failure occurs
either because the object being filtered does not currently match the given criteria, or a
definite exception occurs as a result of proxy preparation (or both). In either case, because
it is a virtual certainty that failure will again result on all future attempts to filter the
object (that is, perform matching and/or proxy preparation), no attempt is made to retry the
operation.
Except for the modifications that may result from filtering as described
above, this method must not modify any other aspect of the contents of the input ServiceItem object because doing so can result in
unpredictable and undesirable effects on future processing by the ServiceDiscoveryManager. Therefore, the
effects of such modifications are undefined.
item - the ServiceItem object to test against the additional criteria.false if the input object fails the filter; true otherwise
(see the method description above).Copyright © GigaSpaces.