bundles/org.simantics.db/src/org/simantics/db/WriteGraph.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.accessor.Accessor;\r
  15 import org.simantics.databoard.binding.Binding;\r
  16 import org.simantics.databoard.type.Datatype;\r
  17 import org.simantics.databoard.util.binary.RandomAccessBinary;\r
  18 import org.simantics.db.exception.BindingException;\r
  19 import org.simantics.db.exception.DatabaseException;\r
  20 import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;\r
  21 import org.simantics.db.exception.ServiceException;\r
  22 import org.simantics.db.request.AsyncMultiRead;\r
  23 \r
  24 /**\r
  25  * For accessing and manipulating the graph data.\r
  26  *\r
  27  * Instantiated by Session for use only during a transaction.\r
  28  * \r
  29  * @author Antti Villberg\r
  30  * @author Marko Luukkainen <marko.luukkainen@vtt.fi> -docs\r
  31  * @see AsyncMultiRead\r
  32  * @see Resource\r
  33  * @see Statement\r
  34  */\r
  35 public interface WriteGraph extends WriteOnlyGraph, ReadGraph {\r
  36 \r
  37     /**\r
  38      * Makes sure that the statements (s,p,o) and (o,p',s) are found in the\r
  39      * graph, where p' is the inverse predicate of p. Contrary to\r
  40      * {@link WriteOnlyGraph#claim(Resource, Resource, Resource, Resource)} this\r
  41      * method assures that the the statement and its inverse are semantically\r
  42      * valid after the invocation of this method.\r
  43      * \r
  44      * @param subject subject, i.e. source resource of the statement to be\r
  45      *        claimed\r
  46      * @param predicate predicate resource of the statement to be claimed\r
  47      * @param object object, i.e. target resource of the statement to be claimed\r
  48      * @throws ServiceException\r
  49      */\r
  50     void claim(Resource subject, Resource predicate, Resource object) throws ServiceException;\r
  51 \r
  52     /**\r
  53      * Sets literal value related to the specified resource with the specified\r
  54      * predicate. If such value exists (s,p), the value is overridden with the\r
  55      * new specified value.\r
  56      * \r
  57      * @param resource\r
  58      * @param predicate\r
  59      * @param value Value of the literal (boxed primitive/String or\r
  60      *        primitive/String array)\r
  61      * @throws ManyObjectsForFunctionalRelationException\r
  62      */\r
  63 \r
  64     /**\r
  65      * Claims\r
  66      * -(resource, predicate, ?o) and when applicable (?o, inverse of predicate, resource)\r
  67      * -(?o, L0.InstanceOf, L0.Literal or type) (user type is used if provided)\r
  68      * -(?o, L0.HasDatatype, <data type of value>) (is assumed to be asserted if type is given)\r
  69      * -(?o contains value) \r
  70      * \r
  71      * For L0 literals type is inferred if not provided by the user. Else if type is not provided L0.Literal is used.\r
  72      * If the user does not provide binding Bindings.getBinding(value.getClass()) is consulted.\r
  73      * Assumes that predicate is functional.\r
  74      * \r
  75      * @throws ServiceException\r
  76      */\r
  77     void claimLiteral(Resource resource, Resource predicate, Object value) throws ManyObjectsForFunctionalRelationException, ServiceException;\r
  78     void claimLiteral(Resource resource, Resource predicate, Object value, Binding binding) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
  79     void claimLiteral(Resource resource, Resource predicate, Resource type, Object value) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
  80     void claimLiteral(Resource resource, Resource predicate, Resource type, Object value, Binding binding) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
  81     void claimLiteral(Resource resource, Resource predicate, Resource inverse, Resource type, Object value) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
  82     void claimLiteral(Resource resource, Resource predicate, Resource inverse, Resource type, Object value, Binding binding) throws BindingException, ManyObjectsForFunctionalRelationException, ServiceException;\r
  83 \r
  84     /**\r
  85      * Returns an accessory that can be used to partially read or write the the\r
  86      * literal. The returned accessory is closed automatically when the\r
  87      * transaction ends. The modifications are written back to graph at\r
  88      * transaction completion.\r
  89      * \r
  90      * @param <T>\r
  91      * @param resource is the parent of literal.\r
  92      * @param predicate is the relation for the literal.\r
  93      * @param datatype is the data type of the literal.\r
  94      * @param initialValue for the literal. If null then default value is used.\r
  95      * @return\r
  96      * @throws DatabaseException\r
  97      */\r
  98     <T extends Accessor> T newLiteral(Resource resource, Resource predicate, Datatype datatype, Object initialValue) throws DatabaseException;\r
  99     \r
 100     /**\r
 101      * Returns RandomAccessBinary that can be used to partially read or write the the\r
 102      * literal. The returned RandomAccessBinary is closed automatically when the\r
 103      * transaction ends. The modifications are written back to graph at\r
 104      * transaction completion.\r
 105      * \r
 106      * @param <T>\r
 107      * @param resource is the parent of literal.\r
 108      * @param predicate is the relation for the literal.\r
 109      * @param datatype is the data type of the literal.\r
 110      * @param initialValue for the literal. If null then default value is used.\r
 111      * @return RandomAccessBinary to access the literal.\r
 112      * @throws DatabaseException\r
 113      */\r
 114     RandomAccessBinary createRandomAccessBinary(Resource resource, Resource predicate, Datatype datatype, Object initialValue)\r
 115                 throws DatabaseException;\r
 116 \r
 117     RandomAccessBinary createRandomAccessBinary(Resource resource, Datatype datatype, Object initialValue)\r
 118                 throws DatabaseException;\r
 119     \r
 120     /**\r
 121      * Makes sure that no statements matching the patterns (s,?p,?o) and\r
 122      * (?o,?p',s), where ?p' is the inverse predicate of ?p, exist in the graph.\r
 123      * In other words, removes all statements outgoing from the specified\r
 124      * resource along with the inverses of those statements.\r
 125      * \r
 126      * @param subject\r
 127      * @throws ServiceException\r
 128      */\r
 129     void deny(Resource subject) throws ServiceException;\r
 130 \r
 131     /**\r
 132      * Makes sure that no statements matching the patterns (s,p,?o) and\r
 133      * (?o,p',s), where p' is the inverse predicate of p, exist in the graph.\r
 134      * Also statements where <code>isSubrelationOf(p, predicate)</code> returns\r
 135      * <code>true</code> shall be removed. In other words, removes all\r
 136      * statements outgoing from the specified resource with the specified\r
 137      * predicate or any of its subrelations, along with the inverses of those\r
 138      * statements.\r
 139      * \r
 140      * @param subject\r
 141      * @throws ServiceException\r
 142      */\r
 143     void deny(Resource subject, Resource predicate) throws ServiceException;\r
 144 \r
 145     /**\r
 146      * Makes sure that no statements matching the patterns (s,p,o) and (o,p',s),\r
 147      * where p' is the inverse predicate of p, exist in the graph. Contrary to\r
 148      * {@link #denyStatement(Resource, Resource, Resource)}, all statements\r
 149      * where <code>isSubrelationOf(p, predicate)</code> returns\r
 150      * <code>true</code> shall be removed. In other words, removes all\r
 151      * statements between the specified subject and object with the specified\r
 152      * predicate or any of its subrelations, along with the inverses of those\r
 153      * statements.\r
 154      * \r
 155      * @param subject\r
 156      * @param predicate\r
 157      * @param object\r
 158      * @throws ServiceException\r
 159      */\r
 160     void deny(Resource subject, Resource predicate, Resource object) throws ServiceException;\r
 161 \r
 162     void deny(Resource subject, Resource predicate, Resource inverse, Resource object) throws ServiceException;\r
 163 \r
 164     /**\r
 165      * Makes sure that no statements matching the patterns (s,p,o) and (o,p',s),\r
 166      * where p' is the inverse predicate of p, exist in the graph. In other\r
 167      * words, removes the specified statement and its possible inverse.\r
 168      * \r
 169      * <p>\r
 170      * This method behaves exactly like {@link #deny(Statement)}, it just takes\r
 171      * the arguments as resources instead of a statement.\r
 172      * \r
 173      * @param subject\r
 174      * @throws ServiceException\r
 175      * \r
 176      * @see {@link #deny(Statement)}\r
 177      */\r
 178     void denyStatement(Resource subject, Resource predicate, Resource object) throws ServiceException;\r
 179 \r
 180     /**\r
 181      * Makes sure that the specified statements (s,p,o) and its inverse\r
 182      * statements (o,p',s), where p' is the inverse predicate of p, do not exist\r
 183      * in the graph.\r
 184      * \r
 185      * <p>\r
 186      * This method behaves exactly like\r
 187      * {@link #denyStatement(Resource, Resource, Resource)}, it just takes the\r
 188      * arguments as a statement instead of 3 resources.\r
 189      * \r
 190      * @param statement\r
 191      * \r
 192      * @see #denyStatement(Resource, Resource, Resource)\r
 193      */\r
 194     void deny(Statement statement) throws ServiceException;\r
 195 \r
 196     /**\r
 197      * Removes all statements (resource,predicate,?o) and literal contained by\r
 198      * ?o.\r
 199      * \r
 200      * @param resource\r
 201      * @param predicate\r
 202      * @throws ManyObjectsForFunctionalRelationException\r
 203      */\r
 204     void denyValue(Resource resource, Resource predicate) throws ManyObjectsForFunctionalRelationException, ServiceException;\r
 205 \r
 206 }\r