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 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;
  39
  40 /**
  41  *
  42  * For initiating requests in asynchronous manner. The possible requests are
  43  * <ul>
  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
  48  * asynchronously
  49  * <li>{@link Write} for reading and writing synchronously
  50  * <li>{@link WriteOnly} for writing synchronously
  51  * </ul>
  52  * <p>
  53  * The standard AsyncRequestProcessors are
  54  * <ul>
  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
  58  * single transaction
  59  * </ul>
  60  *
  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}
  64  *
  65  * @version 0.7
  66  * @author Antti Villberg
  67  * @see Read
  68  * @see AsyncRead
  69  * @see MultiRead
  70  * @see AsyncMultiRead
  71  * @see Write
  72  * @see WriteOnly
  73  * @see AsyncReadGraph
  74  * @see Session
  75  * @see MergingGraphRequestProcessor
  76  * @see RequestProcessor
  77  */
  78 public interface AsyncRequestProcessorSpecific extends ServiceLocator {
  79
  80     /**
  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>.
  88      *
  89      * @deprecated in favor of org.simantics.layer0.Layer0. Will be removed in Simantics 1.2
  90      *
  91      * @return the <code>Builtins</code> instance associated with this session.
  92      */
  93 //    @Deprecated
  94 //    Builtins getBuiltins();
  95
  96     /**
  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.
 102      *
 103      * @param request an instance of {@link Read}.
 104      */
 105     <T> void asyncRequest(Read<T> request);
 106
 107     /**
 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}.
 114      *
 115      * @param request an instance of {@link Read}.
 116      * @param procedure an instance of {@link AsyncListener}.
 117      */
 118     <T> void asyncRequest(Read<T> request, AsyncListener<T> procedure);
 119
 120     /**
 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}
 127      *
 128      * @param request an instance of {@link Read}.
 129      * @param procedure an instance of {@link SyncListener}.
 130      */
 131     <T> void asyncRequest(Read<T> request, SyncListener<T> procedure);
 132
 133     /**
 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}
 140      *
 141      * @param request an instance of {@link Read}.
 142      * @param procedure an instance of {@link Listener}.
 143      */
 144     <T> void asyncRequest(Read<T> request, Listener<T> procedure);
 145
 146     /**
 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}
 152      *
 153      * @param request an instance of {@link Read}.
 154      * @param procedure an instance of {@link AsyncProcedure}.
 155      */
 156     <T> void asyncRequest(Read<T> request, AsyncProcedure<T> procedure);
 157
 158     /**
 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}
 164      *
 165      * @param request an instance of {@link Read}.
 166      * @param procedure an instance of {@link SyncProcedure}.
 167      */
 168     <T> void asyncRequest(Read<T> request, SyncProcedure<T> procedure);
 169
 170     /**
 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}
 176      *
 177      * @param request an instance of {@link Read}.
 178      * @param procedure an instance of {@link Procedure}.
 179      */
 180     <T> void asyncRequest(Read<T> request, Procedure<T> procedure);
 181
 182     /**
 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.
 188      *
 189      * @param request an instance of {@link AsyncRead}.
 190      */
 191     <T> void asyncRequest(AsyncRead<T> request);
 192
 193     /**
 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}.
 200      *
 201      * @param request an instance of {@link AsyncRead}.
 202      * @param procedure an instance of {@link AsyncListener}.
 203      */
 204     <T> void asyncRequest(AsyncRead<T> request, AsyncListener<T> procedure);
 205
 206     /**
 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}
 213      *
 214      * @param request an instance of {@link AsyncRead}.
 215      * @param procedure an instance of {@link SyncListener}.
 216      */
 217     <T> void asyncRequest(AsyncRead<T> request, SyncListener<T> procedure);
 218
 219     /**
 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}
 226      *
 227      * @param request an instance of {@link AsyncRead}.
 228      * @param procedure an instance of {@link Listener}.
 229      */
 230     <T> void asyncRequest(AsyncRead<T> request, Listener<T> procedure);
 231
 232     /**
 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}
 238      *
 239      * @param request an instance of {@link AsyncRead}.
 240      * @param procedure an instance of {@link AsyncProcedure}.
 241      */
 242     <T> void asyncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure);
 243
 244     /**
 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}
 250      *
 251      * @param request an instance of {@link AsyncRead}.
 252      * @param procedure an instance of {@link SyncProcedure}.
 253      */
 254     <T> void asyncRequest(AsyncRead<T> request, SyncProcedure<T> procedure);
 255
 256     /**
 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}
 262      *
 263      * @param request an instance of {@link AsyncRead}.
 264      * @param procedure an instance of {@link Procedure}.
 265      */
 266     <T> void asyncRequest(AsyncRead<T> request, Procedure<T> procedure);
 267
 268     /**
 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.
 274      *
 275      * @param request an instance of {@link MultiRead}.
 276      */
 277     <T> void asyncRequest(MultiRead<T> request);
 278
 279     /**
 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}.
 287      *
 288      * @param request an instance of {@link MultiRead}.
 289      * @param procedure an instance of {@link AsyncMultiListener}.
 290      */
 291     <T> void asyncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure);
 292
 293     /**
 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}
 301      *
 302      * @param request an instance of {@link MultiRead}.
 303      * @param procedure an instance of {@link SyncMultiListener}.
 304      */
 305     <T> void asyncRequest(MultiRead<T> request, SyncMultiListener<T> procedure);
 306
 307     /**
 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}
 314      *
 315      * @param request an instance of {@link MultiRead}.
 316      * @param procedure an instance of {@link MultiListener}.
 317      */
 318     <T> void asyncRequest(MultiRead<T> request, MultiListener<T> procedure);
 319
 320     /**
 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}
 327      *
 328      * @param request an instance of {@link MultiRead}.
 329      * @param procedure an instance of {@link AsyncMultiProcedure}.
 330      */
 331     <T> void asyncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure);
 332
 333     /**
 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}
 340      *
 341      * @param request an instance of {@link MultiRead}.
 342      * @param procedure an instance of {@link SyncMultiProcedure}.
 343      */
 344     <T> void asyncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure);
 345
 346     /**
 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}
 352      *
 353      * @param request an instance of {@link MultiRead}.
 354      * @param procedure an instance of {@link MultiProcedure}.
 355      */
 356     <T> void asyncRequest(MultiRead<T> request, MultiProcedure<T> procedure);
 357
 358     /**
 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
 364      * be lost.
 365      *
 366      * @param request an instance of {@link AsyncMultiRead}.
 367      */
 368     <T> void asyncRequest(AsyncMultiRead<T> request);
 369
 370     /**
 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}.
 378      *
 379      * @param request an instance of {@link AsyncMultiRead}.
 380      * @param procedure an instance of {@link AsyncMultiListener}.
 381      */
 382     <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure);
 383
 384     /**
 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}
 392      *
 393      * @param request an instance of {@link AsyncMultiRead}.
 394      * @param procedure an instance of {@link SyncMultiListener}.
 395      */
 396     <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure);
 397
 398     /**
 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}
 406      *
 407      * @param request an instance of {@link AsyncMultiRead}.
 408      * @param procedure an instance of {@link MultiListener}.
 409      */
 410     <T> void asyncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure);
 411
 412     /**
 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}
 419      *
 420      * @param request an instance of {@link AsyncMultiRead}.
 421      * @param procedure an instance of {@link AsyncMultiProcedure}.
 422      */
 423     <T> void asyncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure);
 424
 425     /**
 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}
 432      *
 433      * @param request an instance of {@link AsyncMultiRead}.
 434      * @param procedure an instance of {@link SyncMultiProcedure}.
 435      */
 436     <T> void asyncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure);
 437
 438     /**
 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}
 445      *
 446      * @param request an instance of {@link AsyncMultiRead}.
 447      * @param procedure an instance of {@link MultiProcedure}.
 448      */
 449     <T> void asyncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure);
 450
 451     /**
 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
 457      * be lost.
 458      *
 459      * @param request an instance of {@link AsyncMultiRead}.
 460      */
 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);
 464
 465     /**
 466      * Asynchronously performs the given {@link Write}. The outcome of the
 467      * request will be lost.
 468      *
 469      * @param request an instance of {@link Write}.
 470      */
 471     void asyncRequest(Write request);
 472
 473     /**
 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.
 477      *
 478      * @param request an instance of {@link Write}.
 479      * @param request an instance of {@link Callback}.
 480      */
 481     void asyncRequest(Write request, Callback<DatabaseException> callback);
 482
 483     <T> void asyncRequest(WriteResult<T> r, Procedure<T> procedure);
 484
 485
 486     /**
 487      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
 488      * request will be lost.
 489      *
 490      * @param request an instance of {@link Write}.
 491      */
 492     void asyncRequest(DelayedWrite request);
 493
 494     /**
 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.
 498      *
 499      * @param request an instance of {@link WriteOnly}.
 500      * @param request an instance of {@link Callback}.
 501      */
 502     void asyncRequest(DelayedWrite request, Callback<DatabaseException> callback);
 503
 504     <T> void asyncRequest(DelayedWriteResult<T> r, Procedure<T> procedure);
 505
 506     /**
 507      * Asynchronously performs the given {@link WriteOnly}. The outcome of the
 508      * request will be lost.
 509      *
 510      * @param request an instance of {@link Write}.
 511      */
 512     void asyncRequest(WriteOnly r);
 513
 514     /**
 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.
 518      *
 519      * @param request an instance of {@link WriteOnly}.
 520      * @param request an instance of {@link Callback}.
 521      */
 522     void asyncRequest(WriteOnly r, Callback<DatabaseException> callback);
 523
 524     <T> void asyncRequest(WriteOnlyResult<T> r, Procedure<T> procedure);
 525
 526 }