]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java
Index tokenized lowercase versions of name and types for UI searches
[simantics/platform.git] / bundles / org.simantics.db.layer0 / src / org / simantics / db / layer0 / variable / Variable.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.layer0.variable;
13
14 import java.util.Collection;
15 import java.util.Set;
16
17 import org.simantics.databoard.binding.Binding;
18 import org.simantics.databoard.binding.mutable.Variant;
19 import org.simantics.databoard.type.Datatype;
20 import org.simantics.db.ReadGraph;
21 import org.simantics.db.Resource;
22 import org.simantics.db.WriteGraph;
23 import org.simantics.db.exception.DatabaseException;
24 import org.simantics.db.layer0.exception.NonWritableVariableException;
25 import org.simantics.db.layer0.request.PropertyInfo;
26 import org.simantics.db.layer0.variable.RVI.RVIPart;
27 import org.simantics.db.layer0.variable.Variables.Role;
28
29 /*
30  * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides
31  *
32  *  - Unified data addressing in string format (URI)
33  *  - Flattening of reusable component hierarchies
34  *  - Runtime values 
35  *  - Derived values
36  *
37  * The Variable interface spans a tree of variables such that each node can have children and properties.
38  *  - children are denoted by the '/' separator
39  *  - properties are denoted by the '#' separator
40  *
41  * There are three kinds of URIs
42  * 
43  *  Variable URI:
44  *   A standard random access identifier to a variable.
45  *   Examples:  
46  *    - http://www.asd.org/Projects/AprosModel1/BaseRealization/Diagram/PI_X#PI_MASS_FLOW
47  *    - http://www.asd.org/Projects/AprosModel1/Experiment/UUID/Diagram/PI_X#PI_MASS_FLOW#Unit
48  *  Realization URI:
49  *   A random access identifier to a context under which a valuation of a model is presented.
50  *   A realization URI is guaranteed to have a unique resource obtainable by ReadGraph.getResource()
51  *   Examples:
52  *    - http://www.asd.org/Projects/AprosModel1/BaseRealization
53  *    - http://www.asd.org/Projects/AprosModel1/Experiment/UUID
54  *  Relative Variable Identifier (RVI):
55  *   A reference which can be used to obtain a variable when realization is given 
56  *   Examples:
57  *   - /Diagram/PI_X#PI_MASS_FLOW
58  *   - /Diagram/PI_X#PI_MASS_FLOW#Unit
59  *
60  * Use cases:
61  * 
62  * 1. Given a configuration resource and context variable obtain variable
63  *    Procedure: call Variable.browse(ReadGraph, Resource)
64  *
65  * 2. Given two variables obtain RVI of second based on first
66  *    Procedure: call Variables.getRVI(Variable, Variable)
67  *    
68  * 3. Given Realization URI obtain Variable
69  *    Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class)
70  *    
71  * 4. Given Realization URI and RVI, obtain Variable
72  *    Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String)
73  * 
74  * 5. Given Variable URI, obtain Variable
75  *    Procedure: call Variables.getVariable(ReadGraph, String)
76  *     
77  * 6. Given Variable, obtain model
78  *    Procedure: call Variables.getModel(ReadGraph, Variable)
79  *
80  * 7. Given Variable, obtain realization
81  *    Procedure: call Variables.getRealization(ReadGraph, Variable)
82
83  * 8. Given Variable, obtain Variable in other realization
84  *    Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource)
85  *    
86  */
87
88
89 public interface Variable {
90
91         /*
92          * Convenience method for getting the value of a named property.
93          */
94         <T> T getPropertyValue(ReadGraph graph, String name) throws DatabaseException;
95         <T> T getPropertyValue(ReadGraph graph, Resource property) throws DatabaseException;
96         <T> T getPossiblePropertyValue(ReadGraph graph, String name) throws DatabaseException;
97         <T> T getPossiblePropertyValue(ReadGraph graph, Resource property) throws DatabaseException;
98         /*
99          * Convenience method for getting the value of a named property.
100          */
101         <T> T getPropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;
102         <T> T getPropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;
103         <T> T getPossiblePropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;
104         <T> T getPossiblePropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;
105         /*
106          * Gets the value of the property. Binding is default.
107          */
108         <T> T getValue(ReadGraph graph) throws DatabaseException;
109         <T> T getPossibleValue(ReadGraph graph) throws DatabaseException;
110         /*
111          * Gets the value of the property. Binding is explicitly given.
112          */
113         <T> T getValue(ReadGraph graph, Binding binding) throws DatabaseException;
114         <T> T getPossibleValue(ReadGraph graph, Binding binding) throws DatabaseException;
115     Variant getVariantValue(ReadGraph graph) throws DatabaseException;
116         
117     /*
118      * If role is Property returns the corresponding PropertyInfo.
119      * @throws DatabaseException if role of this variable is not Property
120      */
121     PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException;
122
123     /**
124      * @return the index root resource or <code>null</code> if the index root
125      *         cannot be found
126      * @throws DatabaseException in any other error conditions
127      */
128     Resource getIndexRoot(ReadGraph graph) throws DatabaseException;
129
130         /**
131          * Writes a value using the given binding.
132          * 
133          * @throws NonWritableVariableException if the variable is not writable
134          * @throws DatabaseException in any other error conditions 
135          */
136         void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException;
137         /**
138          * Writes a value with default binding based on the value class.
139          * 
140          * @throws NonWritableVariableException if the variable is not writable
141          * @throws DatabaseException in any other error conditions 
142          */
143         void setValue(WriteGraph graph, Object value) throws DatabaseException;
144
145         /**
146          * Writes a value to the given property using the given binding.
147          * 
148          * @throws NonWritableVariableException if the variable is not writable
149          * @throws DatabaseException in any other error conditions 
150          */
151         void setPropertyValue(WriteGraph graph, String name, Object value, Binding binding) throws DatabaseException;
152         void setPropertyValue(WriteGraph graph, Resource property, Object value, Binding binding) throws DatabaseException;
153         /**
154          * Writes a value to the given property using the default binding based on
155          * the value class.
156          * 
157          * @throws NonWritableVariableException if the variable is not writable
158          * @throws DatabaseException in any other error conditions 
159          */
160         void setPropertyValue(WriteGraph graph, String name, Object value) throws DatabaseException;
161         void setPropertyValue(WriteGraph graph, Resource property, Object value) throws DatabaseException;
162
163         // TODO methods?
164
165         /*
166          * Gets a named child of this variable. A child corresponds to a '/' in URI notation
167          */
168         Variable getChild(ReadGraph graph, String name) throws DatabaseException;
169         Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException;
170         /*
171          * Gets a named property of this variable. A property corresponds to a '#' in URI notation
172          */
173         Variable getProperty(ReadGraph graph, String name) throws DatabaseException;    
174         Variable getProperty(ReadGraph graph, Resource property) throws DatabaseException;      
175         Variable getPossibleProperty(ReadGraph graph, String name) throws DatabaseException;    
176         Variable getPossibleProperty(ReadGraph graph, Resource property) throws DatabaseException;      
177
178         /*
179          * Browses all children of this variable.
180          * @deprecated replaced by {@link #getChildren(ReadGraph)}
181          */
182         @Deprecated
183         Collection<Variable> browseChildren(ReadGraph graph) throws DatabaseException;
184
185         /*
186          * Gets all children of this variable.
187          */
188         Collection<Variable> getChildren(ReadGraph graph) throws DatabaseException;
189
190         /*
191          * Browses all available properties of this variable. An empty collection shall
192          * be returned if there are no properties for this variable.
193          * @deprecated replaced by {@link #getProperties(ReadGraph)}
194          */
195         @Deprecated
196         Collection<Variable> browseProperties(ReadGraph graph) throws DatabaseException;
197
198         /*
199          * Gets all available properties of this variable. An empty collection shall
200          * be returned if there are no properties for this variable.
201          */
202         Collection<Variable> getProperties(ReadGraph graph) throws DatabaseException;
203         /*
204          * Gets all properties of this variable such that {@link #getClassifications()}
205          * contains classification. An empty collection shall
206          * be returned if there are no properties for this variable.
207          */
208         Collection<Variable> getProperties(ReadGraph graph, String classification) throws DatabaseException;
209         Collection<Variable> getProperties(ReadGraph graph, Resource classification) throws DatabaseException;
210
211         /*
212          * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'. 
213          */
214         Variable browse(ReadGraph graph, String suffix) throws DatabaseException;
215         Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException;
216
217         /*
218          * Browses a single variable using the given configuration resource. 
219          */
220         Variable browse(ReadGraph graph, Resource config) throws DatabaseException;
221         Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException;
222
223         Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException;
224         Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException;
225
226         /*
227          * Gets the requested interface associated to this variable if available.
228          * Examples: 
229          * -Resource
230          * -Accessor
231          * -Binding
232          * 
233          */
234         @Deprecated
235         <T> T getInterface(ReadGraph graph, Class<T> clazz) throws DatabaseException;
236
237         <T> T adapt(ReadGraph graph, Class<T> clazz) throws DatabaseException;
238         <T> T adaptPossible(ReadGraph graph, Class<T> clazz) throws DatabaseException;
239
240         /*
241          * Gets the unique URI reference for this variable.
242          */
243         String getURI(ReadGraph graph) throws DatabaseException;
244
245         /*
246          * Standard properties
247          */
248
249         /**
250          * @param graph
251          * @return the unescaped name of this variable. Escaped names are used in URIs.
252          * @throws DatabaseException if no name is available or other database error occurs
253          */
254         String getName(ReadGraph graph) throws DatabaseException;
255
256         /**
257          * Informative label of this variable.
258          * 
259          * @param graph
260          * @return
261          * @throws DatabaseException if no label is available or other database error occurs
262          */
263         String getLabel(ReadGraph graph) throws DatabaseException;
264         /**
265          * @param graph
266          * @return parent variable, <code>null</code> for root variable
267          * @throws DatabaseException
268          */
269         Variable getParent(ReadGraph graph) throws DatabaseException;
270
271         Datatype getDatatype(ReadGraph graph) throws DatabaseException;
272         Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException;
273         
274         Role getRole(ReadGraph graph) throws DatabaseException;
275         Role getPossibleRole(ReadGraph graph) throws DatabaseException;
276
277         @Deprecated
278         Variable getPredicate(ReadGraph graph) throws DatabaseException;
279         @Deprecated
280         Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException;
281
282         Resource getPredicateResource(ReadGraph graph) throws DatabaseException;
283         Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException;
284
285         Resource getRepresents(ReadGraph graph) throws DatabaseException;
286         Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException;
287
288         Resource getType(ReadGraph graph) throws DatabaseException;
289         Resource getPossibleType(ReadGraph graph) throws DatabaseException;
290         Resource getType(ReadGraph graph, Resource baseType) throws DatabaseException;
291         Resource getPossibleType(ReadGraph graph, Resource baseType) throws DatabaseException;
292
293         Set<String> getClassifications(ReadGraph graph) throws DatabaseException;
294
295         RVI getRVI(ReadGraph graph) throws DatabaseException;
296         RVI getPossibleRVI(ReadGraph graph) throws DatabaseException;
297
298 }