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
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.db.layer0.variable;
\r
14 import java.util.Collection;
\r
15 import java.util.Set;
\r
17 import org.simantics.databoard.binding.Binding;
\r
18 import org.simantics.databoard.binding.mutable.Variant;
\r
19 import org.simantics.databoard.type.Datatype;
\r
20 import org.simantics.db.ReadGraph;
\r
21 import org.simantics.db.Resource;
\r
22 import org.simantics.db.WriteGraph;
\r
23 import org.simantics.db.exception.DatabaseException;
\r
24 import org.simantics.db.layer0.exception.NonWritableVariableException;
\r
25 import org.simantics.db.layer0.request.PropertyInfo;
\r
26 import org.simantics.db.layer0.variable.RVI.RVIPart;
\r
27 import org.simantics.db.layer0.variable.Variables.Role;
\r
30 * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides
\r
32 * - Unified data addressing in string format (URI)
\r
33 * - Flattening of reusable component hierarchies
\r
37 * The Variable interface spans a tree of variables such that each node can have children and properties.
\r
38 * - children are denoted by the '/' separator
\r
39 * - properties are denoted by the '#' separator
\r
41 * There are three kinds of URIs
\r
44 * A standard random access identifier to a variable.
\r
46 * - http://www.asd.org/Projects/AprosModel1/BaseRealization/Diagram/PI_X#PI_MASS_FLOW
\r
47 * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID/Diagram/PI_X#PI_MASS_FLOW#Unit
\r
49 * A random access identifier to a context under which a valuation of a model is presented.
\r
50 * A realization URI is guaranteed to have a unique resource obtainable by ReadGraph.getResource()
\r
52 * - http://www.asd.org/Projects/AprosModel1/BaseRealization
\r
53 * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID
\r
54 * Relative Variable Identifier (RVI):
\r
55 * A reference which can be used to obtain a variable when realization is given
\r
57 * - /Diagram/PI_X#PI_MASS_FLOW
\r
58 * - /Diagram/PI_X#PI_MASS_FLOW#Unit
\r
62 * 1. Given a configuration resource and context variable obtain variable
\r
63 * Procedure: call Variable.browse(ReadGraph, Resource)
\r
65 * 2. Given two variables obtain RVI of second based on first
\r
66 * Procedure: call Variables.getRVI(Variable, Variable)
\r
68 * 3. Given Realization URI obtain Variable
\r
69 * Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class)
\r
71 * 4. Given Realization URI and RVI, obtain Variable
\r
72 * Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String)
\r
74 * 5. Given Variable URI, obtain Variable
\r
75 * Procedure: call Variables.getVariable(ReadGraph, String)
\r
77 * 6. Given Variable, obtain model
\r
78 * Procedure: call Variables.getModel(ReadGraph, Variable)
\r
80 * 7. Given Variable, obtain realization
\r
81 * Procedure: call Variables.getRealization(ReadGraph, Variable)
\r
83 * 8. Given Variable, obtain Variable in other realization
\r
84 * Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource)
\r
89 public interface Variable {
\r
92 * Convenience method for getting the value of a named property.
\r
94 <T> T getPropertyValue(ReadGraph graph, String name) throws DatabaseException;
\r
95 <T> T getPropertyValue(ReadGraph graph, Resource property) throws DatabaseException;
\r
96 <T> T getPossiblePropertyValue(ReadGraph graph, String name) throws DatabaseException;
\r
97 <T> T getPossiblePropertyValue(ReadGraph graph, Resource property) throws DatabaseException;
\r
99 * Convenience method for getting the value of a named property.
\r
101 <T> T getPropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;
\r
102 <T> T getPropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;
\r
103 <T> T getPossiblePropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;
\r
104 <T> T getPossiblePropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;
\r
106 * Gets the value of the property. Binding is default.
\r
108 <T> T getValue(ReadGraph graph) throws DatabaseException;
\r
109 <T> T getPossibleValue(ReadGraph graph) throws DatabaseException;
\r
111 * Gets the value of the property. Binding is explicitly given.
\r
113 <T> T getValue(ReadGraph graph, Binding binding) throws DatabaseException;
\r
114 <T> T getPossibleValue(ReadGraph graph, Binding binding) throws DatabaseException;
\r
115 Variant getVariantValue(ReadGraph graph) throws DatabaseException;
\r
118 * If role is Property returns the corresponding PropertyInfo.
\r
119 * @throws DatabaseException if role of this variable is not Property
\r
121 PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException;
\r
124 * @return the index root resource or <code>null</code> if the index root
\r
126 * @throws DatabaseException in any other error conditions
\r
128 Resource getIndexRoot(ReadGraph graph) throws DatabaseException;
\r
131 * Writes a value using the given binding.
\r
133 * @throws NonWritableVariableException if the variable is not writable
\r
134 * @throws DatabaseException in any other error conditions
\r
136 void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException;
\r
138 * Writes a value with default binding based on the value class.
\r
140 * @throws NonWritableVariableException if the variable is not writable
\r
141 * @throws DatabaseException in any other error conditions
\r
143 void setValue(WriteGraph graph, Object value) throws DatabaseException;
\r
146 * Writes a value to the given property using the given binding.
\r
148 * @throws NonWritableVariableException if the variable is not writable
\r
149 * @throws DatabaseException in any other error conditions
\r
151 void setPropertyValue(WriteGraph graph, String name, Object value, Binding binding) throws DatabaseException;
\r
152 void setPropertyValue(WriteGraph graph, Resource property, Object value, Binding binding) throws DatabaseException;
\r
154 * Writes a value to the given property using the default binding based on
\r
157 * @throws NonWritableVariableException if the variable is not writable
\r
158 * @throws DatabaseException in any other error conditions
\r
160 void setPropertyValue(WriteGraph graph, String name, Object value) throws DatabaseException;
\r
161 void setPropertyValue(WriteGraph graph, Resource property, Object value) throws DatabaseException;
\r
166 * Gets a named child of this variable. A child corresponds to a '/' in URI notation
\r
168 Variable getChild(ReadGraph graph, String name) throws DatabaseException;
\r
169 Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException;
\r
171 * Gets a named property of this variable. A property corresponds to a '#' in URI notation
\r
173 Variable getProperty(ReadGraph graph, String name) throws DatabaseException;
\r
174 Variable getProperty(ReadGraph graph, Resource property) throws DatabaseException;
\r
175 Variable getPossibleProperty(ReadGraph graph, String name) throws DatabaseException;
\r
176 Variable getPossibleProperty(ReadGraph graph, Resource property) throws DatabaseException;
\r
179 * Browses all children of this variable.
\r
180 * @deprecated replaced by {@link #getChildren(ReadGraph)}
\r
183 Collection<Variable> browseChildren(ReadGraph graph) throws DatabaseException;
\r
186 * Gets all children of this variable.
\r
188 Collection<Variable> getChildren(ReadGraph graph) throws DatabaseException;
\r
191 * Browses all available properties of this variable. An empty collection shall
\r
192 * be returned if there are no properties for this variable.
\r
193 * @deprecated replaced by {@link #getProperties(ReadGraph)}
\r
196 Collection<Variable> browseProperties(ReadGraph graph) throws DatabaseException;
\r
199 * Gets all available properties of this variable. An empty collection shall
\r
200 * be returned if there are no properties for this variable.
\r
202 Collection<Variable> getProperties(ReadGraph graph) throws DatabaseException;
\r
204 * Gets all properties of this variable such that {@link #getClassifications()}
\r
205 * contains classification. An empty collection shall
\r
206 * be returned if there are no properties for this variable.
\r
208 Collection<Variable> getProperties(ReadGraph graph, String classification) throws DatabaseException;
\r
209 Collection<Variable> getProperties(ReadGraph graph, Resource classification) throws DatabaseException;
\r
212 * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'.
\r
214 Variable browse(ReadGraph graph, String suffix) throws DatabaseException;
\r
215 Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException;
\r
218 * Browses a single variable using the given configuration resource.
\r
220 Variable browse(ReadGraph graph, Resource config) throws DatabaseException;
\r
221 Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException;
\r
223 Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException;
\r
224 Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException;
\r
227 * Gets the requested interface associated to this variable if available.
\r
235 <T> T getInterface(ReadGraph graph, Class<T> clazz) throws DatabaseException;
\r
237 <T> T adapt(ReadGraph graph, Class<T> clazz) throws DatabaseException;
\r
238 <T> T adaptPossible(ReadGraph graph, Class<T> clazz) throws DatabaseException;
\r
241 * Gets the unique URI reference for this variable.
\r
243 String getURI(ReadGraph graph) throws DatabaseException;
\r
246 * Standard properties
\r
251 * @return the unescaped name of this variable. Escaped names are used in URIs.
\r
252 * @throws DatabaseException if no name is available or other database error occurs
\r
254 String getName(ReadGraph graph) throws DatabaseException;
\r
257 * Informative label of this variable.
\r
261 * @throws DatabaseException if no label is available or other database error occurs
\r
263 String getLabel(ReadGraph graph) throws DatabaseException;
\r
266 * @return parent variable, <code>null</code> for root variable
\r
267 * @throws DatabaseException
\r
269 Variable getParent(ReadGraph graph) throws DatabaseException;
\r
271 Datatype getDatatype(ReadGraph graph) throws DatabaseException;
\r
272 Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException;
\r
274 Role getRole(ReadGraph graph) throws DatabaseException;
\r
275 Role getPossibleRole(ReadGraph graph) throws DatabaseException;
\r
278 Variable getPredicate(ReadGraph graph) throws DatabaseException;
\r
280 Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException;
\r
282 Resource getPredicateResource(ReadGraph graph) throws DatabaseException;
\r
283 Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException;
\r
285 Resource getRepresents(ReadGraph graph) throws DatabaseException;
\r
286 Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException;
\r
288 Resource getType(ReadGraph graph) throws DatabaseException;
\r
289 Resource getPossibleType(ReadGraph graph) throws DatabaseException;
\r
290 Resource getType(ReadGraph graph, Resource baseType) throws DatabaseException;
\r
291 Resource getPossibleType(ReadGraph graph, Resource baseType) throws DatabaseException;
\r
293 Set<String> getClassifications(ReadGraph graph) throws DatabaseException;
\r
295 RVI getRVI(ReadGraph graph) throws DatabaseException;
\r
296 RVI getPossibleRVI(ReadGraph graph) throws DatabaseException;
\r