--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.db.layer0.variable;\r
+\r
+import java.util.Collection;\r
+import java.util.Set;\r
+\r
+import org.simantics.databoard.binding.Binding;\r
+import org.simantics.databoard.binding.mutable.Variant;\r
+import org.simantics.databoard.type.Datatype;\r
+import org.simantics.db.ReadGraph;\r
+import org.simantics.db.Resource;\r
+import org.simantics.db.WriteGraph;\r
+import org.simantics.db.exception.DatabaseException;\r
+import org.simantics.db.layer0.exception.NonWritableVariableException;\r
+import org.simantics.db.layer0.request.PropertyInfo;\r
+import org.simantics.db.layer0.variable.RVI.RVIPart;\r
+import org.simantics.db.layer0.variable.Variables.Role;\r
+\r
+/*\r
+ * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides\r
+ *\r
+ * - Unified data addressing in string format (URI)\r
+ * - Flattening of reusable component hierarchies\r
+ * - Runtime values \r
+ * - Derived values\r
+ *\r
+ * The Variable interface spans a tree of variables such that each node can have children and properties.\r
+ * - children are denoted by the '/' separator\r
+ * - properties are denoted by the '#' separator\r
+ *\r
+ * There are three kinds of URIs\r
+ * \r
+ * Variable URI:\r
+ * A standard random access identifier to a variable.\r
+ * Examples: \r
+ * - http://www.asd.org/Projects/AprosModel1/BaseRealization/Diagram/PI_X#PI_MASS_FLOW\r
+ * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID/Diagram/PI_X#PI_MASS_FLOW#Unit\r
+ * Realization URI:\r
+ * A random access identifier to a context under which a valuation of a model is presented.\r
+ * A realization URI is guaranteed to have a unique resource obtainable by ReadGraph.getResource()\r
+ * Examples:\r
+ * - http://www.asd.org/Projects/AprosModel1/BaseRealization\r
+ * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID\r
+ * Relative Variable Identifier (RVI):\r
+ * A reference which can be used to obtain a variable when realization is given \r
+ * Examples:\r
+ * - /Diagram/PI_X#PI_MASS_FLOW\r
+ * - /Diagram/PI_X#PI_MASS_FLOW#Unit\r
+ *\r
+ * Use cases:\r
+ * \r
+ * 1. Given a configuration resource and context variable obtain variable\r
+ * Procedure: call Variable.browse(ReadGraph, Resource)\r
+ *\r
+ * 2. Given two variables obtain RVI of second based on first\r
+ * Procedure: call Variables.getRVI(Variable, Variable)\r
+ * \r
+ * 3. Given Realization URI obtain Variable\r
+ * Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class)\r
+ * \r
+ * 4. Given Realization URI and RVI, obtain Variable\r
+ * Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String)\r
+ * \r
+ * 5. Given Variable URI, obtain Variable\r
+ * Procedure: call Variables.getVariable(ReadGraph, String)\r
+ * \r
+ * 6. Given Variable, obtain model\r
+ * Procedure: call Variables.getModel(ReadGraph, Variable)\r
+ *\r
+ * 7. Given Variable, obtain realization\r
+ * Procedure: call Variables.getRealization(ReadGraph, Variable)\r
+\r
+ * 8. Given Variable, obtain Variable in other realization\r
+ * Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource)\r
+ * \r
+ */\r
+\r
+\r
+public interface Variable {\r
+\r
+ /*\r
+ * Convenience method for getting the value of a named property.\r
+ */\r
+ <T> T getPropertyValue(ReadGraph graph, String name) throws DatabaseException;\r
+ <T> T getPropertyValue(ReadGraph graph, Resource property) throws DatabaseException;\r
+ <T> T getPossiblePropertyValue(ReadGraph graph, String name) throws DatabaseException;\r
+ <T> T getPossiblePropertyValue(ReadGraph graph, Resource property) throws DatabaseException;\r
+ /*\r
+ * Convenience method for getting the value of a named property.\r
+ */\r
+ <T> T getPropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;\r
+ <T> T getPropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;\r
+ <T> T getPossiblePropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException;\r
+ <T> T getPossiblePropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException;\r
+ /*\r
+ * Gets the value of the property. Binding is default.\r
+ */\r
+ <T> T getValue(ReadGraph graph) throws DatabaseException;\r
+ <T> T getPossibleValue(ReadGraph graph) throws DatabaseException;\r
+ /*\r
+ * Gets the value of the property. Binding is explicitly given.\r
+ */\r
+ <T> T getValue(ReadGraph graph, Binding binding) throws DatabaseException;\r
+ <T> T getPossibleValue(ReadGraph graph, Binding binding) throws DatabaseException;\r
+ Variant getVariantValue(ReadGraph graph) throws DatabaseException;\r
+ \r
+ /*\r
+ * If role is Property returns the corresponding PropertyInfo.\r
+ * @throws DatabaseException if role of this variable is not Property\r
+ */\r
+ PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException;\r
+\r
+ /**\r
+ * @return the index root resource or <code>null</code> if the index root\r
+ * cannot be found\r
+ * @throws DatabaseException in any other error conditions\r
+ */\r
+ Resource getIndexRoot(ReadGraph graph) throws DatabaseException;\r
+\r
+ /**\r
+ * Writes a value using the given binding.\r
+ * \r
+ * @throws NonWritableVariableException if the variable is not writable\r
+ * @throws DatabaseException in any other error conditions \r
+ */\r
+ void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException;\r
+ /**\r
+ * Writes a value with default binding based on the value class.\r
+ * \r
+ * @throws NonWritableVariableException if the variable is not writable\r
+ * @throws DatabaseException in any other error conditions \r
+ */\r
+ void setValue(WriteGraph graph, Object value) throws DatabaseException;\r
+\r
+ /**\r
+ * Writes a value to the given property using the given binding.\r
+ * \r
+ * @throws NonWritableVariableException if the variable is not writable\r
+ * @throws DatabaseException in any other error conditions \r
+ */\r
+ void setPropertyValue(WriteGraph graph, String name, Object value, Binding binding) throws DatabaseException;\r
+ void setPropertyValue(WriteGraph graph, Resource property, Object value, Binding binding) throws DatabaseException;\r
+ /**\r
+ * Writes a value to the given property using the default binding based on\r
+ * the value class.\r
+ * \r
+ * @throws NonWritableVariableException if the variable is not writable\r
+ * @throws DatabaseException in any other error conditions \r
+ */\r
+ void setPropertyValue(WriteGraph graph, String name, Object value) throws DatabaseException;\r
+ void setPropertyValue(WriteGraph graph, Resource property, Object value) throws DatabaseException;\r
+\r
+ // TODO methods?\r
+\r
+ /*\r
+ * Gets a named child of this variable. A child corresponds to a '/' in URI notation\r
+ */\r
+ Variable getChild(ReadGraph graph, String name) throws DatabaseException;\r
+ Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException;\r
+ /*\r
+ * Gets a named property of this variable. A property corresponds to a '#' in URI notation\r
+ */\r
+ Variable getProperty(ReadGraph graph, String name) throws DatabaseException; \r
+ Variable getProperty(ReadGraph graph, Resource property) throws DatabaseException; \r
+ Variable getPossibleProperty(ReadGraph graph, String name) throws DatabaseException; \r
+ Variable getPossibleProperty(ReadGraph graph, Resource property) throws DatabaseException; \r
+\r
+ /*\r
+ * Browses all children of this variable.\r
+ * @deprecated replaced by {@link #getChildren(ReadGraph)}\r
+ */\r
+ @Deprecated\r
+ Collection<Variable> browseChildren(ReadGraph graph) throws DatabaseException;\r
+\r
+ /*\r
+ * Gets all children of this variable.\r
+ */\r
+ Collection<Variable> getChildren(ReadGraph graph) throws DatabaseException;\r
+\r
+ /*\r
+ * Browses all available properties of this variable. An empty collection shall\r
+ * be returned if there are no properties for this variable.\r
+ * @deprecated replaced by {@link #getProperties(ReadGraph)}\r
+ */\r
+ @Deprecated\r
+ Collection<Variable> browseProperties(ReadGraph graph) throws DatabaseException;\r
+\r
+ /*\r
+ * Gets all available properties of this variable. An empty collection shall\r
+ * be returned if there are no properties for this variable.\r
+ */\r
+ Collection<Variable> getProperties(ReadGraph graph) throws DatabaseException;\r
+ /*\r
+ * Gets all properties of this variable such that {@link #getClassifications()}\r
+ * contains classification. An empty collection shall\r
+ * be returned if there are no properties for this variable.\r
+ */\r
+ Collection<Variable> getProperties(ReadGraph graph, String classification) throws DatabaseException;\r
+ Collection<Variable> getProperties(ReadGraph graph, Resource classification) throws DatabaseException;\r
+\r
+ /*\r
+ * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'. \r
+ */\r
+ Variable browse(ReadGraph graph, String suffix) throws DatabaseException;\r
+ Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException;\r
+\r
+ /*\r
+ * Browses a single variable using the given configuration resource. \r
+ */\r
+ Variable browse(ReadGraph graph, Resource config) throws DatabaseException;\r
+ Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException;\r
+\r
+ Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException;\r
+ Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException;\r
+\r
+ /*\r
+ * Gets the requested interface associated to this variable if available.\r
+ * Examples: \r
+ * -Resource\r
+ * -Accessor\r
+ * -Binding\r
+ * \r
+ */\r
+ @Deprecated\r
+ <T> T getInterface(ReadGraph graph, Class<T> clazz) throws DatabaseException;\r
+\r
+ <T> T adapt(ReadGraph graph, Class<T> clazz) throws DatabaseException;\r
+ <T> T adaptPossible(ReadGraph graph, Class<T> clazz) throws DatabaseException;\r
+\r
+ /*\r
+ * Gets the unique URI reference for this variable.\r
+ */\r
+ String getURI(ReadGraph graph) throws DatabaseException;\r
+\r
+ /*\r
+ * Standard properties\r
+ */\r
+\r
+ /**\r
+ * @param graph\r
+ * @return the unescaped name of this variable. Escaped names are used in URIs.\r
+ * @throws DatabaseException if no name is available or other database error occurs\r
+ */\r
+ String getName(ReadGraph graph) throws DatabaseException;\r
+\r
+ /**\r
+ * Informative label of this variable.\r
+ * \r
+ * @param graph\r
+ * @return\r
+ * @throws DatabaseException if no label is available or other database error occurs\r
+ */\r
+ String getLabel(ReadGraph graph) throws DatabaseException;\r
+ /**\r
+ * @param graph\r
+ * @return parent variable, <code>null</code> for root variable\r
+ * @throws DatabaseException\r
+ */\r
+ Variable getParent(ReadGraph graph) throws DatabaseException;\r
+\r
+ Datatype getDatatype(ReadGraph graph) throws DatabaseException;\r
+ Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException;\r
+ \r
+ Role getRole(ReadGraph graph) throws DatabaseException;\r
+ Role getPossibleRole(ReadGraph graph) throws DatabaseException;\r
+\r
+ @Deprecated\r
+ Variable getPredicate(ReadGraph graph) throws DatabaseException;\r
+ @Deprecated\r
+ Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException;\r
+\r
+ Resource getPredicateResource(ReadGraph graph) throws DatabaseException;\r
+ Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException;\r
+\r
+ Resource getRepresents(ReadGraph graph) throws DatabaseException;\r
+ Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException;\r
+\r
+ Resource getType(ReadGraph graph) throws DatabaseException;\r
+ Resource getPossibleType(ReadGraph graph) throws DatabaseException;\r
+ Resource getType(ReadGraph graph, Resource baseType) throws DatabaseException;\r
+ Resource getPossibleType(ReadGraph graph, Resource baseType) throws DatabaseException;\r
+\r
+ Set<String> getClassifications(ReadGraph graph) throws DatabaseException;\r
+\r
+ RVI getRVI(ReadGraph graph) throws DatabaseException;\r
+ RVI getPossibleRVI(ReadGraph graph) throws DatabaseException;\r
+\r
+}\r
Code Review / simantics / platform.git / blobdiff