bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java

   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
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.db.layer0.variable;\r
  13 \r
  14 import java.util.Collection;\r
  15 import java.util.Set;\r
  16 \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
  28 \r
  29 /*\r
  30  * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides\r
  31  *\r
  32  *  - Unified data addressing in string format (URI)\r
  33  *  - Flattening of reusable component hierarchies\r
  34  *  - Runtime values \r
  35  *  - Derived values\r
  36  *\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
  40  *\r
  41  * There are three kinds of URIs\r
  42  * \r
  43  *  Variable URI:\r
  44  *   A standard random access identifier to a variable.\r
  45  *   Examples:  \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
  48  *  Realization URI:\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
  51  *   Examples:\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
  56  *   Examples:\r
  57  *   - /Diagram/PI_X#PI_MASS_FLOW\r
  58  *   - /Diagram/PI_X#PI_MASS_FLOW#Unit\r
  59  *\r
  60  * Use cases:\r
  61  * \r
  62  * 1. Given a configuration resource and context variable obtain variable\r
  63  *    Procedure: call Variable.browse(ReadGraph, Resource)\r
  64  *\r
  65  * 2. Given two variables obtain RVI of second based on first\r
  66  *    Procedure: call Variables.getRVI(Variable, Variable)\r
  67  *    \r
  68  * 3. Given Realization URI obtain Variable\r
  69  *    Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class)\r
  70  *    \r
  71  * 4. Given Realization URI and RVI, obtain Variable\r
  72  *    Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String)\r
  73  * \r
  74  * 5. Given Variable URI, obtain Variable\r
  75  *    Procedure: call Variables.getVariable(ReadGraph, String)\r
  76  *     \r
  77  * 6. Given Variable, obtain model\r
  78  *    Procedure: call Variables.getModel(ReadGraph, Variable)\r
  79  *\r
  80  * 7. Given Variable, obtain realization\r
  81  *    Procedure: call Variables.getRealization(ReadGraph, Variable)\r
  82 \r
  83  * 8. Given Variable, obtain Variable in other realization\r
  84  *    Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource)\r
  85  *    \r
  86  */\r
  87 \r
  88 \r
  89 public interface Variable {\r
  90 \r
  91         /*\r
  92          * Convenience method for getting the value of a named property.\r
  93          */\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
  98         /*\r
  99          * Convenience method for getting the value of a named property.\r
 100          */\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
 105         /*\r
 106          * Gets the value of the property. Binding is default.\r
 107          */\r
 108         <T> T getValue(ReadGraph graph) throws DatabaseException;\r
 109         <T> T getPossibleValue(ReadGraph graph) throws DatabaseException;\r
 110         /*\r
 111          * Gets the value of the property. Binding is explicitly given.\r
 112          */\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
 116         \r
 117     /*\r
 118      * If role is Property returns the corresponding PropertyInfo.\r
 119      * @throws DatabaseException if role of this variable is not Property\r
 120      */\r
 121     PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException;\r
 122 \r
 123     /**\r
 124      * @return the index root resource or <code>null</code> if the index root\r
 125      *         cannot be found\r
 126      * @throws DatabaseException in any other error conditions\r
 127      */\r
 128     Resource getIndexRoot(ReadGraph graph) throws DatabaseException;\r
 129 \r
 130         /**\r
 131          * Writes a value using the given binding.\r
 132          * \r
 133          * @throws NonWritableVariableException if the variable is not writable\r
 134          * @throws DatabaseException in any other error conditions \r
 135          */\r
 136         void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException;\r
 137         /**\r
 138          * Writes a value with default binding based on the value class.\r
 139          * \r
 140          * @throws NonWritableVariableException if the variable is not writable\r
 141          * @throws DatabaseException in any other error conditions \r
 142          */\r
 143         void setValue(WriteGraph graph, Object value) throws DatabaseException;\r
 144 \r
 145         /**\r
 146          * Writes a value to the given property using the given binding.\r
 147          * \r
 148          * @throws NonWritableVariableException if the variable is not writable\r
 149          * @throws DatabaseException in any other error conditions \r
 150          */\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
 153         /**\r
 154          * Writes a value to the given property using the default binding based on\r
 155          * the value class.\r
 156          * \r
 157          * @throws NonWritableVariableException if the variable is not writable\r
 158          * @throws DatabaseException in any other error conditions \r
 159          */\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
 162 \r
 163         // TODO methods?\r
 164 \r
 165         /*\r
 166          * Gets a named child of this variable. A child corresponds to a '/' in URI notation\r
 167          */\r
 168         Variable getChild(ReadGraph graph, String name) throws DatabaseException;\r
 169         Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException;\r
 170         /*\r
 171          * Gets a named property of this variable. A property corresponds to a '#' in URI notation\r
 172          */\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
 177 \r
 178         /*\r
 179          * Browses all children of this variable.\r
 180          * @deprecated replaced by {@link #getChildren(ReadGraph)}\r
 181          */\r
 182         @Deprecated\r
 183         Collection<Variable> browseChildren(ReadGraph graph) throws DatabaseException;\r
 184 \r
 185         /*\r
 186          * Gets all children of this variable.\r
 187          */\r
 188         Collection<Variable> getChildren(ReadGraph graph) throws DatabaseException;\r
 189 \r
 190         /*\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
 194          */\r
 195         @Deprecated\r
 196         Collection<Variable> browseProperties(ReadGraph graph) throws DatabaseException;\r
 197 \r
 198         /*\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
 201          */\r
 202         Collection<Variable> getProperties(ReadGraph graph) throws DatabaseException;\r
 203         /*\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
 207          */\r
 208         Collection<Variable> getProperties(ReadGraph graph, String classification) throws DatabaseException;\r
 209         Collection<Variable> getProperties(ReadGraph graph, Resource classification) throws DatabaseException;\r
 210 \r
 211         /*\r
 212          * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'. \r
 213          */\r
 214         Variable browse(ReadGraph graph, String suffix) throws DatabaseException;\r
 215         Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException;\r
 216 \r
 217         /*\r
 218          * Browses a single variable using the given configuration resource. \r
 219          */\r
 220         Variable browse(ReadGraph graph, Resource config) throws DatabaseException;\r
 221         Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException;\r
 222 \r
 223         Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException;\r
 224         Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException;\r
 225 \r
 226         /*\r
 227          * Gets the requested interface associated to this variable if available.\r
 228          * Examples: \r
 229          * -Resource\r
 230          * -Accessor\r
 231          * -Binding\r
 232          * \r
 233          */\r
 234         @Deprecated\r
 235         <T> T getInterface(ReadGraph graph, Class<T> clazz) throws DatabaseException;\r
 236 \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
 239 \r
 240         /*\r
 241          * Gets the unique URI reference for this variable.\r
 242          */\r
 243         String getURI(ReadGraph graph) throws DatabaseException;\r
 244 \r
 245         /*\r
 246          * Standard properties\r
 247          */\r
 248 \r
 249         /**\r
 250          * @param graph\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
 253          */\r
 254         String getName(ReadGraph graph) throws DatabaseException;\r
 255 \r
 256         /**\r
 257          * Informative label of this variable.\r
 258          * \r
 259          * @param graph\r
 260          * @return\r
 261          * @throws DatabaseException if no label is available or other database error occurs\r
 262          */\r
 263         String getLabel(ReadGraph graph) throws DatabaseException;\r
 264         /**\r
 265          * @param graph\r
 266          * @return parent variable, <code>null</code> for root variable\r
 267          * @throws DatabaseException\r
 268          */\r
 269         Variable getParent(ReadGraph graph) throws DatabaseException;\r
 270 \r
 271         Datatype getDatatype(ReadGraph graph) throws DatabaseException;\r
 272         Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException;\r
 273         \r
 274         Role getRole(ReadGraph graph) throws DatabaseException;\r
 275         Role getPossibleRole(ReadGraph graph) throws DatabaseException;\r
 276 \r
 277         @Deprecated\r
 278         Variable getPredicate(ReadGraph graph) throws DatabaseException;\r
 279         @Deprecated\r
 280         Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException;\r
 281 \r
 282         Resource getPredicateResource(ReadGraph graph) throws DatabaseException;\r
 283         Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException;\r
 284 \r
 285         Resource getRepresents(ReadGraph graph) throws DatabaseException;\r
 286         Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException;\r
 287 \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
 292 \r
 293         Set<String> getClassifications(ReadGraph graph) throws DatabaseException;\r
 294 \r
 295         RVI getRVI(ReadGraph graph) throws DatabaseException;\r
 296         RVI getPossibleRVI(ReadGraph graph) throws DatabaseException;\r
 297 \r
 298 }\r