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 org.apache.river.outrigger.proxy;
19
20 import org.apache.river.landlord.Landlord;
21
22 import net.jini.lookup.ServiceProxyAccessor;
23
24 import java.rmi.MarshalledObject;
25 import java.rmi.NoSuchObjectException;
26 import java.rmi.Remote;
27 import java.rmi.RemoteException;
28
29 import net.jini.core.event.EventRegistration;
30 import net.jini.core.event.RemoteEventListener;
31 import net.jini.core.transaction.Transaction;
32 import net.jini.core.transaction.TransactionException;
33 import net.jini.core.transaction.server.TransactionParticipant;
34
35 import net.jini.id.Uuid;
36 import net.jini.space.InternalSpaceException;
37
38 /**
39 * This interface is the private wire protocol to the Outrigger
40 * implementations of JavaSpaces<sup>TM</sup>
41 * technology.
42 *
43 * @author Sun Microsystems, Inc.
44 *
45 * @see EntryRep
46 */
47 public interface OutriggerServer extends TransactionParticipant, Landlord,
48 OutriggerAdmin, ServiceProxyAccessor, Remote
49 {
50 /**
51 * Marker interface for objects that represent state
52 * that the server finds useful to share across sub-queries.
53 * @see #read
54 * @see #take
55 * @see #readIfExists
56 * @see #takeIfExists
57 */
58 interface QueryCookie {
59 }
60
61 /**
62 * Write a new entry into the space.
63 * @param entry The EntryRep representing the Entry.
64 * @param txn the Transaction.
65 * @param lease the lease duration.
66 * @return an array consisting of three long values, the lease duration,
67 * followed by the least significant bits, then the most significant bits
68 * of the EntryRep's Uuid.
69 * @throws RemoteException if a communication related exception occurs.
70 * @exception TransactionException A transaction error occurred
71 */
72 long[] write(EntryRep entry, Transaction txn, long lease)
73 throws TransactionException, RemoteException;
74
75 /**
76 * Find an entry in the space that matches the passed template and
77 * is visible to the passed transaction. Depending on the state of
78 * the space and the arguments this call may block if no entry can
79 * be immediately returned. The proxy can specify the maximum
80 * period it is willing to wait for a response using the
81 * <code>timeout</code> parameter. The proxy may choose to
82 * breakup a query from the client with a very long timeout into a
83 * set of <em>sub-queries</em>. In such cases it may get a
84 * <code>QueryCookie</code> as response to the sub-queries, in
85 * these cases it should pass the <code>QueryCookie</code> to the
86 * next sub-query (if any) associated with the same request from
87 * the client.
88 * <p>
89 * If a match is found it is returned as an <code>EntryRep</code>.
90 * If <code>txn</code> is non-<code>null</code> the
91 * entry is read locked by the transaction, this allows
92 * other queries to read, but not take the entry. The lock
93 * will be released when the transaction is aborted or prepared.
94 * <p>
95 * If no match is found the call will block for up to the
96 * specified timeout for a match to appear. If there
97 * is still no match available the call will return a
98 * <code>QueryCookie</code>.
99 *
100 * @param tmpl The template that describes the entry being
101 * searched for. May be <code>null</code> if
102 * any visible entry is acceptable.
103 * @param txn The transaction the operation should be
104 * performed under. Maybe be <code>null</code>.
105 * If non-null and entry is found it
106 * will read locked/removed under this
107 * transaction.
108 * @param timeout The maximum number of milliseconds this
109 * call should block in the server before
110 * returning an answer (this not necessarily
111 * the timeout the client asked for.) A value
112 * of 0 indicates the initial search should
113 * be performed, but if no match can be found
114 * <code>null</code> or a <code>QueryCookie</code>
115 * (as appropriate) should be returned immediately.
116 * @param cookie If this call is a continuation of
117 * an earlier query, the cookie from the
118 * last sub-query.
119 * @return an EntryRep if match found, otherwise it will return a QueryCookie
120 * @throws RemoteException if a network failure occurs.
121 * @throws TransactionException if there is a problem
122 * with the specified transaction such as
123 * it can not be joined, or leaves the active
124 * state before the call is complete.
125 * @throws InterruptedException if the thread in the server
126 * is interrupted before the query can be completed.
127 * @throws SecurityException if the server decides
128 * the caller has insufficient privilege to carry
129 * out the operation.
130 * @throws IllegalArgumentException if a negative timeout value is used
131 * @throws InternalSpaceException if there is an internal problem
132 * with the server.
133 */
134 Object read(EntryRep tmpl, Transaction txn, long timeout,
135 QueryCookie cookie)
136 throws TransactionException, RemoteException, InterruptedException;
137
138 /**
139 * Find an entry in the space that matches the passed template and
140 * is visible to the passed transaction. Depending on the state of
141 * the space and the arguments this call may block if no entry can
142 * be immediately returned. The proxy can specify the maximum
143 * period it is willing to wait for a response using the
144 * <code>timeout</code> parameter. The proxy may choose to
145 * breakup a query from the client with a very long timeout into a
146 * set of <em>sub-queries</em>. In such cases it may get a
147 * <code>QueryCookie</code> as response to the sub-queries, in
148 * these cases it should pass the <code>QueryCookie</code> to the
149 * next sub-query (if any) associated with the same request from
150 * the client.
151 * <p>
152 * If a match is found it is returned as an <code>EntryRep</code>.
153 * If <code>txn</code> is non-<code>null</code> the
154 * entry is read locked by the transaction, this allows
155 * other queries to read, but not take the entry. The lock
156 * will be released when the transaction is aborted or prepared.
157 * <p>
158 * If no match can be initially found the call will block until
159 * either the timeout expires or for a detectable period of time
160 * there are no entries in the space (visible to the transaction
161 * or not) that match the passed template. If at some point
162 * there are no matching entries in the space <code>null</code>
163 * will be returned. If the timeout expires and there are matching
164 * entries in the space but none are visible to the passed
165 * transaction a <code>QueryCookie</code> will be returned.
166 *
167 * @param tmpl The template that describes the entry being
168 * searched for. May be <code>null</code> if
169 * any visible entry is acceptable.
170 * @param txn The transaction the operation should be
171 * performed under. Maybe be <code>null</code>.
172 * If non-null and entry is found it
173 * will read locked/removed under this
174 * transaction.
175 * @param timeout The maximum number of milliseconds this
176 * call should block in the server before
177 * returning an answer (this not necessarily
178 * the timeout the client asked for.) A value
179 * of 0 indicates the initial search should
180 * be performed, but if no match can be found
181 * <code>null</code> or a <code>QueryCookie</code>
182 * (as appropriate) should be returned immediately.
183 * @param cookie If this call is a continuation of
184 * an earlier query, the cookie from the
185 * last sub-query.
186 * @return an EntryRep if a match is found, otherwise a QueryCookie
187 * @throws RemoteException if a network failure occurs.
188 * @throws TransactionException if there is a problem
189 * with the specified transaction such as
190 * it can not be joined, or leaves the active
191 * state before the call is complete.
192 * @throws InterruptedException if the thread in the server
193 * is interrupted before the query can be completed.
194 * @throws SecurityException if the server decides
195 * the caller has insufficient privilege to carry
196 * out the operation.
197 * @throws IllegalArgumentException if a negative timeout value is used
198 * @throws InternalSpaceException if there is an internal problem
199 * with the server.
200 */
201 Object readIfExists(EntryRep tmpl, Transaction txn, long timeout,
202 QueryCookie cookie)
203 throws TransactionException, RemoteException, InterruptedException;
204
205
206 /**
207 * Find and remove an entry in the space that matches the passed
208 * template and is visible to the passed transaction. Depending on
209 * the state of the space and the arguments this call may block if
210 * no entry can be immediately returned. The proxy can specify the
211 * maximum period it is willing to wait for a response using the
212 * <code>timeout</code> parameter. The proxy may choose to
213 * breakup a query from the client with a very long timeout into a
214 * set of <em>sub-queries</em>. In such cases it may get a
215 * <code>QueryCookie</code> as response to the sub-queries, in
216 * these cases it should pass the <code>QueryCookie</code> to the
217 * next sub-query (if any) associated with the same request from
218 * the client.
219 * <p>
220 * If a match is found it is returned as an <code>EntryRep</code>.
221 * If <code>txn</code> is <code>null</code> the entry is removed
222 * from the space. If <code>txn</code> is non-<code>null</code> the
223 * entry is exclusively locked by the transaction and will be removed
224 * from the space if the transaction is committed.
225 * <p>
226 * If no match is found the call will block for up to the
227 * specified timeout for a match to appear. If there
228 * is still no match available the call will return a
229 * <code>QueryCookie</code>.
230 *
231 * @param tmpl The template that describes the entry being
232 * searched for. May be <code>null</code> if
233 * any visible entry is acceptable.
234 * @param txn The transaction the operation should be
235 * performed under. Maybe be <code>null</code>.
236 * If non-null and entry is found it
237 * will read locked/removed under this
238 * transaction.
239 * @param timeout The maximum number of milliseconds this
240 * call should block in the server before
241 * returning an answer (this not necessarily
242 * the timeout the client asked for.) A value
243 * of 0 indicates the initial search should
244 * be performed, but if no match can be found
245 * <code>null</code> or a <code>QueryCookie</code>
246 * (as appropriate) should be returned immediately.
247 * @param cookie If this call is a continuation of
248 * an earlier query, the cookie from the
249 * last sub-query.
250 * @return an EntryRep if a match is found, otherwise returns a QueryCookie.
251 * @throws RemoteException if a network failure occurs.
252 * @throws TransactionException if there is a problem
253 * with the specified transaction such as
254 * it can not be joined, or leaves the active
255 * state before the call is complete.
256 * @throws InterruptedException if the thread in the server
257 * is interrupted before the query can be completed.
258 * @throws SecurityException if the server decides
259 * the caller has insufficient privilege to carry
260 * out the operation.
261 * @throws IllegalArgumentException if a negative timeout value is used
262 * @throws InternalSpaceException if there is an internal problem
263 * with the server.
264 */
265 Object take(EntryRep tmpl, Transaction txn, long timeout,
266 QueryCookie cookie)
267 throws TransactionException, RemoteException, InterruptedException;
268
269 /**
270 * Find and remove an entry in the space that matches the passed
271 * template and is visible to the passed transaction. Depending on
272 * the state of the space and the arguments this call may block if
273 * no entry can be immediately returned. The proxy can specify the
274 * maximum period it is willing to wait for a response using the
275 * <code>timeout</code> parameter. The proxy may choose to
276 * breakup a query from the client with a very long timeout into a
277 * set of <em>sub-queries</em>. In such cases it may get a
278 * <code>QueryCookie</code> as response to the sub-queries, in
279 * these cases it should pass the <code>QueryCookie</code> to the
280 * next sub-query (if any) associated with the same request from
281 * the client.
282 * <p>
283 * If a match is found it is returned as an <code>EntryRep</code>.
284 * If <code>txn</code> is <code>null</code> the entry is removed
285 * from the space. If <code>txn</code> is non-<code>null</code> the
286 * entry is exclusively locked by the transaction and will be removed
287 * from the space if the transaction is committed.
288 * <p>
289 * If no match can be initially found the call will block until
290 * either the timeout expires or for a detectable period of time
291 * there are no entries in the space (visible to the transaction
292 * or not) that match the passed template. If at some point there
293 * are no matching entries in the space <code>null</code> will be
294 * returned. If the timeout expires and there are matching entries
295 * in the space but none are visible to the passed transaction a
296 * <code>QueryCookie</code> will be returned.
297 *
298 * @param tmpl The template that describes the entry being
299 * searched for. May be <code>null</code> if
300 * any visible entry is acceptable.
301 * @param txn The transaction the operation should be
302 * performed under. Maybe be <code>null</code>.
303 * If non-null and entry is found it
304 * will read locked/removed under this
305 * transaction.
306 * @param timeout The maximum number of milliseconds this
307 * call should block in the server before
308 * returning an answer (this not necessarily
309 * the timeout the client asked for.) A value
310 * of 0 indicates the initial search should
311 * be performed, but if no match can be found
312 * <code>null</code> or a <code>QueryCookie</code>
313 * (as appropriate) should be returned immediately.
314 * @param cookie If this call is a continuation of
315 * an earlier query, the cookie from the
316 * last sub-query.
317 * @return an EntryRep if a match is found, otherwise returns a QueryCookie.
318 * @throws RemoteException if a network failure occurs.
319 * @throws TransactionException if there is a problem
320 * with the specified transaction such as
321 * it can not be joined, or leaves the active
322 * state before the call is complete.
323 * @throws InterruptedException if the thread in the server
324 * is interrupted before the query can be completed.
325 * @throws SecurityException if the server decides
326 * the caller has insufficient privilege to carry
327 * out the operation.
328 * @throws IllegalArgumentException if a negative timeout value is used
329 * @throws InternalSpaceException if there is an internal problem
330 * with the server.
331 */
332 Object takeIfExists(EntryRep tmpl, Transaction txn, long timeout,
333 QueryCookie cookie)
334 throws TransactionException, RemoteException, InterruptedException;
335
336 /**
337 * When entries are written that match this template notify the
338 * given <code>listener</code>. Matching is done as for <code>read</code>.
339 * @param tmpl template
340 * @param txn transaction
341 * @param listener listener
342 * @param lease lease duration in milliseconds
343 * @param handback MarshalledObject.
344 * @return the EventRegistration.
345 * @throws TransactionException if a transaction related exception occurs.
346 * @throws RemoteException if a communication related exception occurs.
347 */
348 EventRegistration
349 notify(EntryRep tmpl, Transaction txn, RemoteEventListener listener,
350 long lease, MarshalledObject handback)
351 throws TransactionException, RemoteException;
352
353 /**
354 * Write a set of entries into the space.
355 * @param entries array of entries to be written into the space.
356 * @param txn the Transaction
357 * @param leaseTimes for each EntryRep in entries at the same array index.
358 * @return an array of longs that can be used to construct the
359 * leases on the client side. The array will have 3
360 * elements for each lease, the first will be the
361 * duration, followed by the high order bits of the
362 * <code>Uuid</code> and then the lower order bits
363 * of the <code>Uuid</code>.
364 * @exception TransactionException A transaction error occurred
365 * @throws RemoteException if a connection related exception occurs.
366 */
367 long[] write(EntryRep[] entries, Transaction txn, long[] leaseTimes)
368 throws TransactionException, RemoteException;
369
370 /**
371 * Find and remove up to <code>limit</code> entries in the space
372 * that match one or more of the passed templates and are visible
373 * to the passed transaction. Depending on the state of the space
374 * and the arguments this call may block if no entry can be
375 * immediately returned. The proxy can specify the maximum period
376 * it is willing to wait for a response using the
377 * <code>timeout</code> parameter. The proxy may choose to
378 * breakup a query from the client with a very long timeout into a
379 * set of <em>sub-queries</em>. In such cases it may get a
380 * <code>QueryCookie</code> as response to the sub-queries, in
381 * these cases it should pass the <code>QueryCookie</code> to the
382 * next sub-query (if any) associated with the same request from
383 * the client.
384 * <p>
385 * If matchs are found they are returned as in an array of
386 * <code>EntryRep</code>. If <code>txn</code> is
387 * <code>null</code> the entries are removed from the space. If
388 * <code>txn</code> is non-<code>null</code> the entries are
389 * exclusively locked by the transaction and will be removed from
390 * the space if the transaction is committed.
391 * <p>
392 * If there are no matches the call will block for up to the
393 * specified timeout for a match to appear. If there is still no
394 * match available the call will return a
395 * <code>QueryCookie</code>.
396 *
397 * @param tmpls The templates that describes the entries being
398 * searched for
399 * @param tr The transaction the operation should be
400 * performed under. Maybe be <code>null</code>.
401 * If non-null and entries are found they
402 * will removed under this transaction.
403 * @param timeout The maximum number of milliseconds this
404 * call should block in the server before
405 * returning an answer (this not necessarily
406 * the timeout the client asked for.) A value
407 * of 0 indicates the initial search should
408 * be performed, but if no match can be found
409 * a <code>QueryCookie</code> should be
410 * returned immediately.
411 * @param limit The maximum number of entries that should be taken
412 * @param cookie If this call is a continuation of
413 * an earlier query, the cookie from the
414 * last sub-query.
415 * @return an array of EntryRep's if match is successful,
416 * otherwise a QueryCookie
417 * @throws RemoteException if a network failure occurs.
418 * @throws TransactionException if there is a problem
419 * with the specified transaction such as
420 * it can not be joined, or leaves the active
421 * state before the call is complete.
422 * @throws SecurityException if the server decides
423 * the caller has insufficient privilege to carry
424 * out the operation.
425 * @throws IllegalArgumentException if a negative timeout value is used
426 * or if a non-positive limit value is used
427 * @throws InternalSpaceException if there is an internal problem
428 * with the server.
429 */
430 Object take(EntryRep[] tmpls, Transaction tr, long timeout,
431 int limit, QueryCookie cookie)
432 throws TransactionException, RemoteException;
433
434 /**
435 * When entries that match one or more of the passed templates
436 * transition from invisible to visible notify the give
437 * <code>listener</code>. Matching is done as for
438 * <code>read</code>.
439 * @param tmpls the templates that specify what entries should
440 * generate events
441 * @param txn if non-<code>null</code> entries that become
442 * visible to <code>txn</code> should generate events even
443 * if <code>txn</code> is never committed. Registration is
444 * terminated when <code>txn</code> leaves the active state
445 * @param visibilityOnly if <code>true</code>, events will
446 * be generated for this registration only when a
447 * matching <code>Entry</code> transitions from
448 * invisible to visible, otherwise events will be
449 * generated when a matching <code>Entry</code>
450 * makes any transition from unavailable to
451 * available
452 * @param listener object to notify when an entry becomes (re)visible
453 * @param leaseTime initial requested lease time for the registration
454 * @param handback object to be included with every notification
455 * @return An object with information on the registration
456 * @throws TransactionException if <code>txn</code> is
457 * non-<code>null</code> and not active or otherwise invalid
458 * @throws RemoteException if a connection related exception occurs.
459 */
460 EventRegistration registerForAvailabilityEvent(EntryRep[] tmpls,
461 Transaction txn, boolean visibilityOnly,
462 RemoteEventListener listener, long leaseTime,
463 MarshalledObject handback)
464 throws TransactionException, RemoteException;
465
466 /**
467 * Start a new contents query. Returns a
468 * <code>MatchSetData</code> with the initial batch of
469 * entries and (if applicable) the <code>Uuid</code> and initial
470 * lease duration. If the entire result set is contained in the
471 * returned <code>MatchSetData</code> the <code>Uuid</code>
472 * will be <code>null</code> and the lease duration will be
473 * -<code>1</code>.
474 * @param tmpls the templates to use for the iteration
475 * @param tr the transaction to perform the iteration under,
476 * may be <code>null</code>
477 * @param leaseTime the requested lease time
478 * @param limit the maximum number of entries to return
479 * @return A <code>MatchSetData</code> with the initial batch
480 * of entries and (if applicable) the <code>Uuid</code> and initial
481 * lease duration. Initial batch will be the empty array if
482 * there are no matching entries in the space
483 * @throws TransactionException if
484 * <code>tr</code> is non-<code>null</code> and can't be used
485 * @throws IllegalArgumentException if limit is non-positive or
486 * leaseTime is less than -1
487 * @throws NullPointerException if tmpls is <code>null</code>
488 * @throws RemoteException if a communication related exception occurs.
489 */
490 public MatchSetData contents(EntryRep[] tmpls, Transaction tr,
491 long leaseTime, long limit)
492 throws TransactionException, RemoteException;
493
494
495 /**
496 * Return the next batch of entries associated with the specified
497 * contents query. If the returned array is not full then the
498 * query is complete.
499 * @param contentsQueryUuid the id of the contents query
500 * @param entryUuid the id of the last entry in the last batch.
501 * If this does not match what the server has on recored
502 * it will re-send the previous batch.
503 * @return an array of <code>EntryRep</code>s representing
504 * the next batch of entries from the query. Query
505 * is complete if array is not full. Returns an empty
506 * array if there are no entries left
507 * @throws NoSuchObjectException if the server has no record
508 * of <code>contentsQueryUuid</code>
509 */
510 public EntryRep[] nextBatch(Uuid contentsQueryUuid, Uuid entryUuid)
511 throws RemoteException;
512
513
514 /**
515 * Return the admin proxy for this space.
516 * @return the admin proxy.
517 * @throws RemoteException if a communication problem occurs.
518 */
519 Object getAdmin() throws RemoteException;
520 }