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 org.simantics.db.exception.DatabaseException;
\r
15 import org.simantics.db.procedure.AsyncListener;
\r
16 import org.simantics.db.procedure.AsyncMultiListener;
\r
17 import org.simantics.db.procedure.AsyncMultiProcedure;
\r
18 import org.simantics.db.procedure.AsyncProcedure;
\r
19 import org.simantics.db.procedure.Listener;
\r
20 import org.simantics.db.procedure.MultiListener;
\r
21 import org.simantics.db.procedure.MultiProcedure;
\r
22 import org.simantics.db.procedure.Procedure;
\r
23 import org.simantics.db.procedure.SyncListener;
\r
24 import org.simantics.db.procedure.SyncMultiListener;
\r
25 import org.simantics.db.procedure.SyncMultiProcedure;
\r
26 import org.simantics.db.procedure.SyncProcedure;
\r
27 import org.simantics.db.request.AsyncMultiRead;
\r
28 import org.simantics.db.request.AsyncRead;
\r
29 import org.simantics.db.request.DelayedWrite;
\r
30 import org.simantics.db.request.DelayedWriteResult;
\r
31 import org.simantics.db.request.ExternalRead;
\r
32 import org.simantics.db.request.MultiRead;
\r
33 import org.simantics.db.request.Read;
\r
34 import org.simantics.db.request.Write;
\r
35 import org.simantics.db.request.WriteOnly;
\r
36 import org.simantics.db.request.WriteOnlyResult;
\r
37 import org.simantics.db.request.WriteResult;
\r
38 import org.simantics.utils.datastructures.Callback;
\r
42 * For initiating requests in asynchronous manner. The possible requests are
\r
44 * <li>{@link Read} for computing a single result synchronously
\r
45 * <li>{@link AsyncRead} for computing a single result asynchronously
\r
46 * <li>{@link MultiRead} for computing a collection of results synchronously
\r
47 * <li>{@link AsyncMultiRead} for computing a collection of results
\r
49 * <li>{@link Write} for reading and writing synchronously
\r
50 * <li>{@link WriteOnly} for writing synchronously
\r
53 * The standard AsyncRequestProcessors are
\r
55 * <li>{@link AsyncReadGraph} for performing requests during other requests
\r
56 * <li>{@link Session} for initiating a transactions for performing requests
\r
57 * <li>{@link MergingGraphRequestProcessor} for merging several requests in a
\r
58 * single transaction
\r
61 * Database services (see e.g. {@link Session}) are available from implemented
\r
62 * {@link ServiceLocator}. For a synchronous counterpart with the same
\r
63 * functionality as AsyncRequestProcessor see {@link RequestProcessor}
\r
66 * @author Antti Villberg
\r
70 * @see AsyncMultiRead
\r
73 * @see AsyncReadGraph
\r
75 * @see MergingGraphRequestProcessor
\r
76 * @see RequestProcessor
\r
78 public interface AsyncRequestProcessorSpecific extends ServiceLocator {
\r
81 * Provides access to a set of standard resources defined in Layer0. The
\r
82 * existence of {@link Builtins} is guaranteed at {@link Session} creation
\r
83 * time hence the method does not throw. It is also assumed that the
\r
84 * identify of the standard resources cannot change during sessions. To work
\r
85 * this requires that Builtins.class has been registered with this
\r
86 * ServiceLocator. Therefore this is merely a shorthand for
\r
87 * <code>ServiceLocator.getService(Builtins.class)</code>.
\r
89 * @deprecated in favor of org.simantics.layer0.Layer0. Will be removed in Simantics 1.2
\r
91 * @return the <code>Builtins</code> instance associated with this session.
\r
94 // Builtins getBuiltins();
\r
97 * Asynchronously determines the result of the given {@link Read} and
\r
98 * registers the given {@link Read} as a dependency of the ongoing request
\r
99 * if any. This is usually invoked for the side-effects of the given
\r
100 * {@link Read} but can also be used for e.g. dependency registering or
\r
101 * cache priming. All exceptions from request processing will be lost.
\r
103 * @param request an instance of {@link Read}.
\r
105 <T> void asyncRequest(Read<T> request);
\r
108 * Asynchronously registers the given {@link AsyncListener} (as identified
\r
109 * by {@link Object#equals(Object)}) to track changes in the result
\r
110 * determined from the given {@link Read}. Registers the given {@link Read}
\r
111 * as a dependency of the ongoing request if any. Exceptions due to the
\r
112 * determination of the result of the given {@link Read} will be transferred
\r
113 * to the given {@link AsyncListener}.
\r
115 * @param request an instance of {@link Read}.
\r
116 * @param procedure an instance of {@link AsyncListener}.
\r
118 <T> void asyncRequest(Read<T> request, AsyncListener<T> procedure);
\r
121 * Asynchronously registers the given {@link SyncListener} (as identified by
\r
122 * {@link Object#equals(Object)}) to track changes in the result determined
\r
123 * from the given {@link Read}. Registers the given {@link Read} as a
\r
124 * dependency of the ongoing request if any. Exceptions due to the
\r
125 * determination of the result of the given {@link Read} will be transferred
\r
126 * to the given {@link SyncListener}
\r
128 * @param request an instance of {@link Read}.
\r
129 * @param procedure an instance of {@link SyncListener}.
\r
131 <T> void asyncRequest(Read<T> request, SyncListener<T> procedure);
\r
134 * Asynchronously registers the given {@link Listener} (as identified by
\r
135 * {@link Object#equals(Object)}) to track changes in the result determined
\r
136 * from the given {@link Read}. Registers the given {@link Read} as a
\r
137 * dependency of the ongoing request if any. Exceptions due to the
\r
138 * determination of the result of the given {@link Read} will be transferred
\r
139 * to the given {@link Listener}
\r
141 * @param request an instance of {@link Read}.
\r
142 * @param procedure an instance of {@link Listener}.
\r
144 <T> void asyncRequest(Read<T> request, Listener<T> procedure);
\r
147 * Asynchronously supplies the result determined from the given {@link Read}
\r
148 * to the given {@link AsyncProcedure}. Registers the given {@link Read} as
\r
149 * a dependency of the ongoing request if any. Exceptions due to the
\r
150 * determination of the result of the given {@link Read} will be transferred
\r
151 * to the given {@link AsyncProcedure}
\r
153 * @param request an instance of {@link Read}.
\r
154 * @param procedure an instance of {@link AsyncProcedure}.
\r
156 <T> void asyncRequest(Read<T> request, AsyncProcedure<T> procedure);
\r
159 * Asynchronously supplies the result determined from the given {@link Read}
\r
160 * to the given {@link SyncProcedure}. Registers the given {@link Read} as a
\r
161 * dependency of the ongoing request if any. Exceptions due to the
\r
162 * determination of the result of the given {@link Read} will be transferred
\r
163 * to the given {@link SyncProcedure}
\r
165 * @param request an instance of {@link Read}.
\r
166 * @param procedure an instance of {@link SyncProcedure}.
\r
168 <T> void asyncRequest(Read<T> request, SyncProcedure<T> procedure);
\r
171 * Asynchronously supplies the result determined from the given {@link Read}
\r
172 * to the given {@link Procedure}. Registers the given {@link Read} as a
\r
173 * dependency of the ongoing request if any. Exceptions due to the
\r
174 * determination of the result of the given {@link Read} will be transferred
\r
175 * to the given {@link Procedure}
\r
177 * @param request an instance of {@link Read}.
\r
178 * @param procedure an instance of {@link Procedure}.
\r
180 <T> void asyncRequest(Read<T> request, Procedure<T> procedure);
\r
183 * Asynchronously determines the result of the given {@link AsyncRead} and
\r
184 * registers the given {@link AsyncRead} as a dependency of the ongoing
\r
185 * request if any. This is usually invoked for the side-effects of the given
\r
186 * {@link AsyncRead} but can also be used for e.g. dependency registering or
\r
187 * cache priming. All exceptions from request processing will be lost.
\r
189 * @param request an instance of {@link AsyncRead}.
\r
191 <T> void asyncRequest(AsyncRead<T> request);
\r
194 * Asynchronously registers the given {@link AsyncListener} (as identified
\r
195 * by {@link Object#equals(Object)}) to track changes in the result
\r
196 * determined from the given {@link AsyncRead}. Registers the given
\r
197 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
198 * Exceptions due to the determination of the result of the given
\r
199 * {@link AsyncRead} will be transferred to the given {@link AsyncListener}.
\r
201 * @param request an instance of {@link AsyncRead}.
\r
202 * @param procedure an instance of {@link AsyncListener}.
\r
204 <T> void asyncRequest(AsyncRead<T> request, AsyncListener<T> procedure);
\r
207 * Asynchronously registers the given {@link SyncListener} (as identified by
\r
208 * {@link Object#equals(Object)}) to track changes in the result determined
\r
209 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
\r
210 * as a dependency of the ongoing request if any. Exceptions due to the
\r
211 * determination of the result of the given {@link AsyncRead} will be
\r
212 * transferred to the given {@link SyncListener}
\r
214 * @param request an instance of {@link AsyncRead}.
\r
215 * @param procedure an instance of {@link SyncListener}.
\r
217 <T> void asyncRequest(AsyncRead<T> request, SyncListener<T> procedure);
\r
220 * Asynchronously registers the given {@link Listener} (as identified by
\r
221 * {@link Object#equals(Object)}) to track changes in the result determined
\r
222 * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
\r
223 * as a dependency of the ongoing request if any. Exceptions due to the
\r
224 * determination of the result of the given {@link AsyncRead} will be
\r
225 * transferred to the given {@link Listener}
\r
227 * @param request an instance of {@link AsyncRead}.
\r
228 * @param procedure an instance of {@link Listener}.
\r
230 <T> void asyncRequest(AsyncRead<T> request, Listener<T> procedure);
\r
233 * Asynchronously supplies the result determined from the given
\r
234 * {@link AsyncRead} to the given {@link AsyncProcedure}. Registers the
\r
235 * given {@link AsyncRead} as a dependency of the ongoing request if any.
\r
236 * Exceptions due to the determination of the result of the given
\r
237 * {@link AsyncRead} will be transferred to the given {@link AsyncProcedure}
\r
239 * @param request an instance of {@link AsyncRead}.
\r
240 * @param procedure an instance of {@link AsyncProcedure}.
\r
242 <T> void asyncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure);
\r
245 * Asynchronously supplies the result determined from the given
\r
246 * {@link AsyncRead} to the given {@link SyncProcedure}. Registers the given
\r
247 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
248 * Exceptions due to the determination of the result of the given
\r
249 * {@link AsyncRead} will be transferred to the given {@link SyncProcedure}
\r
251 * @param request an instance of {@link AsyncRead}.
\r
252 * @param procedure an instance of {@link SyncProcedure}.
\r
254 <T> void asyncRequest(AsyncRead<T> request, SyncProcedure<T> procedure);
\r
257 * Asynchronously supplies the result determined from the given
\r
258 * {@link AsyncRead} to the given {@link Procedure}. Registers the given
\r
259 * {@link AsyncRead} as a dependency of the ongoing request if any.
\r
260 * Exceptions due to the determination of the result of the given
\r
261 * {@link AsyncRead} will be transferred to the given {@link Procedure}
\r
263 * @param request an instance of {@link AsyncRead}.
\r
264 * @param procedure an instance of {@link Procedure}.
\r
266 <T> void asyncRequest(AsyncRead<T> request, Procedure<T> procedure);
\r
269 * Asynchronously determines the result of the given {@link MultiRead} and
\r
270 * registers the given {@link MultiRead} as a dependency of the ongoing
\r
271 * request if any. This is usually invoked for the side-effects of the given
\r
272 * {@link MultiRead} but can also be used for e.g. dependency registering or
\r
273 * cache priming. All exceptions from request processing will be lost.
\r
275 * @param request an instance of {@link MultiRead}.
\r
277 <T> void asyncRequest(MultiRead<T> request);
\r
280 * Asynchronously 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> void asyncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure);
\r
294 * Asynchronously 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> void asyncRequest(MultiRead<T> request, SyncMultiListener<T> procedure);
\r
308 * Asynchronously 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> void asyncRequest(MultiRead<T> request, MultiListener<T> procedure);
\r
321 * Asynchronously 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> void asyncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure);
\r
334 * Asynchronously 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> void asyncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure);
\r
347 * Asynchronously 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> void asyncRequest(MultiRead<T> request, MultiProcedure<T> procedure);
\r
359 * Asynchronously 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
368 <T> void asyncRequest(AsyncMultiRead<T> request);
\r
371 * Asynchronously registers the given {@link AsyncMultiListener} (as
\r
372 * identified by {@link Object#equals(Object)}) to track changes in the
\r
373 * result determined from the given {@link AsyncMultiRead}. Registers the
\r
374 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
375 * any. Exceptions due to the determination of the result of the given
\r
376 * {@link AsyncMultiRead} will be transferred to the given
\r
377 * {@link AsyncMultiListener}.
\r
379 * @param request an instance of {@link AsyncMultiRead}.
\r
380 * @param procedure an instance of {@link AsyncMultiListener}.
\r
382 <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure);
\r
385 * Asynchronously registers the given {@link SyncMultiListener} (as
\r
386 * identified by {@link Object#equals(Object)}) to track changes in the
\r
387 * result determined from the given {@link AsyncMultiRead}. Registers the
\r
388 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
389 * any. Exceptions due to the determination of the result of the given
\r
390 * {@link AsyncMultiRead} will be transferred to the given
\r
391 * {@link SyncMultiListener}
\r
393 * @param request an instance of {@link AsyncMultiRead}.
\r
394 * @param procedure an instance of {@link SyncMultiListener}.
\r
396 <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure);
\r
399 * Asynchronously registers the given {@link MultiListener} (as identified
\r
400 * by {@link Object#equals(Object)}) to track changes in the result
\r
401 * determined from the given {@link AsyncMultiRead}. Registers the given
\r
402 * {@link AsyncMultiRead} as a dependency of the ongoing request if any.
\r
403 * Exceptions due to the determination of the result of the given
\r
404 * {@link AsyncMultiRead} will be transferred to the given
\r
405 * {@link MultiListener}
\r
407 * @param request an instance of {@link AsyncMultiRead}.
\r
408 * @param procedure an instance of {@link MultiListener}.
\r
410 <T> void asyncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure);
\r
413 * Asynchronously supplies the result determined from the given
\r
414 * {@link AsyncMultiRead} to the given {@link AsyncMultiProcedure}.
\r
415 * Registers the given {@link AsyncMultiRead} as a dependency of the ongoing
\r
416 * request if any. Exceptions due to the determination of the result of the
\r
417 * given {@link AsyncMultiRead} will be transferred to the given
\r
418 * {@link AsyncMultiProcedure}
\r
420 * @param request an instance of {@link AsyncMultiRead}.
\r
421 * @param procedure an instance of {@link AsyncMultiProcedure}.
\r
423 <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure);
\r
426 * Asynchronously supplies the result determined from the given
\r
427 * {@link AsyncMultiRead} to the given {@link SyncMultiProcedure}. Registers
\r
428 * the given {@link AsyncMultiRead} as a dependency of the ongoing request
\r
429 * if any. Exceptions due to the determination of the result of the given
\r
430 * {@link AsyncMultiRead} will be transferred to the given
\r
431 * {@link SyncMultiProcedure}
\r
433 * @param request an instance of {@link AsyncMultiRead}.
\r
434 * @param procedure an instance of {@link SyncMultiProcedure}.
\r
436 <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure);
\r
439 * Asynchronously supplies the result determined from the given
\r
440 * {@link AsyncMultiRead} to the given {@link MultiProcedure}. Registers the
\r
441 * given {@link AsyncMultiRead} as a dependency of the ongoing request if
\r
442 * any. Exceptions due to the determination of the result of the given
\r
443 * {@link AsyncMultiRead} will be transferred to the given
\r
444 * {@link MultiProcedure}
\r
446 * @param request an instance of {@link AsyncMultiRead}.
\r
447 * @param procedure an instance of {@link MultiProcedure}.
\r
449 <T> void asyncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure);
\r
452 * Asynchronously determines the result of the given {@link AsyncMultiRead}
\r
453 * and registers the given {@link AsyncMultiRead} as a dependency of the
\r
454 * ongoing request if any. This is usually invoked for the side-effects of
\r
455 * the given {@link AsyncMultiRead} but can also be used for e.g. dependency
\r
456 * registering or cache priming. All exceptions from request processing will
\r
459 * @param request an instance of {@link AsyncMultiRead}.
\r
461 <T> void asyncRequest(ExternalRead<T> request);
\r
462 <T> void asyncRequest(ExternalRead<T> request, Listener<T> procedure);
\r
463 <T> void asyncRequest(ExternalRead<T> request, Procedure<T> procedure);
\r
466 * Asynchronously performs the given {@link Write}. The outcome of the
\r
467 * request will be lost.
\r
469 * @param request an instance of {@link Write}.
\r
471 void asyncRequest(Write request);
\r
474 * Asynchronously performs the given {@link Write}. The outcome of the
\r
475 * request will be reported to given {@link Callback} in the form of a
\r
476 * DatabaseException raised during request processing or null upon success.
\r
478 * @param request an instance of {@link Write}.
\r
479 * @param request an instance of {@link Callback}.
\r
481 void asyncRequest(Write request, Callback<DatabaseException> callback);
\r
483 <T> void asyncRequest(WriteResult<T> r, Procedure<T> procedure);
\r
487 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
\r
488 * request will be lost.
\r
490 * @param request an instance of {@link Write}.
\r
492 void asyncRequest(DelayedWrite request);
\r
495 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
\r
496 * request will be reported to given {@link Callback} in the form of a
\r
497 * DatabaseException raised during request processing or null upon success.
\r
499 * @param request an instance of {@link WriteOnly}.
\r
500 * @param request an instance of {@link Callback}.
\r
502 void asyncRequest(DelayedWrite request, Callback<DatabaseException> callback);
\r
504 <T> void asyncRequest(DelayedWriteResult<T> r, Procedure<T> procedure);
\r
507 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
\r
508 * request will be lost.
\r
510 * @param request an instance of {@link Write}.
\r
512 void asyncRequest(WriteOnly r);
\r
515 * Asynchronously performs the given {@link WriteOnly}. The outcome of the
\r
516 * request will be reported to given {@link Callback} in the form of a
\r
517 * DatabaseException raised during request processing or null upon success.
\r
519 * @param request an instance of {@link WriteOnly}.
\r
520 * @param request an instance of {@link Callback}.
\r
522 void asyncRequest(WriteOnly r, Callback<DatabaseException> callback);
\r
524 <T> void asyncRequest(WriteOnlyResult<T> r, Procedure<T> procedure);
\r