bundles/org.simantics.simulator.variable/src/org/simantics/simulator/variable/NodeManager.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2013 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  *     Semantum Oy - initial API and implementation\r
  12  *******************************************************************************/\r
  13 package org.simantics.simulator.variable;\r
  14 \r
  15 import java.util.Collections;\r
  16 import java.util.List;\r
  17 import java.util.Set;\r
  18 \r
  19 import org.simantics.databoard.binding.Binding;\r
  20 import org.simantics.databoard.binding.error.BindingException;\r
  21 import org.simantics.databoard.binding.mutable.Variant;\r
  22 import org.simantics.databoard.type.Datatype;\r
  23 import org.simantics.simulator.variable.exceptions.InvalidPathException;\r
  24 import org.simantics.simulator.variable.exceptions.NoSuchNodeException;\r
  25 import org.simantics.simulator.variable.exceptions.NoValueException;\r
  26 import org.simantics.simulator.variable.exceptions.NodeManagerException;\r
  27 import org.simantics.simulator.variable.exceptions.NotInRealmException;\r
  28 \r
  29 /**\r
  30  * {@code NodeManager} provides access to a local simulator\r
  31  * or a similar entity. Because simulation may be ongoing, access\r
  32  * is restricted to a certain realm.\r
  33  * \r
  34  * @author Hannu Niemist&ouml;\r
  35  * @author Antti Villberg\r
  36  */\r
  37 public interface NodeManager<Node> {\r
  38 \r
  39         // --- Do not require a realm access ---\r
  40         \r
  41         /**\r
  42          * The realm of the node manager. Almost all other methods\r
  43          * of this class must be called inside this realm.\r
  44          */\r
  45         Realm getRealm();\r
  46 \r
  47         /**\r
  48          * Returns the name of the node. This method does not require \r
  49          * that caller is in realm.\r
  50          */\r
  51         String getName(Node node);\r
  52 \r
  53         /**\r
  54          * Adds a listener to a certain node. The new listener is called as\r
  55          * soon as possible (for example before simulator takes the next simulation\r
  56          * step). After the first call, it is called always the node value \r
  57          * or structure may have changed. This can be called outside of the realm.\r
  58          */\r
  59         void addNodeListener(Node node, Runnable listener);\r
  60         \r
  61         /**\r
  62          * Removes previously added listener. This can be called outside of\r
  63          * the realm.\r
  64          */\r
  65         void removeNodeListener(Node node, Runnable listener);\r
  66         \r
  67         // --- Require a realm access ---\r
  68         \r
  69         /**\r
  70          * @return {@code null} if node cannot be found, otherwise a node with the given path\r
  71          * @throws InvalidPathException if the path is not in a valid path format\r
  72          * @throws NotInRealmException if not synchronized to the realm\r
  73          */\r
  74         Node getNode(String path) throws NodeManagerException;  \r
  75         /**\r
  76          * @return {@code null} if node cannot be found, otherwise a child node with the given name\r
  77          * @throws NotInRealmException if not synchronized to the realm\r
  78          */\r
  79         Node getChild(Node node, String name) throws NodeManagerException;\r
  80         Node getProperty(Node node, String name) throws NodeManagerException;\r
  81         List<String> getChildNames(Node node) throws NodeManagerException;\r
  82         List<String> getPropertyNames(Node node) throws NodeManagerException;\r
  83         List<Node> getChildren(Node node) throws NodeManagerException;\r
  84         List<Node> getProperties(Node node) throws NodeManagerException;\r
  85 \r
  86         /**\r
  87          * @throws NoValueException if the node has no value (and therefore no datatype)\r
  88          * @throws NotInRealmException if not synchronized to the realm\r
  89          */\r
  90         Datatype getDatatype(Node node) throws NodeManagerException;\r
  91         /**\r
  92          * @throws NoValueException if the node has no value\r
  93          * @throws BindingException if the value can not be bound to the given binding\r
  94          * @throws NotInRealmException if not synchronized to the realm\r
  95          */\r
  96         Object getValue(Node node, Binding binding) throws NodeManagerException, BindingException;\r
  97         /**\r
  98          * A variant of {@link #getValue(Object, Binding)} that uses\r
  99          * a binding chosen by the node manager.\r
 100          */\r
 101         Variant getValue(Node node) throws NodeManagerException;\r
 102         /**\r
 103          * @throws NoSuchNodeException if the property does not exist\r
 104          * @throws NoValueException if the property has no value\r
 105          * @throws NotInRealmException if not synchronized to the realm\r
 106          * @throws BindingException if the value can not be bound to the given binding\r
 107          */\r
 108         Object getValue(Node node, String property, Binding binding) throws NodeManagerException, BindingException;\r
 109         /**\r
 110          * A variant of {@link #getValue(Object, String, Binding)} that uses\r
 111          * a binding chosen by the node manager.\r
 112          */\r
 113         Variant getValue(Node node, String property) throws NodeManagerException;       \r
 114         \r
 115         /**\r
 116          * @throws BindingException if the value can not be bound to the given binding\r
 117          * @throws NoValueException if the property has no value that could be assigned\r
 118          * @throws NotInRealmException if not synchronized to the realm\r
 119          */\r
 120         void setValue(Node node, Object value, Binding binding) throws NodeManagerException, BindingException;\r
 121         /**\r
 122          * @throws BindingException if the value can not be bound to the given binding\r
 123          * @throws NoSuchNodeException if the property does not exist\r
 124          * @throws NoValueException if the property has no value that could be assigned\r
 125          * @throws NotInRealmException if not synchronized to the realm\r
 126          */\r
 127         void setValue(Node node, String property, Object value, Binding binding) throws NodeManagerException, BindingException;\r
 128 \r
 129         /**\r
 130          * Asks the full URI of a property node. The parent of the property is also given as a parameter.\r
 131          * This is an optional method, NodeManager does not have to implement it for all nodes.\r
 132          */\r
 133     String getPropertyURI(Node parent, Node property);\r
 134 \r
 135         /**\r
 136          * Asks for the classifications of a property node.\r
 137          * This is an optional method, NodeManager does not have to implement it for all nodes.\r
 138          * A default implementation should just return {@link Collections#emptySet()}.\r
 139          * Classifications can be any strings, however a recommended interpretation is to return\r
 140          * the URIs of the primary ontological types that this node corresponds to.\r
 141          * \r
 142          * @param node the node to classify\r
 143          * @return classifications of the node, empty set if the node has no classifications\r
 144          */\r
 145         Set<String> getClassifications(Node node) throws NodeManagerException;\r
 146 \r
 147 }