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