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 }