bundles/org.simantics.db/src/org/simantics/db/RequestProcessorSpecific.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.Collection;
  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 synchronous 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 RequestProcessors are
  55  * <ul>
  56  * <li>{@link ReadGraph} 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 an asynchronous counterpart with the same
  64  * functionality as RequestProcessor see {@link AsyncRequestProcessor}
  65  *
  66  * <p>
  67  * <b>IMPORTANT:</b>A client invoking any of the <code>syncRequest</code>
  68  * -methods in this interface must not assume that the request is performed
  69  * within the same thread that performed the <code>syncRequest</code>
  70  * invocation. This is an implementation-specific matter.
  71  *
  72  * @version 0.7
  73  * @author Antti Villberg
  74  * @see Read
  75  * @see AsyncRead
  76  * @see MultiRead
  77  * @see AsyncMultiRead
  78  * @see Write
  79  * @see WriteOnly
  80  * @see ReadGraph
  81  * @see Session
  82  * @see MergingGraphRequestProcessor
  83  * @see AsyncRequestProcessor
  84  */
  85 public interface RequestProcessorSpecific extends AsyncRequestProcessor {
  86
  87     /**
  88      * Synchronously determines and returns the result of the given {@link Read}
  89      * and registers the given {@link Read} as a dependency of the ongoing
  90      * request if any. This is usually invoked for the side-effects of the given
  91      * {@link Read} but can also be used for e.g. dependency registering or
  92      * cache priming.
  93      *
  94      * @param request an instance of {@link Read}
  95      * @return the result of the given {@link Read}
  96      * @throws DatabaseException from {@link Read#perform(ReadGraph)} or from
  97      *         request processing system
  98      */
  99     <T> T syncRequest(Read<T> request) throws DatabaseException;
 100
 101     /**
 102      * Synchronously registers the given {@link AsyncListener} (as identified
 103      * by {@link Object#equals(Object)}) to track changes in the result
 104      * determined from the given {@link Read}. Registers the given {@link Read}
 105      * as a dependency of the ongoing request if any. Exceptions due to the
 106      * determination of the result of the given {@link Read} will be transferred
 107      * to the given {@link AsyncListener}.
 108      *
 109      * @param request an instance of {@link Read}.
 110      * @param procedure an instance of {@link AsyncListener}.
 111      */
 112     //<T> T syncRequest(Read<T> request, AsyncListener<T> procedure) throws DatabaseException;
 113
 114     /**
 115      * Synchronously registers the given {@link SyncListener} (as identified by
 116      * {@link Object#equals(Object)}) to track changes in the result determined
 117      * from the given {@link Read}. Registers the given {@link Read} as a
 118      * dependency of the ongoing request if any. Exceptions due to the
 119      * determination of the result of the given {@link Read} will be transferred
 120      * to the given {@link SyncListener}
 121      *
 122      * @param request an instance of {@link Read}.
 123      * @param procedure an instance of {@link SyncListener}.
 124      */
 125     <T> T syncRequest(Read<T> request, SyncListener<T> procedure) throws DatabaseException;
 126
 127     /**
 128      * Synchronously registers the given {@link Listener} (as identified by
 129      * {@link Object#equals(Object)}) to track changes in the result determined
 130      * from the given {@link Read}. Registers the given {@link Read} as a
 131      * dependency of the ongoing request if any. Exceptions due to the
 132      * determination of the result of the given {@link Read} will be transferred
 133      * to the given {@link Listener}
 134      *
 135      * @param request an instance of {@link Read}.
 136      * @param procedure an instance of {@link Listener}.
 137      */
 138     <T> T syncRequest(Read<T> request, Listener<T> procedure) throws DatabaseException;
 139
 140     /**
 141      * Synchronously supplies the result determined from the given {@link Read}
 142      * to the given {@link AsyncProcedure}. Registers the given {@link Read} as
 143      * a dependency of the ongoing request if any. Exceptions due to the
 144      * determination of the result of the given {@link Read} will be transferred
 145      * to the given {@link AsyncProcedure}
 146      *
 147      * @param request an instance of {@link Read}.
 148      * @param procedure an instance of {@link AsyncProcedure}.
 149      */
 150     <T> T syncRequest(Read<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
 151
 152     /**
 153      * Synchronously supplies the result determined from the given {@link Read}
 154      * to the given {@link SyncProcedure}. Registers the given {@link Read} as a
 155      * dependency of the ongoing request if any. Exceptions due to the
 156      * determination of the result of the given {@link Read} will be transferred
 157      * to the given {@link SyncProcedure}
 158      *
 159      * @param request an instance of {@link Read}.
 160      * @param procedure an instance of {@link SyncProcedure}.
 161      */
 162     <T> T syncRequest(Read<T> request, SyncProcedure<T> procedure) throws DatabaseException;
 163
 164     /**
 165      * Synchronously supplies the result determined from the given {@link Read}
 166      * to the given {@link Procedure}. Registers the given {@link Read} as a
 167      * dependency of the ongoing request if any. Exceptions due to the
 168      * determination of the result of the given {@link Read} will be transferred
 169      * to the given {@link Procedure}
 170      *
 171      * @param request an instance of {@link Read}.
 172      * @param procedure an instance of {@link Procedure}.
 173      */
 174     <T> T syncRequest(Read<T> request, Procedure<T> procedure) throws DatabaseException;
 175
 176     /**
 177      * Synchronously determines the result of the given {@link AsyncRead} and
 178      * registers the given {@link AsyncRead} as a dependency of the ongoing
 179      * request if any. This is usually invoked for the side-effects of the given
 180      * {@link AsyncRead} but can also be used for e.g. dependency registering or
 181      * cache priming.
 182      *
 183      * @param request an instance of {@link AsyncRead}.
 184      * @return the result of the given {@link AsyncRead}
 185      * @throws DatabaseException from {@link AsyncRead#perform(AsyncReadGraph)} or from
 186      *         request processing system
 187      */
 188     <T> T syncRequest(AsyncRead<T> request) throws DatabaseException;
 189
 190     /**
 191      * Synchronously registers the given {@link AsyncListener} (as identified
 192      * by {@link Object#equals(Object)}) to track changes in the result
 193      * determined from the given {@link AsyncRead}. Registers the given
 194      * {@link AsyncRead} as a dependency of the ongoing request if any.
 195      * Exceptions due to the determination of the result of the given
 196      * {@link AsyncRead} will be transferred to the given {@link AsyncListener}.
 197      *
 198      * @param request an instance of {@link AsyncRead}.
 199      * @param procedure an instance of {@link AsyncListener}.
 200      */
 201     <T> T syncRequest(AsyncRead<T> request, AsyncListener<T> procedure) throws DatabaseException;
 202
 203     /**
 204      * Synchronously registers the given {@link SyncListener} (as identified by
 205      * {@link Object#equals(Object)}) to track changes in the result determined
 206      * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
 207      * as a dependency of the ongoing request if any. Exceptions due to the
 208      * determination of the result of the given {@link AsyncRead} will be
 209      * transferred to the given {@link SyncListener}
 210      *
 211      * @param request an instance of {@link AsyncRead}.
 212      * @param procedure an instance of {@link SyncListener}.
 213      */
 214     <T> T syncRequest(AsyncRead<T> request, SyncListener<T> procedure) throws DatabaseException;
 215
 216     /**
 217      * Synchronously registers the given {@link Listener} (as identified by
 218      * {@link Object#equals(Object)}) to track changes in the result determined
 219      * from the given {@link AsyncRead}. Registers the given {@link AsyncRead}
 220      * as a dependency of the ongoing request if any. Exceptions due to the
 221      * determination of the result of the given {@link AsyncRead} will be
 222      * transferred to the given {@link Listener}
 223      *
 224      * @param request an instance of {@link AsyncRead}.
 225      * @param procedure an instance of {@link Listener}.
 226      */
 227     <T> T syncRequest(AsyncRead<T> request, Listener<T> procedure) throws DatabaseException;
 228
 229     /**
 230      * Synchronously supplies the result determined from the given
 231      * {@link AsyncRead} to the given {@link AsyncProcedure}. Registers the
 232      * given {@link AsyncRead} as a dependency of the ongoing request if any.
 233      * Exceptions due to the determination of the result of the given
 234      * {@link AsyncRead} will be transferred to the given {@link AsyncProcedure}
 235      *
 236      * @param request an instance of {@link AsyncRead}.
 237      * @param procedure an instance of {@link AsyncProcedure}.
 238      */
 239     <T> T syncRequest(AsyncRead<T> request, AsyncProcedure<T> procedure) throws DatabaseException;
 240
 241     /**
 242      * Synchronously supplies the result determined from the given
 243      * {@link AsyncRead} to the given {@link SyncProcedure}. Registers the given
 244      * {@link AsyncRead} as a dependency of the ongoing request if any.
 245      * Exceptions due to the determination of the result of the given
 246      * {@link AsyncRead} will be transferred to the given {@link SyncProcedure}
 247      *
 248      * @param request an instance of {@link AsyncRead}.
 249      * @param procedure an instance of {@link SyncProcedure}.
 250      */
 251     <T> T syncRequest(AsyncRead<T> request, SyncProcedure<T> procedure) throws DatabaseException;
 252
 253     /**
 254      * Synchronously supplies the result determined from the given
 255      * {@link AsyncRead} to the given {@link Procedure}. Registers the given
 256      * {@link AsyncRead} as a dependency of the ongoing request if any.
 257      * Exceptions due to the determination of the result of the given
 258      * {@link AsyncRead} will be transferred to the given {@link Procedure}
 259      *
 260      * @param request an instance of {@link AsyncRead}.
 261      * @param procedure an instance of {@link Procedure}.
 262      */
 263     <T> T syncRequest(AsyncRead<T> request, Procedure<T> procedure) throws DatabaseException;
 264
 265     /**
 266      * Synchronously determines the result of the given {@link MultiRead} and
 267      * registers the given {@link MultiRead} as a dependency of the ongoing
 268      * request if any. This is usually invoked for the side-effects of the given
 269      * {@link MultiRead} but can also be used for e.g. dependency registering or
 270      * cache priming. All exceptions from request processing will be lost.
 271      *
 272      * @param request an instance of {@link MultiRead}.
 273      * @return the result of the given {@link MultiRead}
 274      * @throws DatabaseException from {@link MultiRead#perform(ReadGraph)} or from
 275      *         request processing system
 276      */
 277     <T> Collection<T> syncRequest(MultiRead<T> request) throws DatabaseException;
 278
 279     /**
 280      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
 292
 293     /**
 294      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
 306
 307     /**
 308      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
 319
 320     /**
 321      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
 332
 333     /**
 334      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
 345
 346     /**
 347      * Synchronously 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> Collection<T> syncRequest(MultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
 357
 358     /**
 359      * Synchronously 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      * @throws DatabaseException from {@link AsyncMultiRead#perform(AsyncReadGraph)} or from
 368      *         request processing system
 369      */
 370     <T> Collection<T> syncRequest(AsyncMultiRead<T> request) throws DatabaseException;
 371
 372     /**
 373      * Synchronously registers the given {@link AsyncMultiListener} (as
 374      * identified by {@link Object#equals(Object)}) to track changes in the
 375      * result determined from the given {@link AsyncMultiRead}. Registers the
 376      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
 377      * any. Exceptions due to the determination of the result of the given
 378      * {@link AsyncMultiRead} will be transferred to the given
 379      * {@link AsyncMultiListener}.
 380      *
 381      * @param request an instance of {@link AsyncMultiRead}.
 382      * @param procedure an instance of {@link AsyncMultiListener}.
 383      */
 384     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiListener<T> procedure) throws DatabaseException;
 385
 386     /**
 387      * Synchronously registers the given {@link SyncMultiListener} (as
 388      * identified by {@link Object#equals(Object)}) to track changes in the
 389      * result determined from the given {@link AsyncMultiRead}. Registers the
 390      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
 391      * any. Exceptions due to the determination of the result of the given
 392      * {@link AsyncMultiRead} will be transferred to the given
 393      * {@link SyncMultiListener}
 394      *
 395      * @param request an instance of {@link AsyncMultiRead}.
 396      * @param procedure an instance of {@link SyncMultiListener}.
 397      */
 398     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiListener<T> procedure) throws DatabaseException;
 399
 400     /**
 401      * Synchronously registers the given {@link MultiListener} (as identified
 402      * by {@link Object#equals(Object)}) to track changes in the result
 403      * determined from the given {@link AsyncMultiRead}. Registers the given
 404      * {@link AsyncMultiRead} as a dependency of the ongoing request if any.
 405      * Exceptions due to the determination of the result of the given
 406      * {@link AsyncMultiRead} will be transferred to the given
 407      * {@link MultiListener}
 408      *
 409      * @param request an instance of {@link AsyncMultiRead}.
 410      * @param procedure an instance of {@link MultiListener}.
 411      */
 412     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiListener<T> procedure) throws DatabaseException;
 413
 414     /**
 415      * Synchronously supplies the result determined from the given
 416      * {@link AsyncMultiRead} to the given {@link AsyncMultiProcedure}.
 417      * Registers the given {@link AsyncMultiRead} as a dependency of the ongoing
 418      * request if any. Exceptions due to the determination of the result of the
 419      * given {@link AsyncMultiRead} will be transferred to the given
 420      * {@link AsyncMultiProcedure}
 421      *
 422      * @param request an instance of {@link AsyncMultiRead}.
 423      * @param procedure an instance of {@link AsyncMultiProcedure}.
 424      */
 425     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, AsyncMultiProcedure<T> procedure) throws DatabaseException;
 426
 427     /**
 428      * Synchronously supplies the result determined from the given
 429      * {@link AsyncMultiRead} to the given {@link SyncMultiProcedure}. Registers
 430      * the given {@link AsyncMultiRead} as a dependency of the ongoing request
 431      * if any. Exceptions due to the determination of the result of the given
 432      * {@link AsyncMultiRead} will be transferred to the given
 433      * {@link SyncMultiProcedure}
 434      *
 435      * @param request an instance of {@link AsyncMultiRead}.
 436      * @param procedure an instance of {@link SyncMultiProcedure}.
 437      */
 438     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, SyncMultiProcedure<T> procedure) throws DatabaseException;
 439
 440     /**
 441      * Synchronously supplies the result determined from the given
 442      * {@link AsyncMultiRead} to the given {@link MultiProcedure}. Registers the
 443      * given {@link AsyncMultiRead} as a dependency of the ongoing request if
 444      * any. Exceptions due to the determination of the result of the given
 445      * {@link AsyncMultiRead} will be transferred to the given
 446      * {@link MultiProcedure}
 447      *
 448      * @param request an instance of {@link AsyncMultiRead}.
 449      * @param procedure an instance of {@link MultiProcedure}.
 450      */
 451     <T> Collection<T> syncRequest(AsyncMultiRead<T> request, MultiProcedure<T> procedure) throws DatabaseException;
 452
 453
 454     <T> T syncRequest(ExternalRead<T> request) throws DatabaseException;
 455     <T> T syncRequest(ExternalRead<T> request, Listener<T> procedure) throws DatabaseException;
 456     <T> T syncRequest(ExternalRead<T> request, Procedure<T> procedure) throws DatabaseException;
 457
 458     /**
 459      * Synchronously performs the given {@link Write}.
 460      *
 461      * @param request an instance of {@link Write}.
 462      */
 463     void syncRequest(Write request) throws DatabaseException;
 464
 465     /**
 466      * Synchronously performs the given {@link DelayedWrite}.
 467      *
 468      * @param request an instance of {@link DelayedWrite}.
 469      */
 470     void syncRequest(DelayedWrite request) throws DatabaseException;
 471
 472     /**
 473      * Synchronously performs the given {@link WriteOnly}.
 474      *
 475      * @param request an instance of {@link Write}.
 476      */
 477     void syncRequest(WriteOnly r) throws DatabaseException;
 478
 479     /**
 480      * Synchronously performs the given {@link Write}.
 481      *
 482      * @param request an instance of {@link Write}.
 483      */
 484     <T> T syncRequest(WriteResult<T> request) throws DatabaseException;
 485
 486     /**
 487      * Synchronously performs the given {@link DelayedWrite}.
 488      *
 489      * @param request an instance of {@link DelayedWrite}.
 490      */
 491     <T> T syncRequest(DelayedWriteResult<T> request) throws DatabaseException;
 492
 493     /**
 494      * Synchronously performs the given {@link WriteOnly}.
 495      *
 496      * @param request an instance of {@link Write}.
 497      */
 498     <T> T syncRequest(WriteOnlyResult<T> r) throws DatabaseException;
 499
 500 }