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