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.
ServiceDiscoveryManager| 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 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.