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