]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.db/src/org/simantics/db/WriteGraph.java
Multiple readers and variable optimization
[simantics/platform.git] / 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 }