1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
\r
3 * in Industry THTH ry.
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.db;
\r
14 import java.util.Collection;
\r
16 import org.simantics.db.exception.DatabaseException;
\r
17 import org.simantics.db.procedure.AsyncListener;
\r
18 import org.simantics.db.procedure.AsyncMultiListener;
\r
19 import org.simantics.db.procedure.AsyncMultiProcedure;
\r
20 import org.simantics.db.procedure.AsyncProcedure;
\r
21 import org.simantics.db.procedure.Listener;
\r
22 import org.simantics.db.procedure.MultiListener;
\r
23 import org.simantics.db.procedure.MultiProcedure;
\r
24 import org.simantics.db.procedure.Procedure;
\r
25 import org.simantics.db.procedure.SyncListener;
\r
26 import org.simantics.db.procedure.SyncMultiListener;
\r
27 import org.simantics.db.procedure.SyncMultiProcedure;
\r
28 import org.simantics.db.procedure.SyncProcedure;
\r
29 import org.simantics.db.request.AsyncMultiRead;
\r
30 import org.simantics.db.request.AsyncRead;
\r
31 import org.simantics.db.request.DelayedWrite;
\r
32 import org.simantics.db.request.DelayedWriteResult;
\r
33 import org.simantics.db.request.ExternalRead;
\r
34 import org.simantics.db.request.MultiRead;
\r
35 import org.simantics.db.request.Read;
\r
36 import org.simantics.db.request.Write;
\r
37 import org.simantics.db.request.WriteOnly;
\r
38 import org.simantics.db.request.WriteOnlyResult;
\r
39 import org.simantics.db.request.WriteResult;
\r
43 * For initiating requests in synchronous manner. The possible requests are
\r
45 * <li>{@link Read} for computing a single result synchronously
\r
46 * <li>{@link AsyncRead} for computing a single result asynchronously
\r
47 * <li>{@link MultiRead} for computing a collection of results synchronously
\r
48 * <li>{@link AsyncMultiRead} for computing a collection of results
\r
50 * <li>{@link Write} for reading and writing synchronously
\r
51 * <li>{@link WriteOnly} for writing synchronously
\r
54 * The standard RequestProcessors are
\r
56 * <li>{@link ReadGraph} for performing requests during other requests
\r
57 * <li>{@link Session} for initiating a transactions for performing requests
\r
58 * <li>{@link MergingGraphRequestProcessor} for merging several requests in a
\r
59 * single transaction
\r
62 * Database services (see e.g. {@link Session}) are available from implemented
\r
63 * {@link ServiceLocator}. For an asynchronous counterpart with the same
\r
64 * functionality as RequestProcessor see {@link AsyncRequestProcessor}
\r
67 * <b>IMPORTANT:</b>A client invoking any of the <code>syncRequest</code>
\r
68 * -methods in this interface must not assume that the request is performed
\r
69 * within the same thread that performed the <code>syncRequest</code>
\r
70 * invocation. This is an implementation-specific matter.
\r
73 * @author Antti Villberg
\r
77 * @see AsyncMultiRead
\r
82 * @see MergingGraphRequestProcessor
\r
83 * @see AsyncRequestProcessor
\r
85 public interface RequestProcessorSpecific extends AsyncRequestProcessor {
\r
88 * Synchronously determines and returns the result of the given {@link Read}
\r
89 * and registers the given {@link Read} as a dependency of the ongoing
\r
90 * request if any. This is usually invoked for the side-effects of the given
\r
91 * {@link Read} but can also be used for e.g. dependency registering or
\r
94 * @param request an instance of {@link Read}
\r
95 * @return the result of the given {@link Read}
\r
96 * @throws DatabaseException from {@link Read#perform(ReadGraph)} or from
\r
97 * request processing system
\r
99 <T> T syncRequest(Read<T> request) throws DatabaseException;
\r
102 * Synchronously registers the given {@link AsyncListener} (as identified
\r
103 * by {@link Object#equals(Object)}) to track changes in the result
\r
104 * determined from the given {@link Read}. Registers the given {@link Read}
\r
105 * as a dependency of the ongoing request if any. Exceptions due to the
\r
106 * determination of the result of the given {@link Read} will be transferred
\r
107 * to the given {@link AsyncListener}.
\r
109 * @param request an instance of {@link Read}.
\r
110 * @param procedure an instance of {@link AsyncListener}.
\r
112 //<T> T syncRequest(Read<T> request, AsyncListener<T> procedure) throws DatabaseException;
\r
115 * Synchronously registers the given {@link SyncListener} (as identified by
\r
116 * {@link Object#equals(Object)}) to track changes in the result determined
\r
117 * from the given {@link Read}. Registers the given {@link Read} as a
\r
118 * dependency of the ongoing request if any. Exceptions due to the
\r
119 * determination of the result of the given {@link Read} will be transferred
\r
120 * to the given {@link SyncListener}
\r
122 * @param request an instance of {@link Read}.
\r
123 * @param procedure an instance of {@link SyncListener}.
\r
125 <T> T syncRequest(Read<T> request, SyncListener<T> procedure) throws DatabaseException;
\r
128 * Synchronously registers the given {@link Listener} (as identified by
\r
129 * {@link Object#equals(Object)}) to track changes in the result determined
\r
130 * from the given {@link Read}. Registers the given {@link Read} as a
\r
131 * dependency of the ongoing request if any. Exceptions due to the
\r
132 * determination of the result of the given {@link Read} will be transferred
\r
133 * to the given {@link Listener}
\r
135 * @param request an instance of {@link Read}.
\r
136 * @param procedure an instance of {@link Listener}.
\r
138 <T> T syncRequest(Read<T> request, Listener<T> procedure) throws DatabaseException;
\r
141 * Synchronously supplies the result determined from the given {@link Read}
\r
142 * to the given {@link AsyncProcedure}. Registers the given {@link Read} as
\r
143 * a dependency of the ongoing request if any. Exceptions due to the
\r
144 * determination of the result of the given {@link Read} will be transferred
\r
145 * to the given {@link AsyncProcedure}
\r
147 * @param request an instance of {@link Read}.
\r
148 * @param procedure an instance of {@link AsyncProcedure}.
\r
150 <T> T syncRequest(Read<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
\r
153 * Synchronously supplies the result determined from the given {@link Read}
\r
154 * to the given {@link SyncProcedure}. Registers the given {@link Read} as a
\r
155 * dependency of the ongoing request if any. Exceptions due to the
\r
156 * determination of the result of the given {@link Read} will be transferred
\r
157 * to the given {@link SyncProcedure}
\r
159 * @param request an instance of {@link Read}.
\r
160 * @param procedure an instance of {@link SyncProcedure}.
\r
162 <T> T syncRequest(Read<T> request, SyncProcedure<T> procedure) throws DatabaseException;
\r
165 * Synchronously supplies the result determined from the given {@link Read}
\r
166 * to the given {@link Procedure}. Registers the given {@link Read} as a
\r
167 * dependency of the ongoing request if any. Exceptions due to the
\r
168 * determination of the result of the given {@link Read} will be transferred
\r
169 * to the given {@link Procedure}
\r
171 * @param request an instance of {@link Read}.
\r
172 * @param procedure an instance of {@link Procedure}.
\r
174 <T> T syncRequest(Read<T> request, Procedure<T> procedure) throws DatabaseException;
\r
177 * Synchronously determines the result of the given {@link AsyncRead} and
\r
178 * registers the given {@link AsyncRead} as a dependency of the ongoing
\r
179 * request if any. This is usually invoked for the side-effects of the given
\r
180 * {@link AsyncRead} but can also be used for e.g. dependency registering or
\r
183 * @param request an instance of {@link AsyncRead}.
\r
184 * @return the result of the given {@link AsyncRead}
\r
185 * @throws DatabaseException from {@link AsyncRead#perform(AsyncReadGraph)} or from
\r
186 * request processing system
\r
188 <T> T syncRequest(AsyncRead<T> request) throws DatabaseException;
\r
191 * Synchronously registers the given {@link AsyncListener} (as identified
\r
192 * by {@link Object#equals(Object)}) to track changes in the result
\r
193 * determined from the given {@link AsyncRead}. Registers the given
\r
194 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
195 * Exceptions due to the determination of the result of the given
\r
196 * {@link AsyncRead} will be transferred to the given {@link AsyncListener}.
\r
198 * @param request an instance of {@link AsyncRead}.
\r
199 * @param procedure an instance of {@link AsyncListener}.
\r
201 <T> T syncRequest(AsyncRead<T> request, AsyncListener<T> procedure) throws DatabaseException;
\r
204 * Synchronously registers the given {@link SyncListener} (as identified by
\r
205 * {@link Object#equals(Object)}) to track changes in the result determined
\r
206 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
\r
207 * as a dependency of the ongoing request if any. Exceptions due to the
\r
208 * determination of the result of the given {@link AsyncRead} will be
\r
209 * transferred to the given {@link SyncListener}
\r
211 * @param request an instance of {@link AsyncRead}.
\r
212 * @param procedure an instance of {@link SyncListener}.
\r
214 <T> T syncRequest(AsyncRead<T> request, SyncListener<T> procedure) throws DatabaseException;
\r
217 * Synchronously registers the given {@link Listener} (as identified by
\r
218 * {@link Object#equals(Object)}) to track changes in the result determined
\r
219 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
\r
220 * as a dependency of the ongoing request if any. Exceptions due to the
\r
221 * determination of the result of the given {@link AsyncRead} will be
\r
222 * transferred to the given {@link Listener}
\r
224 * @param request an instance of {@link AsyncRead}.
\r
225 * @param procedure an instance of {@link Listener}.
\r
227 <T> T syncRequest(AsyncRead<T> request, Listener<T> procedure) throws DatabaseException;
\r
230 * Synchronously supplies the result determined from the given
\r
231 * {@link AsyncRead} to the given {@link AsyncProcedure}. Registers the
\r
232 * given {@link AsyncRead} as a dependency of the ongoing request if any.
\r
233 * Exceptions due to the determination of the result of the given
\r
234 * {@link AsyncRead} will be transferred to the given {@link AsyncProcedure}
\r
236 * @param request an instance of {@link AsyncRead}.
\r
237 * @param procedure an instance of {@link AsyncProcedure}.
\r
239 <T> T syncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
\r
242 * Synchronously supplies the result determined from the given
\r
243 * {@link AsyncRead} to the given {@link SyncProcedure}. Registers the given
\r
244 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
245 * Exceptions due to the determination of the result of the given
\r
246 * {@link AsyncRead} will be transferred to the given {@link SyncProcedure}
\r
248 * @param request an instance of {@link AsyncRead}.
\r
249 * @param procedure an instance of {@link SyncProcedure}.
\r
251 <T> T syncRequest(AsyncRead<T> request, SyncProcedure<T> procedure) throws DatabaseException;
\r
254 * Synchronously supplies the result determined from the given
\r
255 * {@link AsyncRead} to the given {@link Procedure}. Registers the given
\r
256 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
257 * Exceptions due to the determination of the result of the given
\r
258 * {@link AsyncRead} will be transferred to the given {@link Procedure}
\r
260 * @param request an instance of {@link AsyncRead}.
\r
261 * @param procedure an instance of {@link Procedure}.
\r
263 <T> T syncRequest(AsyncRead<T> request, Procedure<T> procedure) throws DatabaseException;
\r
266 * Synchronously determines the result of the given {@link MultiRead} and
\r
267 * registers the given {@link MultiRead} as a dependency of the ongoing
\r
268 * request if any. This is usually invoked for the side-effects of the given
\r
269 * {@link MultiRead} but can also be used for e.g. dependency registering or
\r
270 * cache priming. All exceptions from request processing will be lost.
\r
272 * @param request an instance of {@link MultiRead}.
\r
273 * @return the result of the given {@link MultiRead}
\r
274 * @throws DatabaseException from {@link MultiRead#perform(ReadGraph)} or from
\r
275 * request processing system
\r
277 <T> Collection<T> syncRequest(MultiRead<T> request) throws DatabaseException;
\r
280 * Synchronously registers the given {@link AsyncMultiListener} (as
\r
281 * identified by {@link Object#equals(Object)}) to track changes in the
\r
282 * result determined from the given {@link MultiRead}. Registers the given
\r
283 * {@link MultiRead} as a dependency of the ongoing request if any.
\r
284 * Exceptions due to the determination of the result of the given
\r
285 * {@link MultiRead} will be transferred to the given
\r
286 * {@link AsyncMultiListener}.
\r
288 * @param request an instance of {@link MultiRead}.
\r
289 * @param procedure an instance of {@link AsyncMultiListener}.
\r
291 <T> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
\r
294 * Synchronously registers the given {@link SyncMultiListener} (as
\r
295 * identified by {@link Object#equals(Object)}) to track changes in the
\r
296 * result determined from the given {@link MultiRead}. Registers the given
\r
297 * {@link MultiRead} as a dependency of the ongoing request if any.
\r
298 * Exceptions due to the determination of the result of the given
\r
299 * {@link MultiRead} will be transferred to the given
\r
300 * {@link SyncMultiListener}
\r
302 * @param request an instance of {@link MultiRead}.
\r
303 * @param procedure an instance of {@link SyncMultiListener}.
\r
305 <T> Collection<T> syncRequest(MultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
\r
308 * Synchronously registers the given {@link MultiListener} (as identified
\r
309 * by {@link Object#equals(Object)}) to track changes in the result
\r
310 * determined from the given {@link MultiRead}. Registers the given
\r
311 * {@link MultiRead} as a dependency of the ongoing request if any.
\r
312 * Exceptions due to the determination of the result of the given
\r
313 * {@link MultiRead} will be transferred to the given {@link MultiListener}
\r
315 * @param request an instance of {@link MultiRead}.
\r
316 * @param procedure an instance of {@link MultiListener}.
\r
318 <T> Collection<T> syncRequest(MultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
\r
321 * Synchronously supplies the result determined from the given
\r
322 * {@link MultiRead} to the given {@link AsyncMultiProcedure}. Registers the
\r
323 * given {@link MultiRead} as a dependency of the ongoing request if any.
\r
324 * Exceptions due to the determination of the result of the given
\r
325 * {@link MultiRead} will be transferred to the given
\r
326 * {@link AsyncMultiProcedure}
\r
328 * @param request an instance of {@link MultiRead}.
\r
329 * @param procedure an instance of {@link AsyncMultiProcedure}.
\r
331 <T> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
\r
334 * Synchronously supplies the result determined from the given
\r
335 * {@link MultiRead} to the given {@link SyncMultiProcedure}. Registers the
\r
336 * given {@link MultiRead} as a dependency of the ongoing request if any.
\r
337 * Exceptions due to the determination of the result of the given
\r
338 * {@link MultiRead} will be transferred to the given
\r
339 * {@link SyncMultiProcedure}
\r
341 * @param request an instance of {@link MultiRead}.
\r
342 * @param procedure an instance of {@link SyncMultiProcedure}.
\r
344 <T> Collection<T> syncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
\r
347 * Synchronously supplies the result determined from the given
\r
348 * {@link MultiRead} to the given {@link MultiProcedure}. Registers the
\r
349 * given {@link MultiRead} as a dependency of the ongoing request if any.
\r
350 * Exceptions due to the determination of the result of the given
\r
351 * {@link MultiRead} will be transferred to the given {@link MultiProcedure}
\r
353 * @param request an instance of {@link MultiRead}.
\r
354 * @param procedure an instance of {@link MultiProcedure}.
\r
356 <T> Collection<T> syncRequest(MultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
\r
359 * Synchronously determines the result of the given {@link AsyncMultiRead}
\r
360 * and registers the given {@link AsyncMultiRead} as a dependency of the
\r
361 * ongoing request if any. This is usually invoked for the side-effects of
\r
362 * the given {@link AsyncMultiRead} but can also be used for e.g. dependency
\r
363 * registering or cache priming. All exceptions from request processing will
\r
366 * @param request an instance of {@link AsyncMultiRead}.
\r
367 * @throws DatabaseException from {@link AsyncMultiRead#perform(AsyncReadGraph)} or from
\r
368 * request processing system
\r
370 <T> Collection<T> syncRequest(AsyncMultiRead<T> request) throws DatabaseException;
\r
373 * Synchronously registers the given {@link AsyncMultiListener} (as
\r
374 * identified by {@link Object#equals(Object)}) to track changes in the
\r
375 * result determined from the given {@link AsyncMultiRead}. Registers the
\r
376 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
377 * any. Exceptions due to the determination of the result of the given
\r
378 * {@link AsyncMultiRead} will be transferred to the given
\r
379 * {@link AsyncMultiListener}.
\r
381 * @param request an instance of {@link AsyncMultiRead}.
\r
382 * @param procedure an instance of {@link AsyncMultiListener}.
\r
384 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
\r
387 * Synchronously registers the given {@link SyncMultiListener} (as
\r
388 * identified by {@link Object#equals(Object)}) to track changes in the
\r
389 * result determined from the given {@link AsyncMultiRead}. Registers the
\r
390 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
391 * any. Exceptions due to the determination of the result of the given
\r
392 * {@link AsyncMultiRead} will be transferred to the given
\r
393 * {@link SyncMultiListener}
\r
395 * @param request an instance of {@link AsyncMultiRead}.
\r
396 * @param procedure an instance of {@link SyncMultiListener}.
\r
398 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
\r
401 * Synchronously registers the given {@link MultiListener} (as identified
\r
402 * by {@link Object#equals(Object)}) to track changes in the result
\r
403 * determined from the given {@link AsyncMultiRead}. Registers the given
\r
404 * {@link AsyncMultiRead} as a dependency of the ongoing request if any.
\r
405 * Exceptions due to the determination of the result of the given
\r
406 * {@link AsyncMultiRead} will be transferred to the given
\r
407 * {@link MultiListener}
\r
409 * @param request an instance of {@link AsyncMultiRead}.
\r
410 * @param procedure an instance of {@link MultiListener}.
\r
412 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
\r
415 * Synchronously supplies the result determined from the given
\r
416 * {@link AsyncMultiRead} to the given {@link AsyncMultiProcedure}.
\r
417 * Registers the given {@link AsyncMultiRead} as a dependency of the ongoing
\r
418 * request if any. Exceptions due to the determination of the result of the
\r
419 * given {@link AsyncMultiRead} will be transferred to the given
\r
420 * {@link AsyncMultiProcedure}
\r
422 * @param request an instance of {@link AsyncMultiRead}.
\r
423 * @param procedure an instance of {@link AsyncMultiProcedure}.
\r
425 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
\r
428 * Synchronously supplies the result determined from the given
\r
429 * {@link AsyncMultiRead} to the given {@link SyncMultiProcedure}. Registers
\r
430 * the given {@link AsyncMultiRead} as a dependency of the ongoing request
\r
431 * if any. Exceptions due to the determination of the result of the given
\r
432 * {@link AsyncMultiRead} will be transferred to the given
\r
433 * {@link SyncMultiProcedure}
\r
435 * @param request an instance of {@link AsyncMultiRead}.
\r
436 * @param procedure an instance of {@link SyncMultiProcedure}.
\r
438 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
\r
441 * Synchronously supplies the result determined from the given
\r
442 * {@link AsyncMultiRead} to the given {@link MultiProcedure}. Registers the
\r
443 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
444 * any. Exceptions due to the determination of the result of the given
\r
445 * {@link AsyncMultiRead} will be transferred to the given
\r
446 * {@link MultiProcedure}
\r
448 * @param request an instance of {@link AsyncMultiRead}.
\r
449 * @param procedure an instance of {@link MultiProcedure}.
\r
451 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
\r
454 <T> T syncRequest(ExternalRead<T> request) throws DatabaseException;
\r
455 <T> T syncRequest(ExternalRead<T> request, Listener<T> procedure) throws DatabaseException;
\r
456 <T> T syncRequest(ExternalRead<T> request, Procedure<T> procedure) throws DatabaseException;
\r
459 * Synchronously performs the given {@link Write}.
\r
461 * @param request an instance of {@link Write}.
\r
463 void syncRequest(Write request) throws DatabaseException;
\r
466 * Synchronously performs the given {@link DelayedWrite}.
\r
468 * @param request an instance of {@link DelayedWrite}.
\r
470 void syncRequest(DelayedWrite request) throws DatabaseException;
\r
473 * Synchronously performs the given {@link WriteOnly}.
\r
475 * @param request an instance of {@link Write}.
\r
477 void syncRequest(WriteOnly r) throws DatabaseException;
\r
480 * Synchronously performs the given {@link Write}.
\r
482 * @param request an instance of {@link Write}.
\r
484 <T> T syncRequest(WriteResult<T> request) throws DatabaseException;
\r
487 * Synchronously performs the given {@link DelayedWrite}.
\r
489 * @param request an instance of {@link DelayedWrite}.
\r
491 <T> T syncRequest(DelayedWriteResult<T> request) throws DatabaseException;
\r
494 * Synchronously performs the given {@link WriteOnly}.
\r
496 * @param request an instance of {@link Write}.
\r
498 <T> T syncRequest(WriteOnlyResult<T> r) throws DatabaseException;
\r