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 }