1 /*******************************************************************************
2 * Copyright (c) 2007, 2018 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;
15 import java.util.function.Consumer;
17 import org.simantics.db.exception.DatabaseException;
18 import org.simantics.db.procedure.AsyncListener;
19 import org.simantics.db.procedure.AsyncMultiListener;
20 import org.simantics.db.procedure.AsyncMultiProcedure;
21 import org.simantics.db.procedure.AsyncProcedure;
22 import org.simantics.db.procedure.Listener;
23 import org.simantics.db.procedure.MultiListener;
24 import org.simantics.db.procedure.MultiProcedure;
25 import org.simantics.db.procedure.Procedure;
26 import org.simantics.db.procedure.SyncListener;
27 import org.simantics.db.procedure.SyncMultiListener;
28 import org.simantics.db.procedure.SyncMultiProcedure;
29 import org.simantics.db.procedure.SyncProcedure;
30 import org.simantics.db.request.AsyncMultiRead;
31 import org.simantics.db.request.AsyncRead;
32 import org.simantics.db.request.DelayedWrite;
33 import org.simantics.db.request.DelayedWriteResult;
34 import org.simantics.db.request.ExternalRead;
35 import org.simantics.db.request.MultiRead;
36 import org.simantics.db.request.Read;
37 import org.simantics.db.request.Write;
38 import org.simantics.db.request.WriteOnly;
39 import org.simantics.db.request.WriteOnlyResult;
40 import org.simantics.db.request.WriteResult;
44 * For initiating requests in synchronous manner. The possible requests are
46 * <li>{@link Read} for computing a single result synchronously
47 * <li>{@link AsyncRead} for computing a single result asynchronously
48 * <li>{@link MultiRead} for computing a collection of results synchronously
49 * <li>{@link AsyncMultiRead} for computing a collection of results
51 * <li>{@link Write} for reading and writing synchronously
52 * <li>{@link WriteOnly} for writing synchronously
55 * The standard RequestProcessors are
57 * <li>{@link ReadGraph} for performing requests during other requests
58 * <li>{@link Session} for initiating a transactions for performing requests
59 * <li>{@link MergingGraphRequestProcessor} for merging several requests in a
63 * Database services (see e.g. {@link Session}) are available from implemented
64 * {@link ServiceLocator}. For an asynchronous counterpart with the same
65 * functionality as RequestProcessor see {@link AsyncRequestProcessor}
68 * <b>IMPORTANT:</b>A client invoking any of the <code>syncRequest</code>
69 * -methods in this interface must not assume that the request is performed
70 * within the same thread that performed the <code>syncRequest</code>
71 * invocation. This is an implementation-specific matter.
74 * @author Antti Villberg
83 * @see MergingGraphRequestProcessor
84 * @see AsyncRequestProcessor
86 public interface RequestProcessorSpecific {
89 * Synchronously determines and returns the result of the given {@link Read}
90 * and registers the given {@link Read} as a dependency of the ongoing
91 * request if any. This is usually invoked for the side-effects of the given
92 * {@link Read} but can also be used for e.g. dependency registering or
95 * @param request an instance of {@link Read}
96 * @return the result of the given {@link Read}
97 * @throws DatabaseException from {@link Read#perform(ReadGraph)} or from
98 * request processing system
100 <T> T syncRequest(Read<T> request) throws DatabaseException;
103 * Synchronously registers the given {@link AsyncListener} (as identified
104 * by {@link Object#equals(Object)}) to track changes in the result
105 * determined from the given {@link Read}. Registers the given {@link Read}
106 * as a dependency of the ongoing request if any. Exceptions due to the
107 * determination of the result of the given {@link Read} will be transferred
108 * to the given {@link AsyncListener}.
110 * @param request an instance of {@link Read}.
111 * @param procedure an instance of {@link AsyncListener}.
113 //<T> T syncRequest(Read<T> request, AsyncListener<T> procedure) throws DatabaseException;
116 * Synchronously registers the given {@link SyncListener} (as identified by
117 * {@link Object#equals(Object)}) to track changes in the result determined
118 * from the given {@link Read}. Registers the given {@link Read} as a
119 * dependency of the ongoing request if any. Exceptions due to the
120 * determination of the result of the given {@link Read} will be transferred
121 * to the given {@link SyncListener}
123 * @param request an instance of {@link Read}.
124 * @param procedure an instance of {@link SyncListener}.
126 <T> T syncRequest(Read<T> request, SyncListener<T> procedure) throws DatabaseException;
129 * Synchronously registers the given {@link Listener} (as identified by
130 * {@link Object#equals(Object)}) to track changes in the result determined
131 * from the given {@link Read}. Registers the given {@link Read} as a
132 * dependency of the ongoing request if any. Exceptions due to the
133 * determination of the result of the given {@link Read} will be transferred
134 * to the given {@link Listener}
136 * @param request an instance of {@link Read}.
137 * @param procedure an instance of {@link Listener}.
139 <T> T syncRequest(Read<T> request, Listener<T> procedure) throws DatabaseException;
142 * Synchronously supplies the result determined from the given {@link Read}
143 * to the given {@link AsyncProcedure}. Registers the given {@link Read} as
144 * a dependency of the ongoing request if any. Exceptions due to the
145 * determination of the result of the given {@link Read} will be transferred
146 * to the given {@link AsyncProcedure}
148 * @param request an instance of {@link Read}.
149 * @param procedure an instance of {@link AsyncProcedure}.
151 <T> T syncRequest(Read<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
154 * Synchronously supplies the result determined from the given {@link Read}
155 * to the given {@link SyncProcedure}. Registers the given {@link Read} as a
156 * dependency of the ongoing request if any. Exceptions due to the
157 * determination of the result of the given {@link Read} will be transferred
158 * to the given {@link SyncProcedure}
160 * @param request an instance of {@link Read}.
161 * @param procedure an instance of {@link SyncProcedure}.
163 <T> T syncRequest(Read<T> request, SyncProcedure<T> procedure) throws DatabaseException;
166 * Synchronously supplies the result determined from the given {@link Read}
167 * to the given {@link Procedure}. Registers the given {@link Read} as a
168 * dependency of the ongoing request if any. Exceptions due to the
169 * determination of the result of the given {@link Read} will be transferred
170 * to the given {@link Procedure}
172 * @param request an instance of {@link Read}.
173 * @param procedure an instance of {@link Procedure}.
175 <T> T syncRequest(Read<T> request, Procedure<T> procedure) throws DatabaseException;
178 * Synchronously determines the result of the given {@link AsyncRead} and
179 * registers the given {@link AsyncRead} as a dependency of the ongoing
180 * request if any. This is usually invoked for the side-effects of the given
181 * {@link AsyncRead} but can also be used for e.g. dependency registering or
184 * @param request an instance of {@link AsyncRead}.
185 * @return the result of the given {@link AsyncRead}
186 * @throws DatabaseException from {@link AsyncRead#perform(AsyncReadGraph)} or from
187 * request processing system
189 <T> T syncRequest(AsyncRead<T> request) throws DatabaseException;
192 * Synchronously registers the given {@link AsyncListener} (as identified
193 * by {@link Object#equals(Object)}) to track changes in the result
194 * determined from the given {@link AsyncRead}. Registers the given
195 * {@link AsyncRead} as a dependency of the ongoing request if any.
196 * Exceptions due to the determination of the result of the given
197 * {@link AsyncRead} will be transferred to the given {@link AsyncListener}.
199 * @param request an instance of {@link AsyncRead}.
200 * @param procedure an instance of {@link AsyncListener}.
202 <T> T syncRequest(AsyncRead<T> request, AsyncListener<T> procedure) throws DatabaseException;
205 * Synchronously registers the given {@link SyncListener} (as identified by
206 * {@link Object#equals(Object)}) to track changes in the result determined
207 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
208 * as a dependency of the ongoing request if any. Exceptions due to the
209 * determination of the result of the given {@link AsyncRead} will be
210 * transferred to the given {@link SyncListener}
212 * @param request an instance of {@link AsyncRead}.
213 * @param procedure an instance of {@link SyncListener}.
215 <T> T syncRequest(AsyncRead<T> request, SyncListener<T> procedure) throws DatabaseException;
218 * Synchronously registers the given {@link Listener} (as identified by
219 * {@link Object#equals(Object)}) to track changes in the result determined
220 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
221 * as a dependency of the ongoing request if any. Exceptions due to the
222 * determination of the result of the given {@link AsyncRead} will be
223 * transferred to the given {@link Listener}
225 * @param request an instance of {@link AsyncRead}.
226 * @param procedure an instance of {@link Listener}.
228 <T> T syncRequest(AsyncRead<T> request, Listener<T> procedure) throws DatabaseException;
231 * Synchronously supplies the result determined from the given
232 * {@link AsyncRead} to the given {@link AsyncProcedure}. Registers the
233 * given {@link AsyncRead} as a dependency of the ongoing request if any.
234 * Exceptions due to the determination of the result of the given
235 * {@link AsyncRead} will be transferred to the given {@link AsyncProcedure}
237 * @param request an instance of {@link AsyncRead}.
238 * @param procedure an instance of {@link AsyncProcedure}.
240 <T> T syncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
243 * Synchronously supplies the result determined from the given
244 * {@link AsyncRead} to the given {@link SyncProcedure}. Registers the given
245 * {@link AsyncRead} as a dependency of the ongoing request if any.
246 * Exceptions due to the determination of the result of the given
247 * {@link AsyncRead} will be transferred to the given {@link SyncProcedure}
249 * @param request an instance of {@link AsyncRead}.
250 * @param procedure an instance of {@link SyncProcedure}.
252 <T> T syncRequest(AsyncRead<T> request, SyncProcedure<T> procedure) throws DatabaseException;
255 * Synchronously supplies the result determined from the given
256 * {@link AsyncRead} to the given {@link Procedure}. Registers the given
257 * {@link AsyncRead} as a dependency of the ongoing request if any.
258 * Exceptions due to the determination of the result of the given
259 * {@link AsyncRead} will be transferred to the given {@link Procedure}
261 * @param request an instance of {@link AsyncRead}.
262 * @param procedure an instance of {@link Procedure}.
264 <T> T syncRequest(AsyncRead<T> request, Procedure<T> procedure) throws DatabaseException;
267 * Synchronously determines the result of the given {@link MultiRead} and
268 * registers the given {@link MultiRead} as a dependency of the ongoing
269 * request if any. This is usually invoked for the side-effects of the given
270 * {@link MultiRead} but can also be used for e.g. dependency registering or
271 * cache priming. All exceptions from request processing will be lost.
273 * @param request an instance of {@link MultiRead}.
274 * @return the result of the given {@link MultiRead}
275 * @throws DatabaseException from {@link MultiRead#perform(ReadGraph)} or from
276 * request processing system
278 <T> Collection<T> syncRequest(MultiRead<T> request) throws DatabaseException;
281 * Synchronously registers the given {@link AsyncMultiListener} (as
282 * identified by {@link Object#equals(Object)}) to track changes in the
283 * result determined from the given {@link MultiRead}. Registers the given
284 * {@link MultiRead} as a dependency of the ongoing request if any.
285 * Exceptions due to the determination of the result of the given
286 * {@link MultiRead} will be transferred to the given
287 * {@link AsyncMultiListener}.
289 * @param request an instance of {@link MultiRead}.
290 * @param procedure an instance of {@link AsyncMultiListener}.
292 //<T> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
295 * Synchronously registers the given {@link SyncMultiListener} (as
296 * identified by {@link Object#equals(Object)}) to track changes in the
297 * result determined from the given {@link MultiRead}. Registers the given
298 * {@link MultiRead} as a dependency of the ongoing request if any.
299 * Exceptions due to the determination of the result of the given
300 * {@link MultiRead} will be transferred to the given
301 * {@link SyncMultiListener}
303 * @param request an instance of {@link MultiRead}.
304 * @param procedure an instance of {@link SyncMultiListener}.
306 <T> Collection<T> syncRequest(MultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
309 * Synchronously registers the given {@link MultiListener} (as identified
310 * by {@link Object#equals(Object)}) to track changes in the result
311 * determined from the given {@link MultiRead}. Registers the given
312 * {@link MultiRead} as a dependency of the ongoing request if any.
313 * Exceptions due to the determination of the result of the given
314 * {@link MultiRead} will be transferred to the given {@link MultiListener}
316 * @param request an instance of {@link MultiRead}.
317 * @param procedure an instance of {@link MultiListener}.
319 <T> Collection<T> syncRequest(MultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
322 * Synchronously supplies the result determined from the given
323 * {@link MultiRead} to the given {@link AsyncMultiProcedure}. Registers the
324 * given {@link MultiRead} as a dependency of the ongoing request if any.
325 * Exceptions due to the determination of the result of the given
326 * {@link MultiRead} will be transferred to the given
327 * {@link AsyncMultiProcedure}
329 * @param request an instance of {@link MultiRead}.
330 * @param procedure an instance of {@link AsyncMultiProcedure}.
332 //<T> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
335 * Synchronously supplies the result determined from the given
336 * {@link MultiRead} to the given {@link SyncMultiProcedure}. Registers the
337 * given {@link MultiRead} as a dependency of the ongoing request if any.
338 * Exceptions due to the determination of the result of the given
339 * {@link MultiRead} will be transferred to the given
340 * {@link SyncMultiProcedure}
342 * @param request an instance of {@link MultiRead}.
343 * @param procedure an instance of {@link SyncMultiProcedure}.
345 <T> Collection<T> syncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
348 * Synchronously supplies the result determined from the given
349 * {@link MultiRead} to the given {@link MultiProcedure}. Registers the
350 * given {@link MultiRead} as a dependency of the ongoing request if any.
351 * Exceptions due to the determination of the result of the given
352 * {@link MultiRead} will be transferred to the given {@link MultiProcedure}
354 * @param request an instance of {@link MultiRead}.
355 * @param procedure an instance of {@link MultiProcedure}.
357 <T> Collection<T> syncRequest(MultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
360 * Synchronously determines the result of the given {@link AsyncMultiRead}
361 * and registers the given {@link AsyncMultiRead} as a dependency of the
362 * ongoing request if any. This is usually invoked for the side-effects of
363 * the given {@link AsyncMultiRead} but can also be used for e.g. dependency
364 * registering or cache priming. All exceptions from request processing will
367 * @param request an instance of {@link AsyncMultiRead}.
368 * @throws DatabaseException from {@link AsyncMultiRead#perform(AsyncReadGraph)} or from
369 * request processing system
371 <T> Collection<T> syncRequest(AsyncMultiRead<T> request) throws DatabaseException;
374 * Synchronously registers the given {@link AsyncMultiListener} (as
375 * identified by {@link Object#equals(Object)}) to track changes in the
376 * result determined from the given {@link AsyncMultiRead}. Registers the
377 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
378 * any. Exceptions due to the determination of the result of the given
379 * {@link AsyncMultiRead} will be transferred to the given
380 * {@link AsyncMultiListener}.
382 * @param request an instance of {@link AsyncMultiRead}.
383 * @param procedure an instance of {@link AsyncMultiListener}.
385 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
388 * Synchronously registers the given {@link SyncMultiListener} (as
389 * identified by {@link Object#equals(Object)}) to track changes in the
390 * result determined from the given {@link AsyncMultiRead}. Registers the
391 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
392 * any. Exceptions due to the determination of the result of the given
393 * {@link AsyncMultiRead} will be transferred to the given
394 * {@link SyncMultiListener}
396 * @param request an instance of {@link AsyncMultiRead}.
397 * @param procedure an instance of {@link SyncMultiListener}.
399 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
402 * Synchronously registers the given {@link MultiListener} (as identified
403 * by {@link Object#equals(Object)}) to track changes in the result
404 * determined from the given {@link AsyncMultiRead}. Registers the given
405 * {@link AsyncMultiRead} as a dependency of the ongoing request if any.
406 * Exceptions due to the determination of the result of the given
407 * {@link AsyncMultiRead} will be transferred to the given
408 * {@link MultiListener}
410 * @param request an instance of {@link AsyncMultiRead}.
411 * @param procedure an instance of {@link MultiListener}.
413 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
416 * Synchronously supplies the result determined from the given
417 * {@link AsyncMultiRead} to the given {@link AsyncMultiProcedure}.
418 * Registers the given {@link AsyncMultiRead} as a dependency of the ongoing
419 * request if any. Exceptions due to the determination of the result of the
420 * given {@link AsyncMultiRead} will be transferred to the given
421 * {@link AsyncMultiProcedure}
423 * @param request an instance of {@link AsyncMultiRead}.
424 * @param procedure an instance of {@link AsyncMultiProcedure}.
426 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
429 * Synchronously supplies the result determined from the given
430 * {@link AsyncMultiRead} to the given {@link SyncMultiProcedure}. Registers
431 * the given {@link AsyncMultiRead} as a dependency of the ongoing request
432 * if any. Exceptions due to the determination of the result of the given
433 * {@link AsyncMultiRead} will be transferred to the given
434 * {@link SyncMultiProcedure}
436 * @param request an instance of {@link AsyncMultiRead}.
437 * @param procedure an instance of {@link SyncMultiProcedure}.
439 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
442 * Synchronously supplies the result determined from the given
443 * {@link AsyncMultiRead} to the given {@link MultiProcedure}. Registers the
444 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
445 * any. Exceptions due to the determination of the result of the given
446 * {@link AsyncMultiRead} will be transferred to the given
447 * {@link MultiProcedure}
449 * @param request an instance of {@link AsyncMultiRead}.
450 * @param procedure an instance of {@link MultiProcedure}.
452 <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
455 <T> T syncRequest(ExternalRead<T> request) throws DatabaseException;
456 <T> T syncRequest(ExternalRead<T> request, Listener<T> procedure) throws DatabaseException;
457 <T> T syncRequest(ExternalRead<T> request, Procedure<T> procedure) throws DatabaseException;
460 * Synchronously performs the given {@link Write}.
462 * @param request an instance of {@link Write}.
464 void syncRequest(Write request) throws DatabaseException;
467 * Synchronously performs the given {@link DelayedWrite}.
469 * @param request an instance of {@link DelayedWrite}.
471 void syncRequest(DelayedWrite request) throws DatabaseException;
474 * Synchronously performs the given {@link WriteOnly}.
476 * @param request an instance of {@link Write}.
478 void syncRequest(WriteOnly r) throws DatabaseException;
481 * Synchronously performs the given {@link Write}.
483 * @param request an instance of {@link Write}.
485 <T> T syncRequest(WriteResult<T> request) throws DatabaseException;
488 * Synchronously performs the given {@link DelayedWrite}.
490 * @param request an instance of {@link DelayedWrite}.
492 <T> T syncRequest(DelayedWriteResult<T> request) throws DatabaseException;
495 * Synchronously performs the given {@link WriteOnly}.
497 * @param request an instance of {@link Write}.
499 <T> T syncRequest(WriteOnlyResult<T> r) throws DatabaseException;
502 * Asynchronously performs the given {@link Write}. The outcome of the
503 * request will be lost.
505 * @param request an instance of {@link Write}.
507 void asyncRequest(Write request);
510 * Asynchronously performs the given {@link Write}. The outcome of the
511 * request will be reported to given {@link Consumer} in the form of a
512 * DatabaseException raised during request processing or null upon success.
514 * @param request an instance of {@link Write}.
515 * @param request an instance of {@link Consumer}.
517 void asyncRequest(Write request, Consumer<DatabaseException> callback);
519 <T> void asyncRequest(WriteResult<T> r, Procedure<T> procedure);
523 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
524 * request will be lost.
526 * @param request an instance of {@link Write}.
528 void asyncRequest(DelayedWrite request);
531 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
532 * request will be reported to given {@link Consumer} in the form of a
533 * DatabaseException raised during request processing or null upon success.
535 * @param request an instance of {@link WriteOnly}.
536 * @param request an instance of {@link Consumer}.
538 void asyncRequest(DelayedWrite request, Consumer<DatabaseException> callback);
540 <T> void asyncRequest(DelayedWriteResult<T> r, Procedure<T> procedure);
543 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
544 * request will be lost.
546 * @param request an instance of {@link Write}.
548 void asyncRequest(WriteOnly r);
551 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
552 * request will be reported to given {@link Consumer} in the form of a
553 * DatabaseException raised during request processing or null upon success.
555 * @param request an instance of {@link WriteOnly}.
556 * @param request an instance of {@link Consumer}.
558 void asyncRequest(WriteOnly r, Consumer<DatabaseException> callback);
560 <T> void asyncRequest(WriteOnlyResult<T> r, Procedure<T> procedure);