bundles/org.simantics.db/src/org/simantics/db/RequestProcessor.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2018 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.Procedure;
  16 import org.simantics.db.request.ReadInterface;
  17 import org.simantics.db.request.WriteInterface;
  18
  19 /**
  20  *
  21  * For initiating requests in synchronous manner. The possible requests are
  22  * <ul>
  23  * <li>{@link ReadInterface} for computing a single result
  24  * <li>{@link WriteInterface} for making a modification into the database
  25  * </ul>
  26  * <p>
  27  * Some standard implementations of ReadInterface and WriteInterface include
  28  * <ul>
  29  * <li>{@link ResourceRead} which is identified by a single resource
  30  * <li>{@link ResourceRead2} which is identified by a pair of resources
  31  * <li>{@link UnaryRead} which is identifier by a single object
  32  * <li>{@link BinaryRead} which is identifier by a pair of objects
  33  * <li>{@link UniqueRead} which is unique (not equal to anything but itself)
  34  * <li>{@link ReadRequest} which does not report a result
  35  * <li>{@link WriteRequest} for writing
  36  * </ul>
  37  * <p>
  38  * The standard RequestProcessors are
  39  * <ul>
  40  * <li>{@link ReadGraph} for performing requests during other requests
  41  * <li>{@link Session} for initiating a transactions for performing requests
  42  * <li>{@link MergingGraphRequestProcessor} for merging several requests in a
  43  * single transaction
  44  * </ul>
  45  *
  46  * Database services (see e.g. {@link Session}) are available from implemented
  47  * {@link ServiceLocator}. For an asynchronous counterpart with the same
  48  * functionality as RequestProcessor see {@link AsyncRequestProcessor}
  49  *
  50  * <p>
  51  * <b>IMPORTANT:</b>A client invoking any of the <code>sync</code>
  52  * -methods in this interface must not assume that the request is performed
  53  * within the same thread that performed the <code>syncRequest</code>
  54  * invocation. This is an implementation-specific matter.
  55  *
  56  * @version 1.5
  57  * @author Antti Villberg
  58  * @see ReadInterface
  59  * @see WriteInterface
  60  * @see ReadGraph
  61  * @see Session
  62  * @see MergingGraphRequestProcessor
  63  * @see AsyncRequestProcessor
  64  */
  65 public interface RequestProcessor extends RequestProcessorSpecific, ServiceLocator {
  66
  67     Resource getRootLibrary();
  68
  69     /**
  70      * @return the {@link Session} for which this processor is based on.
  71      */
  72     Session getSession();
  73
  74     <T> T sync(ReadInterface<T> r) throws DatabaseException;
  75     <T> T sync(WriteInterface<T> r) throws DatabaseException;
  76
  77     <T> void async(WriteInterface<T> r);
  78     <T> void async(WriteInterface<T> r, Procedure<T> procedure);
  79
  80     Object getModificationCounter();
  81
  82 }