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

See Also:
  `ServiceDiscoveryManager`

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

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

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