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 package net.jini.core.lookup;
19
20 import java.rmi.MarshalledObject;
21 import java.rmi.RemoteException;
22 import net.jini.core.discovery.LookupLocator;
23 import net.jini.core.event.EventRegistration;
24 import net.jini.core.event.RemoteEventListener;
25 import net.jini.io.MarshalledInstance;
26
27 /**
28 * Defines the interface to the lookup service. The interface is not a
29 * remote interface; each implementation of the lookup service exports
30 * proxy objects that implement the ServiceRegistrar interface local to
31 * the client, using an implementation-specific protocol to communicate
32 * with the actual remote server. All of the proxy methods obey normal
33 * RMI remote interface semantics except where explicitly noted. Two
34 * proxy objects are equal if they are proxies for the same lookup service.
35 * Every method invocation (on both ServiceRegistrar and ServiceRegistration)
36 * is atomic with respect to other invocations.
37 *
38 * @author Sun Microsystems, Inc.
39 *
40 * @see ServiceRegistration
41 *
42 * @since 1.0
43 */
44 public interface ServiceRegistrar {
45
46 /**
47 * Register a new service or re-register an existing service. The method
48 * is defined so that it can be used in an idempotent fashion.
49 * Specifically, if a call to register results in a RemoteException (in
50 * which case the item might or might not have been registered), the
51 * caller can simply repeat the call to register with the same parameters,
52 * until it succeeds.
53 * <p>
54 * To register a new service, item.serviceID should be null. In that
55 * case, if item.service does not equal (using MarshalledObject.equals)
56 * any existing item's service object, then a new service ID will be
57 * assigned and included in the returned ServiceRegistration. The
58 * service ID is unique over time and space with respect to all other
59 * service IDs generated by all lookup services. If item.service does
60 * equal an existing item's service object, the existing item is first
61 * deleted from the lookup service (even if it has different attributes)
62 * and its lease is cancelled, but that item's service ID is reused for
63 * the newly registered item.
64 * <p>
65 * To re-register an existing service, or to register the service in any
66 * other lookup service, item.serviceID should be set to the same service
67 * ID that was returned by the initial registration. If an item is
68 * already registered under the same service ID, the existing item is
69 * first deleted (even if it has different attributes or a different
70 * service instance) and its lease is cancelled. Note that service
71 * object equality is not checked in this case, to allow for reasonable
72 * evolution of the service (e.g., the serialized form of the stub
73 * changes, or the service implements a new interface).
74 * <p>
75 * Any duplicate attribute sets included in a service item are eliminated
76 * in the stored representation of the item. The lease duration request
77 * is not exact; the returned lease is allowed to have a shorter (but not
78 * longer) duration than what was requested. The registration is
79 * persistent across restarts (crashes) of the lookup service until the
80 * lease expires or is cancelled.
81 *
82 * @param item service item to register
83 * @param leaseDuration requested lease duration, in milliseconds
84 * @return a ServiceRegistration in this lookup service for the specified
85 * service item
86 * @throws java.rmi.RemoteException if a connection problem occurs.
87 */
88 ServiceRegistration register(ServiceItem item, long leaseDuration)
89 throws RemoteException;
90
91 /**
92 * Returns the service object (i.e., just ServiceItem.service) from an
93 * item matching the template, or null if there is no match. If multiple
94 * items match the template, it is arbitrary as to which service object
95 * is returned. If the returned object cannot be deserialized, an
96 * UnmarshalException is thrown with the standard RMI semantics.
97 *
98 * @param tmpl template to match
99 * @return an object that represents a service that matches the
100 * specified template
101 * @throws java.rmi.RemoteException if a connection problem occurs.
102 */
103 Object lookup(ServiceTemplate tmpl) throws RemoteException;
104
105 /**
106 * Returns at most maxMatches items matching the template, plus the total
107 * number of items that match the template. The return value is never
108 * null, and the returned items array is only null if maxMatches is zero.
109 * For each returned item, if the service object cannot be deserialized,
110 * the service field of the item is set to null and no exception is
111 * thrown. Similarly, if an attribute set cannot be deserialized, that
112 * element of the attributeSets array is set to null and no exception
113 * is thrown.
114 *
115 * @param tmpl template to match
116 * @param maxMatches maximum number of matches to return
117 * @return a ServiceMatches instance that contains at most maxMatches
118 * items matching the template, plus the total number of items
119 * that match the template. The return value is never null, and
120 * the returned items array is only null if maxMatches is zero.
121 * @throws java.rmi.RemoteException if a connection problem occurs.
122 */
123 ServiceMatches lookup(ServiceTemplate tmpl, int maxMatches)
124 throws RemoteException;
125
126 /**
127 * An event is sent when the changed item matches the template before
128 * the operation, but doesn't match the template after the operation
129 * (this includes deletion of the item).
130 */
131 int TRANSITION_MATCH_NOMATCH = 1 << 0;
132
133 /**
134 * An event is sent when the changed item doesn't match the template
135 * before the operation (this includes not existing), but does match
136 * the template after the operation.
137 */
138 int TRANSITION_NOMATCH_MATCH = 1 << 1;
139
140 /**
141 * An event is sent when the changed item matches the template both
142 * before and after the operation.
143 */
144 int TRANSITION_MATCH_MATCH = 1 << 2;
145
146 /**
147 * Registers for event notification. The registration is leased; the
148 * lease expiration request is not exact. The registration is persistent
149 * across restarts (crashes) of the lookup service until the lease expires
150 * or is cancelled. The event ID in the returned EventRegistration is
151 * unique at least with respect to all other active event registrations
152 * in this lookup service with different service templates or transitions.
153 * <p>
154 * While the event registration is in effect, a ServiceEvent is sent to
155 * the specified listener whenever a register, lease cancellation or
156 * expiration, or attribute change operation results in an item changing
157 * state in a way that satisfies the template and transition combination.
158 *
159 * @param tmpl template to match
160 * @param transitions bitwise OR of any non-empty set of transition values
161 * @param listener listener to send events to
162 * @param handback object to include in every ServiceEvent generated
163 * @param leaseDuration requested lease duration
164 * @return an EventRegistration object to the entity that registered the
165 * specified remote listener
166 * @throws java.rmi.RemoteException if a connection problem occurs.
167 */
168 @Deprecated
169 EventRegistration notify(ServiceTemplate tmpl,
170 int transitions,
171 RemoteEventListener listener,
172 MarshalledObject handback,
173 long leaseDuration)
174 throws RemoteException;
175
176 /**
177 * Looks at all service items that match the specified template, finds
178 * every entry (among those service items) that either doesn't match any
179 * entry templates or is a subclass of at least one matching entry
180 * template, and returns the set of the (most specific) classes of those
181 * entries. Duplicate classes are eliminated, and the order of classes
182 * within the returned array is arbitrary. Null (not an empty array) is
183 * returned if there are no such entries or no matching items. If a
184 * returned class cannot be deserialized, that element of the returned
185 * array is set to null and no exception is thrown.
186 *
187 * @param tmpl template to match
188 * @return an array of entry Classes (attribute sets) for every service
189 * that matches the specified template
190 * @throws java.rmi.RemoteException if a connection problem occurs.
191 */
192 Class[] getEntryClasses(ServiceTemplate tmpl) throws RemoteException;
193
194 /**
195 * Looks at all service items that match the specified template, finds
196 * every entry (among those service items) that matches
197 * tmpl.attributeSetTemplates[setIndex], and returns the set of values
198 * of the specified field of those entries. Duplicate values are
199 * eliminated, and the order of values within the returned array is
200 * arbitrary. Null (not an empty array) is returned if there are no
201 * matching items. If a returned value cannot be deserialized, that
202 * element of the returned array is set to null and no exception is
203 * thrown.
204 *
205 * @param tmpl template to match
206 * @param setIndex index into tmpl.attributeSetTemplates
207 * @param field name of field of tmpl.attributeSetTemplates[setIndex]
208 *
209 * @return an array of objects that represents field values of entries
210 * associated with services that meet the specified matching
211 * criteria
212 *
213 * @throws NoSuchFieldException field does not name a field of the
214 * entry template
215 * @throws java.rmi.RemoteException if a connection problem occurs.
216 */
217 Object[] getFieldValues(ServiceTemplate tmpl, int setIndex, String field)
218 throws NoSuchFieldException, RemoteException;
219
220 /**
221 * Looks at all service items that match the specified template, and for
222 * every service item finds the most specific type (class or interface)
223 * or types the service item is an instance of that are neither equal to,
224 * nor a superclass of, any of the service types in the template and that
225 * have names that start with the specified prefix, and returns the set
226 * of all such types. Duplicate types are eliminated, and the order of
227 * types within the returned array is arbitrary. Null (not an empty
228 * array) is returned if there are no such types. If a returned type
229 * cannot be deserialized, that element of the returned array is set to
230 * null and no exception is thrown.
231 *
232 * @param tmpl template to match
233 * @param prefix class name prefix
234 *
235 * @return an array of Classes of all services that either match the
236 * specified template or match the specified prefix
237 * @throws java.rmi.RemoteException if a connection problem occurs.
238 */
239 Class[] getServiceTypes(ServiceTemplate tmpl, String prefix)
240 throws RemoteException;
241
242 /**
243 * Returns the service ID of the lookup service. Note that this does not
244 * make a remote call. A lookup service is always registered with itself
245 * under this service ID, and if a lookup service is configured to
246 * register itself with other lookup services, it will register with all
247 * of them using this same service ID.
248 *
249 * @return the service ID of the lookup service.
250 */
251 ServiceID getServiceID();
252
253 /**
254 * Returns a LookupLocator that can be used if necessary for unicast
255 * discovery of the lookup service.
256 *
257 * @return a LookupLocator that can be used for unicast discovery of
258 * the lookup service, if necessary.
259 * @throws java.rmi.RemoteException when a connection problem occurs.
260 */
261 LookupLocator getLocator() throws RemoteException;
262
263 /**
264 * Returns the set of groups that this lookup service is currently a
265 * member of.
266 *
267 * @return a String array of groups that this lookup service is currently
268 * a member of.
269 * @throws java.rmi.RemoteException when a connection problem occurs.
270 */
271 String[] getGroups() throws RemoteException;
272 }