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