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