]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.db/src/org/simantics/db/AsyncRequestProcessorSpecific.java
Multiple readers and variable optimization
[simantics/platform.git] / bundles / org.simantics.db / src / org / simantics / db / AsyncRequestProcessorSpecific.java
1 /*******************************************************************************
2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
3  * in Industry THTH ry.
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
8  *
9  * Contributors:
10  *     VTT Technical Research Centre of Finland - initial API and implementation
11  *******************************************************************************/
12 package org.simantics.db;
13
14 import java.util.function.Consumer;
15
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;
40
41 /**
42  * 
43  * For initiating requests in asynchronous manner. The possible requests are
44  * <ul>
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
49  * asynchronously
50  * <li>{@link Write} for reading and writing synchronously
51  * <li>{@link WriteOnly} for writing synchronously
52  * </ul>
53  * <p>
54  * The standard AsyncRequestProcessors are
55  * <ul>
56  * <li>{@link AsyncReadGraph} 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
59  * single transaction
60  * </ul>
61  * 
62  * Database services (see e.g. {@link Session}) are available from implemented
63  * {@link ServiceLocator}. For a synchronous counterpart with the same
64  * functionality as AsyncRequestProcessor see {@link RequestProcessor}
65  * 
66  * @version 0.7
67  * @author Antti Villberg
68  * @see Read
69  * @see AsyncRead
70  * @see MultiRead
71  * @see AsyncMultiRead
72  * @see Write
73  * @see WriteOnly
74  * @see AsyncReadGraph
75  * @see Session
76  * @see MergingGraphRequestProcessor
77  * @see RequestProcessor
78  */
79 public interface AsyncRequestProcessorSpecific extends ServiceLocator {
80
81     /**
82      * Provides access to a set of standard resources defined in Layer0. The
83      * existence of {@link Builtins} is guaranteed at {@link Session} creation
84      * time hence the method does not throw. It is also assumed that the
85      * identify of the standard resources cannot change during sessions. To work
86      * this requires that Builtins.class has been registered with this
87      * ServiceLocator. Therefore this is merely a shorthand for
88      * <code>ServiceLocator.getService(Builtins.class)</code>.
89      * 
90      * @deprecated in favor of org.simantics.layer0.Layer0. Will be removed in Simantics 1.2
91      * 
92      * @return the <code>Builtins</code> instance associated with this session.
93      */
94 //    @Deprecated
95 //    Builtins getBuiltins();
96
97     /**
98      * Asynchronously determines the result of the given {@link Read} and
99      * registers the given {@link Read} as a dependency of the ongoing request
100      * if any. This is usually invoked for the side-effects of the given
101      * {@link Read} but can also be used for e.g. dependency registering or
102      * cache priming. All exceptions from request processing will be lost.
103      * 
104      * @param request an instance of {@link Read}.
105      */
106     <T> void asyncRequest(Read<T> request);
107
108     /**
109      * Asynchronously registers the given {@link AsyncListener} (as identified
110      * by {@link Object#equals(Object)}) to track changes in the result
111      * determined from the given {@link Read}. Registers the given {@link Read}
112      * as a dependency of the ongoing request if any. Exceptions due to the
113      * determination of the result of the given {@link Read} will be transferred
114      * to the given {@link AsyncListener}.
115      * 
116      * @param request an instance of {@link Read}.
117      * @param procedure an instance of {@link AsyncListener}.
118      */
119     <T> void asyncRequest(Read<T> request, AsyncListener<T> procedure);
120
121     /**
122      * Asynchronously registers the given {@link SyncListener} (as identified by
123      * {@link Object#equals(Object)}) to track changes in the result determined
124      * from the given {@link Read}. Registers the given {@link Read} as a
125      * dependency of the ongoing request if any. Exceptions due to the
126      * determination of the result of the given {@link Read} will be transferred
127      * to the given {@link SyncListener}
128      * 
129      * @param request an instance of {@link Read}.
130      * @param procedure an instance of {@link SyncListener}.
131      */
132     <T> void asyncRequest(Read<T> request, SyncListener<T> procedure);
133
134     /**
135      * Asynchronously registers the given {@link Listener} (as identified by
136      * {@link Object#equals(Object)}) to track changes in the result determined
137      * from the given {@link Read}. Registers the given {@link Read} as a
138      * dependency of the ongoing request if any. Exceptions due to the
139      * determination of the result of the given {@link Read} will be transferred
140      * to the given {@link Listener}
141      * 
142      * @param request an instance of {@link Read}.
143      * @param procedure an instance of {@link Listener}.
144      */
145     <T> void asyncRequest(Read<T> request, Listener<T> procedure);
146
147     /**
148      * Asynchronously supplies the result determined from the given {@link Read}
149      * to the given {@link AsyncProcedure}. Registers the given {@link Read} as
150      * a dependency of the ongoing request if any. Exceptions due to the
151      * determination of the result of the given {@link Read} will be transferred
152      * to the given {@link AsyncProcedure}
153      * 
154      * @param request an instance of {@link Read}.
155      * @param procedure an instance of {@link AsyncProcedure}.
156      */
157     <T> void asyncRequest(Read<T> request, AsyncProcedure<T> procedure);
158
159     /**
160      * Asynchronously supplies the result determined from the given {@link Read}
161      * to the given {@link SyncProcedure}. Registers the given {@link Read} as a
162      * dependency of the ongoing request if any. Exceptions due to the
163      * determination of the result of the given {@link Read} will be transferred
164      * to the given {@link SyncProcedure}
165      * 
166      * @param request an instance of {@link Read}.
167      * @param procedure an instance of {@link SyncProcedure}.
168      */
169     <T> void asyncRequest(Read<T> request, SyncProcedure<T> procedure);
170
171     /**
172      * Asynchronously supplies the result determined from the given {@link Read}
173      * to the given {@link Procedure}. Registers the given {@link Read} as a
174      * dependency of the ongoing request if any. Exceptions due to the
175      * determination of the result of the given {@link Read} will be transferred
176      * to the given {@link Procedure}
177      * 
178      * @param request an instance of {@link Read}.
179      * @param procedure an instance of {@link Procedure}.
180      */
181     <T> void asyncRequest(Read<T> request, Procedure<T> procedure);
182
183     /**
184      * Asynchronously determines the result of the given {@link AsyncRead} and
185      * registers the given {@link AsyncRead} as a dependency of the ongoing
186      * request if any. This is usually invoked for the side-effects of the given
187      * {@link AsyncRead} but can also be used for e.g. dependency registering or
188      * cache priming. All exceptions from request processing will be lost.
189      * 
190      * @param request an instance of {@link AsyncRead}.
191      */
192     <T> void asyncRequest(AsyncRead<T> request);
193
194     /**
195      * Asynchronously registers the given {@link AsyncListener} (as identified
196      * by {@link Object#equals(Object)}) to track changes in the result
197      * determined from the given {@link AsyncRead}. Registers the given
198      * {@link AsyncRead} as a dependency of the ongoing request if any.
199      * Exceptions due to the determination of the result of the given
200      * {@link AsyncRead} will be transferred to the given {@link AsyncListener}.
201      * 
202      * @param request an instance of {@link AsyncRead}.
203      * @param procedure an instance of {@link AsyncListener}.
204      */
205     <T> void asyncRequest(AsyncRead<T> request, AsyncListener<T> procedure);
206
207     /**
208      * Asynchronously registers the given {@link SyncListener} (as identified by
209      * {@link Object#equals(Object)}) to track changes in the result determined
210      * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
211      * as a dependency of the ongoing request if any. Exceptions due to the
212      * determination of the result of the given {@link AsyncRead} will be
213      * transferred to the given {@link SyncListener}
214      * 
215      * @param request an instance of {@link AsyncRead}.
216      * @param procedure an instance of {@link SyncListener}.
217      */
218     <T> void asyncRequest(AsyncRead<T> request, SyncListener<T> procedure);
219
220     /**
221      * Asynchronously registers the given {@link Listener} (as identified by
222      * {@link Object#equals(Object)}) to track changes in the result determined
223      * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
224      * as a dependency of the ongoing request if any. Exceptions due to the
225      * determination of the result of the given {@link AsyncRead} will be
226      * transferred to the given {@link Listener}
227      * 
228      * @param request an instance of {@link AsyncRead}.
229      * @param procedure an instance of {@link Listener}.
230      */
231     <T> void asyncRequest(AsyncRead<T> request, Listener<T> procedure);
232
233     /**
234      * Asynchronously supplies the result determined from the given
235      * {@link AsyncRead} to the given {@link AsyncProcedure}. Registers the
236      * given {@link AsyncRead} as a dependency of the ongoing request if any.
237      * Exceptions due to the determination of the result of the given
238      * {@link AsyncRead} will be transferred to the given {@link AsyncProcedure}
239      * 
240      * @param request an instance of {@link AsyncRead}.
241      * @param procedure an instance of {@link AsyncProcedure}.
242      */
243     <T> void asyncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure);
244
245     /**
246      * Asynchronously supplies the result determined from the given
247      * {@link AsyncRead} to the given {@link SyncProcedure}. Registers the given
248      * {@link AsyncRead} as a dependency of the ongoing request if any.
249      * Exceptions due to the determination of the result of the given
250      * {@link AsyncRead} will be transferred to the given {@link SyncProcedure}
251      * 
252      * @param request an instance of {@link AsyncRead}.
253      * @param procedure an instance of {@link SyncProcedure}.
254      */
255     <T> void asyncRequest(AsyncRead<T> request, SyncProcedure<T> procedure);
256
257     /**
258      * Asynchronously supplies the result determined from the given
259      * {@link AsyncRead} to the given {@link Procedure}. Registers the given
260      * {@link AsyncRead} as a dependency of the ongoing request if any.
261      * Exceptions due to the determination of the result of the given
262      * {@link AsyncRead} will be transferred to the given {@link Procedure}
263      * 
264      * @param request an instance of {@link AsyncRead}.
265      * @param procedure an instance of {@link Procedure}.
266      */
267     <T> void asyncRequest(AsyncRead<T> request, Procedure<T> procedure);
268
269     /**
270      * Asynchronously determines the result of the given {@link MultiRead} and
271      * registers the given {@link MultiRead} as a dependency of the ongoing
272      * request if any. This is usually invoked for the side-effects of the given
273      * {@link MultiRead} but can also be used for e.g. dependency registering or
274      * cache priming. All exceptions from request processing will be lost.
275      * 
276      * @param request an instance of {@link MultiRead}.
277      */
278     <T> void asyncRequest(MultiRead<T> request);
279
280     /**
281      * Asynchronously 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}.
288      * 
289      * @param request an instance of {@link MultiRead}.
290      * @param procedure an instance of {@link AsyncMultiListener}.
291      */
292     <T> void asyncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure);
293
294     /**
295      * Asynchronously 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}
302      * 
303      * @param request an instance of {@link MultiRead}.
304      * @param procedure an instance of {@link SyncMultiListener}.
305      */
306     <T> void asyncRequest(MultiRead<T> request, SyncMultiListener<T> procedure);
307
308     /**
309      * Asynchronously 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}
315      * 
316      * @param request an instance of {@link MultiRead}.
317      * @param procedure an instance of {@link MultiListener}.
318      */
319     <T> void asyncRequest(MultiRead<T> request, MultiListener<T> procedure);
320
321     /**
322      * Asynchronously 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}
328      * 
329      * @param request an instance of {@link MultiRead}.
330      * @param procedure an instance of {@link AsyncMultiProcedure}.
331      */
332     <T> void asyncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure);
333
334     /**
335      * Asynchronously 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}
341      * 
342      * @param request an instance of {@link MultiRead}.
343      * @param procedure an instance of {@link SyncMultiProcedure}.
344      */
345     <T> void asyncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure);
346
347     /**
348      * Asynchronously 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}
353      * 
354      * @param request an instance of {@link MultiRead}.
355      * @param procedure an instance of {@link MultiProcedure}.
356      */
357     <T> void asyncRequest(MultiRead<T> request, MultiProcedure<T> procedure);
358
359     /**
360      * Asynchronously 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
365      * be lost.
366      * 
367      * @param request an instance of {@link AsyncMultiRead}.
368      */
369     <T> void asyncRequest(AsyncMultiRead<T> request);
370
371     /**
372      * Asynchronously registers the given {@link AsyncMultiListener} (as
373      * identified by {@link Object#equals(Object)}) to track changes in the
374      * result determined from the given {@link AsyncMultiRead}. Registers the
375      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
376      * any. Exceptions due to the determination of the result of the given
377      * {@link AsyncMultiRead} will be transferred to the given
378      * {@link AsyncMultiListener}.
379      * 
380      * @param request an instance of {@link AsyncMultiRead}.
381      * @param procedure an instance of {@link AsyncMultiListener}.
382      */
383     <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure);
384
385     /**
386      * Asynchronously registers the given {@link SyncMultiListener} (as
387      * identified by {@link Object#equals(Object)}) to track changes in the
388      * result determined from the given {@link AsyncMultiRead}. Registers the
389      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
390      * any. Exceptions due to the determination of the result of the given
391      * {@link AsyncMultiRead} will be transferred to the given
392      * {@link SyncMultiListener}
393      * 
394      * @param request an instance of {@link AsyncMultiRead}.
395      * @param procedure an instance of {@link SyncMultiListener}.
396      */
397     <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure);
398
399     /**
400      * Asynchronously registers the given {@link MultiListener} (as identified
401      * by {@link Object#equals(Object)}) to track changes in the result
402      * determined from the given {@link AsyncMultiRead}. Registers the given
403      * {@link AsyncMultiRead} as a dependency of the ongoing request if any.
404      * Exceptions due to the determination of the result of the given
405      * {@link AsyncMultiRead} will be transferred to the given
406      * {@link MultiListener}
407      * 
408      * @param request an instance of {@link AsyncMultiRead}.
409      * @param procedure an instance of {@link MultiListener}.
410      */
411     <T> void asyncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure);
412
413     /**
414      * Asynchronously supplies the result determined from the given
415      * {@link AsyncMultiRead} to the given {@link AsyncMultiProcedure}.
416      * Registers the given {@link AsyncMultiRead} as a dependency of the ongoing
417      * request if any. Exceptions due to the determination of the result of the
418      * given {@link AsyncMultiRead} will be transferred to the given
419      * {@link AsyncMultiProcedure}
420      * 
421      * @param request an instance of {@link AsyncMultiRead}.
422      * @param procedure an instance of {@link AsyncMultiProcedure}.
423      */
424     <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure);
425
426     /**
427      * Asynchronously supplies the result determined from the given
428      * {@link AsyncMultiRead} to the given {@link SyncMultiProcedure}. Registers
429      * the given {@link AsyncMultiRead} as a dependency of the ongoing request
430      * if any. Exceptions due to the determination of the result of the given
431      * {@link AsyncMultiRead} will be transferred to the given
432      * {@link SyncMultiProcedure}
433      * 
434      * @param request an instance of {@link AsyncMultiRead}.
435      * @param procedure an instance of {@link SyncMultiProcedure}.
436      */
437     <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure);
438
439     /**
440      * Asynchronously supplies the result determined from the given
441      * {@link AsyncMultiRead} to the given {@link MultiProcedure}. Registers the
442      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
443      * any. Exceptions due to the determination of the result of the given
444      * {@link AsyncMultiRead} will be transferred to the given
445      * {@link MultiProcedure}
446      * 
447      * @param request an instance of {@link AsyncMultiRead}.
448      * @param procedure an instance of {@link MultiProcedure}.
449      */
450     <T> void asyncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure);
451
452     /**
453      * Asynchronously determines the result of the given {@link AsyncMultiRead}
454      * and registers the given {@link AsyncMultiRead} as a dependency of the
455      * ongoing request if any. This is usually invoked for the side-effects of
456      * the given {@link AsyncMultiRead} but can also be used for e.g. dependency
457      * registering or cache priming. All exceptions from request processing will
458      * be lost.
459      * 
460      * @param request an instance of {@link AsyncMultiRead}.
461      */
462     <T> void asyncRequest(ExternalRead<T> request);
463     <T> void asyncRequest(ExternalRead<T> request, Listener<T> procedure);
464     <T> void asyncRequest(ExternalRead<T> request, Procedure<T> procedure);
465     
466     /**
467      * Asynchronously performs the given {@link Write}. The outcome of the
468      * request will be lost.
469      * 
470      * @param request an instance of {@link Write}.
471      */
472     void asyncRequest(Write request);
473
474     /**
475      * Asynchronously performs the given {@link Write}. The outcome of the
476      * request will be reported to given {@link Consumer} in the form of a
477      * DatabaseException raised during request processing or null upon success.
478      * 
479      * @param request an instance of {@link Write}.
480      * @param request an instance of {@link Consumer}.
481      */
482     void asyncRequest(Write request, Consumer<DatabaseException> callback);
483     
484     <T> void asyncRequest(WriteResult<T> r, Procedure<T> procedure);
485     
486
487     /**
488      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
489      * request will be lost.
490      * 
491      * @param request an instance of {@link Write}.
492      */
493     void asyncRequest(DelayedWrite request);
494
495     /**
496      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
497      * request will be reported to given {@link Consumer} in the form of a
498      * DatabaseException raised during request processing or null upon success.
499      * 
500      * @param request an instance of {@link WriteOnly}.
501      * @param request an instance of {@link Consumer}.
502      */
503     void asyncRequest(DelayedWrite request, Consumer<DatabaseException> callback);
504
505     <T> void asyncRequest(DelayedWriteResult<T> r, Procedure<T> procedure);
506
507     /**
508      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
509      * request will be lost.
510      * 
511      * @param request an instance of {@link Write}.
512      */
513     void asyncRequest(WriteOnly r);
514
515     /**
516      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
517      * request will be reported to given {@link Consumer} in the form of a
518      * DatabaseException raised during request processing or null upon success.
519      * 
520      * @param request an instance of {@link WriteOnly}.
521      * @param request an instance of {@link Consumer}.
522      */
523     void asyncRequest(WriteOnly r, Consumer<DatabaseException> callback);
524     
525     <T> void asyncRequest(WriteOnlyResult<T> r, Procedure<T> procedure);
526     
527 }