1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package net.jini.lookup;
20
21 import net.jini.core.lookup.ServiceItem;
22
23 /**
24 * The <code>ServiceItemFilter</code> interface defines the methods used by
25 * an object such as the {@link net.jini.lookup.ServiceDiscoveryManager
26 * ServiceDiscoveryManager} or the {@link net.jini.lookup.LookupCache
27 * LookupCache} to apply additional selection criteria when searching for
28 * services in which an entity has registered interest. It is the
29 * responsibility of the entity requesting the application of additional
30 * criteria to construct an implementation of this interface that defines
31 * the additional criteria, and to pass the resulting object (referred to
32 * as a <i>filter</i>) into the object that will apply it.
33 * <p>
34 * The filtering mechanism provided by implementations of this interface is
35 * particularly useful to entities that wish to extend the capabilities of
36 * the standard template matching scheme. For example, because template
37 * matching does not allow one to search for services based on a range of
38 * attribute values, this additional matching mechanism can be exploited by
39 * the entity to ask the managing object to find all registered printer
40 * services that have a resolution attribute between say, 300 dpi and
41 * 1200 dpi.
42 * <p>
43 * In addition to (or instead of) applying additional matching criteria to
44 * candidate service proxies initially found through template matching, this
45 * filtering mechanism can also be used to extend the selection process so
46 * that only proxies that are <i>safe</i> to use are returned to the entity.
47 * To do this, the entity would use this interface to supply the
48 * {@link net.jini.lookup.ServiceDiscoveryManager ServiceDiscoveryManager}
49 * or {@link net.jini.lookup.LookupCache LookupCache} with a filter that,
50 * when applied to a candidate proxy, performs a set of operations that
51 * is referred to as <i>proxy preparation</i>. As described in the
52 * documentation for {@link net.jini.security.ProxyPreparer}, proxy
53 * preparation typically includes operations such as, verifying trust
54 * in the proxy, specifying client constraints, and dynamically granting
55 * necessary permissions to the proxy.
56 *
57 * @author Sun Microsystems, Inc.
58 *
59 * @see ServiceDiscoveryManager
60 */
61 public interface ServiceItemFilter {
62
63 /**
64 * <p>
65 * This method defines the implementation of the additional selection
66 * criteria (additional matching and/or proxy preparation) to apply to a
67 * {@link net.jini.core.lookup.ServiceItem ServiceItem} object found
68 * through standard template matching. This method takes one argument:
69 * the {@link net.jini.core.lookup.ServiceItem ServiceItem} object to
70 * test against the additional criteria.</p>
71 * <p>
72 * Neither a <code>null</code> reference nor a
73 * {@link net.jini.core.lookup.ServiceItem ServiceItem} object containing
74 * <code>null</code> fields will be passed to this method by the
75 * {@link net.jini.lookup.ServiceDiscoveryManager ServiceDiscoveryManager}
76 * or the {@link net.jini.lookup.LookupCache LookupCache}.</p>
77 * <p>
78 * If the parameter passed to this method is a
79 * {@link net.jini.core.lookup.ServiceItem ServiceItem} object that has
80 * non-<code>null</code> fields but is associated with attribute sets
81 * containing <code>null</code> entries, then this method must process
82 * that parameter in a reasonable manner.</p>
83 * <p>
84 * Note that although this method returns a <code>boolean</code>, there
85 * are actually three possible return states that can occur. Those states
86 * are classified by the value of the returned <code>boolean</code> in
87 * combination with the (possibly modified) contents of the
88 * {@link net.jini.core.lookup.ServiceItem ServiceItem} object that was
89 * input to this method. The three possible return states can be
90 * summarized as follows:
91 * </p>
92 * <ul>
93 * <li> If the input object satisfies any additional matching criteria
94 * that are specified, and if the proxy is successfully prepared
95 * (when requested), then this method returns <code>true</code>
96 * and the service field of the
97 * {@link net.jini.core.lookup.ServiceItem ServiceItem} parameter
98 * is either left unchanged (when proxy preparation is not
99 * requested) or is <b><i>replaced</i></b> with the prepared proxy.
100 * When this state is returned by this method, it is said that the
101 * object <i>passed</i> (the <code>check</code> method of) the
102 * filter; or that the filter returned a <i>pass</i> condition.
103 * <li> If either the input object does not satisfy any additional
104 * matching criteria that are specified, or if proxy preparation
105 * is requested but fails because of a <i>definite exception</i>
106 * (such as a {@link java.lang.SecurityException SecurityException},
107 * then this method returns <code>false</code>. When this state is
108 * returned by this method, it is said that the object
109 * <i>failed</i> (the <code>check</code> method of) the filter;
110 * or that the filter returned a <i>failure</i> condition.
111 * <li> If the input object satisfies any additional matching criteria
112 * that are specified, and proxy preparation is requested but
113 * fails because of an <i>indefinite exception</i> (such as a
114 * {@link java.rmi.RemoteException RemoteException}), then this
115 * method returns <code>true</code> and the service field of the
116 * {@link net.jini.core.lookup.ServiceItem ServiceItem} parameter
117 * is <b><i>replaced</i></b> with <code>null</code>. In this case,
118 * the object has neither passed nor failed the filter. Thus, when
119 * this state is returned by this method, it is said that the
120 * results of the filtering process are <i>indefinite</i>.
121 * </ul>
122 * <p>
123 * With respect to a remote operation such as proxy preparation, the
124 * term <i>indefinite exception</i> refers to a class of exception where
125 * any such exception does not allow assertions to be made about the
126 * probability of success (or failure) of future attempts to prepare the
127 * proxy. A {@link java.rmi.RemoteException RemoteException} caused by a
128 * transient communciation failure is one such example of an exception
129 * that can be classified as an indefinite exception. Thus, whenever
130 * this method returns an indefinite result, the object that invoked
131 * this method (either {@link net.jini.lookup.ServiceDiscoveryManager
132 * ServiceDiscoveryManager} or {@link net.jini.lookup.LookupCache
133 * LookupCache}) will retry the filter by calling this method again,
134 * at a later time, when success may be possible.
135 * <p>
136 * Alternatively, the term <i>definite exception</i> refers to a
137 * class of exception where any such exception is indicative of a
138 * <b><i>permanent</i></b> failure. That is, when an operation fails
139 * as a result of an exception that can be classified as a definite
140 * exception, that exception allows one to assert that any future
141 * attempts to perform the failed operation will also be met with failure.
142 * A {@link java.lang.SecurityException SecurityException} is an example
143 * of a definite exception in the case of proxy preparation. Thus, when
144 * this method results in failure, that failure occurs either because
145 * the object being filtered does not currently match the given
146 * criteria, or a definite exception occurs as a result of proxy
147 * preparation (or both). In either case, because it is a virtual
148 * certainty that failure will again result on all future attempts to
149 * filter the object (that is, perform matching and/or proxy preparation),
150 * no attempt is made to retry the operation.
151 * <p>
152 * Except for the modifications that may result from filtering as
153 * described above, this method must not modify any other aspect
154 * of the contents of the input {@link net.jini.core.lookup.ServiceItem
155 * ServiceItem} object because doing so can result in unpredictable and
156 * undesirable effects on future processing by the
157 * {@link net.jini.lookup.ServiceDiscoveryManager ServiceDiscoveryManager}.
158 * Therefore, the effects of such modifications are undefined.
159 *
160 * @param item the <code>ServiceItem</code> object to test against the
161 * additional criteria.
162 *
163 * @return <code>false</code> if the input object fails the filter;
164 * <code>true</code> otherwise (see the method description above).
165 */
166 boolean check(ServiceItem item);
167 }