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

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.db;\r
  13 \r
  14 import org.simantics.databoard.binding.Binding;\r
  15 import org.simantics.db.exception.BindingException;\r
  16 import org.simantics.db.exception.ClusterSetExistException;\r
  17 import org.simantics.db.exception.DatabaseException;\r
  18 import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;\r
  19 import org.simantics.db.exception.ResourceNotFoundException;\r
  20 import org.simantics.db.exception.ServiceException;\r
  21 import org.simantics.db.request.AsyncMultiRead;\r
  22 import org.simantics.db.request.Write;\r
  23 import org.simantics.db.request.WriteOnly;\r
  24 import org.simantics.db.request.WriteTraits;\r
  25 \r
  26 \r
  27 /**\r
  28  * For accessing and manipulating the graph data.\r
  29  * \r
  30  * Instantiated by Session for use only during a transaction.\r
  31  * \r
  32  * @author Antti Villberg\r
  33  * @see AsyncMultiRead\r
  34  * @see Resource\r
  35  * @see Statement\r
  36  */\r
  37 public interface WriteOnlyGraph extends ServiceLocator, MetadataI {\r
  38 \r
  39     Resource getRootLibrary();\r
  40 \r
  41     /**\r
  42      * Gets a builtin resource. For a list of builtin resources see TODO Wiki\r
  43      * \r
  44      * @param uri the identifier\r
  45      * @return the resource\r
  46      * @throws ResourceNotFoundException if resouce was not found\r
  47      * @throws ServiceException on connection and database failures\r
  48      * @see AsyncReadGraph#forBuiltin\r
  49      */\r
  50     Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;\r
  51 \r
  52     /**\r
  53      * Creates a new resource.\r
  54      * @throws ServiceException\r
  55      * \r
  56      * @returns the new resource\r
  57      */\r
  58     Resource newResource() throws ServiceException;\r
  59 \r
  60     /**\r
  61      * Creates a resource into the specified cluster.\r
  62      * \r
  63      * @param clusterId the ID of the cluster to create the resource into\r
  64      * @throws ServiceException\r
  65      * @returns the new resource\r
  66      */\r
  67     Resource newResource(long clusterId) throws ServiceException;\r
  68 \r
  69     /**\r
  70      * Creates a resource into the specified cluster set.\r
  71      * \r
  72      * @param clusterSet identifies the cluster set which must exist.\r
  73      * @throws ServiceException \r
  74      * @throws ClusterSetExistException if cluster set does not exist.\r
  75      * @returns the new resource\r
  76      * @see #newClusterSet\r
  77      */\r
  78     Resource newResource(Resource clusterSet) throws ServiceException, ClusterSetExistException;\r
  79 \r
  80     /**\r
  81      * Creates a new cluster set.\r
  82      * \r
  83      * @param clusterSet identifies the created cluster set.\r
  84      * @throws ServiceException\r
  85      * @throws ClusterSetExistException if cluster set exists already.\r
  86      */\r
  87     void newClusterSet(Resource clusterSet) throws ServiceException, ClusterSetExistException;\r
  88     /**\r
  89      * Sets cluster set to be used for {@link #newResource()} method.\r
  90      * If cluster set is null then newResource behaves as before. \r
  91      * \r
  92      * @param clusterSet\r
  93      * @return old cluster set.\r
  94      * @throws ServiceException\r
  95      */\r
  96     Resource setClusterSet4NewResource(Resource clusterSet) throws ServiceException;\r
  97     \r
  98     /**\r
  99      * Makes sure that the statements (s,p,o) and (o,i,s) are found in the\r
 100      * graph. It is not asserted that p is an inverse relation of i, this is\r
 101      * assumed and considered to be the client's responsibility.\r
 102      * \r
 103      * <p>\r
 104      * If no inverse relation (o,i,s) is desired, <code>null</code> may be given as inverse.\r
 105      * </p>\r
 106      * \r
 107      * @param subject\r
 108      * @param predicate\r
 109      * @param inverse\r
 110      * @param object\r
 111      */\r
 112     void claim(Resource subject, Resource predicate, Resource inverse, Resource object) throws ServiceException;\r
 113 \r
 114     /**\r
 115      * Stores the specified literal value (boxed primitive/String or\r
 116      * primitive/String array) into the specified resource. Any previous value\r
 117      * is overridden.\r
 118      * \r
 119      * @param resource the resource to store the literal value into\r
 120      * @param value the literal value\r
 121      */\r
 122     void claimValue(Resource resource, Object value) throws ServiceException;\r
 123     void claimValue(Resource resource, Object value, Binding binding) throws ServiceException;\r
 124 \r
 125     void addLiteral(Resource resource, Resource predicate, Resource inverse, Object value, Binding binding) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
 126     void addLiteral(Resource resource, Resource predicate, Resource inverse, Resource type, Object value, Binding binding) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
 127 \r
 128     /**\r
 129      * Makes sure that the statements (s,p,o) and (o,i,s) are no longer found in\r
 130      * the graph. It is not asserted that p is an inverse relation of i, this is\r
 131      * assumed and considered to be the client's responsibility.\r
 132      * \r
 133      * @param subject\r
 134      * @param predicate\r
 135      * @param inverse\r
 136      * @param object\r
 137      */\r
 138     void deny(Resource subject, Resource predicate, Resource inverse, Resource object, VirtualGraph graph) throws ServiceException;\r
 139 \r
 140     /**\r
 141      * If there is a literal value associated with the specified resource, it is\r
 142      * removed. Otherwise does nothing.\r
 143      * \r
 144      * @param resource\r
 145      */\r
 146     void denyValue(Resource resource) throws ServiceException;\r
 147     void denyValue(Resource resource, VirtualGraph graph) throws ServiceException;\r
 148 \r
 149     /**\r
 150      * Ends writing into the current cluster and starts a new one. Any resources\r
 151      * created with {@link #newResource()} after this call will go into the new\r
 152      * cluster.\r
 153      */\r
 154     void flushCluster() throws ServiceException;\r
 155 \r
 156     /**\r
 157      * Flush all modified data in the given cluster stream to server.\r
 158      * \r
 159      * @param r is resource used to identify cluster. If null then all clusters\r
 160      *        streams are flushed.\r
 161      */\r
 162     void flushCluster(Resource r) throws ServiceException;\r
 163 \r
 164     /**\r
 165      * Synchronously performs the given {@link WriteOnly}.\r
 166      * \r
 167      * @param request an instance of {@link Write}.\r
 168      */\r
 169     void syncRequest(WriteOnly r) throws DatabaseException;\r
 170 \r
 171     int thread();\r
 172 \r
 173     VirtualGraph getProvider();\r
 174     \r
 175     /**\r
 176      * After current request is processed the undo list is cleared.\r
 177      */\r
 178     void clearUndoList(WriteTraits writeTraits);\r
 179     \r
 180     boolean isImmutable(Resource resource) throws DatabaseException;\r
 181 \r
 182     /**\r
 183      * Marks the beginning of the ongoing write transaction as an undo point.\r
 184      * Calling this method several times during the same transaction has no\r
 185      * effect.\r
 186      */\r
 187     void markUndoPoint();\r
 188 \r
 189 }\r