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>LookupCache</code> interface defines the methods provided
25 * by the object created and returned by the
26 * {@link net.jini.lookup.ServiceDiscoveryManager ServiceDiscoveryManager}
27 * when a client-like entity invokes the
28 * {@link net.jini.lookup.ServiceDiscoveryManager#createLookupCache
29 * createLookupCache} method. It is within the object returned by that
30 * method that discovered service references, matching criteria defined
31 * by the entity, are stored. Through this interface, the entity may
32 * retrieve one or more of the stored service references, register and
33 * un-register with the cache's event mechanism, discard previously
34 * discovered service references to make them eligible for re-discovery,
35 * and terminate all of the cache's processing.
36 *
37 * @author Sun Microsystems, Inc.
38 *
39 * @see ServiceDiscoveryManager
40 */
41 public interface LookupCache {
42 /**
43 * Finds a <code>ServiceItem</code> object that satisfies the given
44 * <code>filter</code> parameter.
45 * <p>
46 * The service item returned must have been previously discovered to
47 * be both registered with one or more of the lookup services in the
48 * managed set, and to match criteria defined by the entity.
49 * <p>
50 * The semantics of the <code>filter</code> argument are identical
51 * to those of the <code>filter</code> argument specified for a
52 * number of the methods defined in the interface of the
53 * <code>ServiceDiscoveryManager</code> utility class. This argument
54 * is intended to allow an entity to separate its filtering into two
55 * steps: an initial filter applied during the discovery phase, and
56 * a finer resolution filter applied upon retrieval from the cache.
57 * As with the methods of the <code>ServiceDiscoveryManager</code>, if
58 * <code>null</code> is the value of this argument, then no additional
59 * filtering will be performed.
60 *
61 * @param filter used for matching <code>ServiceItem</code>s. A null
62 * value means no additional filtering should be applied.
63 *
64 * @return ServiceItem that satisfies the filter, and that was
65 * previously discovered to be registered with one
66 * or more lookup services in the managed set. A
67 * <code>null</code> value will be returned if no
68 * <code>ServiceItem</code> is found that matches
69 * the criteria or if the cache is empty.
70 */
71 public ServiceItem lookup(ServiceItemFilter filter);
72
73 /**
74 * Finds an array of instances of <code>ServiceItem</code> that each
75 * satisfy the given <code>filter</code> parameter.
76 * <p>
77 * Each service item contained in the returned array must have been
78 * previously discovered to be both registered with one or more of the
79 * lookup services in the managed set, and to match criteria defined
80 * by the entity.
81 * <p>
82 * The semantics of the <code>filter</code> argument are
83 * identical to those of the <code>filter</code> argument specified
84 * for a number of the methods defined in the interface of the
85 * <code>ServiceDiscoveryManager</code> utility class. This argument is
86 * intended to allow an entity to separate its filtering into two
87 * steps: an initial filter applied during the discovery phase, and
88 * a finer resolution filter applied upon retrieval from the cache.
89 * As with the methods of the <code>ServiceDiscoveryManager</code>, if
90 * <code>null</code> is the value of this argument, then no
91 * additional filtering will be performed.
92 *
93 * @param filter used for matching <code>ServiceItem</code>s.
94 * A null value means no additional filtering should
95 * be applied.
96 *
97 * @param maxMatches maximum number of matches to return. If this
98 * value is set to <code>Integer.MAX_VALUE</code>
99 * then all elements in the cache that match the
100 * criteria will be returned.
101 *
102 * @return ServiceItem[] array whose elements each satisfy the filter,
103 * and that were previously discovered to be
104 * registered with one or more lookup services in
105 * the managed set. An empty array will be returned
106 * if no <code>ServiceItem</code> is found that
107 * matches the criteria or if the cache is empty.
108 *
109 * @throws java.lang.IllegalArgumentException if <code>maxMatches</code>
110 * is a negative number.
111 */
112 public ServiceItem[] lookup(ServiceItemFilter filter, int maxMatches);
113
114 /**
115 * Registers a <code>ServiceDiscoveryListener</code> object with
116 * the event mechanism of a <code>LookupCache</code>. The listener
117 * object will receive a <code>ServiceDiscoveryEvent</code> upon the
118 * discovery, removal, or modification of one of the cache's
119 * services. Once a listener is registered, it will be notified of
120 * all service references discovered to date, and will be notified as
121 * new services are discovered and existing services are modified or
122 * discarded.
123 *
124 * If the parameter value duplicates (using <code>equals</code>) another
125 * element in the set of listeners, no action is taken. If the parameter
126 * value is <code>null</code>, a <code>NullPointerException</code> is
127 * thrown.
128 *
129 * @param listener the <code>ServiceDiscoveryListener</code> object to
130 * register.
131 *
132 * @throws java.lang.NullPointerException this exception occurs when
133 * <code>null</code> is input to the <code>listener</code>
134 * parameter.
135 * @see #removeListener
136 *
137 */
138 public void addListener(ServiceDiscoveryListener listener);
139
140 /**
141 * Removes a <code>ServiceDiscoveryListener</code> object from the set
142 * of listeners currently registered with the <code>LookupCache</code>.
143 * Once all listeners are removed from the cache's set of listeners,
144 * the cache will send no more <code>ServiceDiscoveryEvent</code>
145 * notifications.
146 *
147 * If the parameter value is <code>null</code>, or if the parameter value
148 * does not exist in the managed set of listeners, no action is taken.
149 *
150 * @param listener the <code>ServiceDiscoveryListener</code> object to
151 * remove.
152 * @see #addListener
153 */
154 public void removeListener(ServiceDiscoveryListener listener);
155
156 /**
157 * Deletes a service reference from the cache and causes a notification
158 * to be sent to all registered listeners indicating that the service
159 * has been discarded.
160 *
161 * @param serviceReference the service reference to discard.
162 */
163 public void discard(Object serviceReference);
164
165 /**
166 * Performs cleanup duties related to the termination of
167 * the processing being performed by a particular instance of
168 * <code>LookupCache</code>. For that instance, this method cancels
169 * all event leases granted by the lookup services that supplied the
170 * contents of the cache, and un-exports all remote listener objects
171 * registered with those lookup services. The <code>terminate</code>
172 * method is typically called when the entity is no longer interested
173 * in the contents of the <code>LookupCache</code>.
174 */
175 void terminate();
176 }