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

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