net.jini.lookup

Interface ServiceItemFilter

public interface ServiceItemFilter

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

Author:

Sun Microsystems, Inc.

See Also:

ServiceDiscoveryManager

Method Summary

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.

Method Detail

check

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

• If the input object satisfies any additional matching criteria that are specified, and if the proxy is successfully prepared (when requested), then this method returns 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.
• If either the input object does not satisfy any additional matching criteria that are specified, or if proxy preparation is requested but fails because of a definite exception (such as a 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.
• If the input object satisfies any additional matching criteria that are specified, and proxy preparation is requested but fails because of an indefinite exception (such as a 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.

Parameters:

item - the ServiceItem object to test against the additional criteria.

Returns:

false if the input object fails the filter; true otherwise (see the method description above).