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
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
15 import java.util.Collections;
\r
16 import java.util.List;
\r
17 import java.util.Set;
\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
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
34 * @author Hannu Niemistö
\r
35 * @author Antti Villberg
\r
37 public interface NodeManager<Node> {
\r
39 // --- Do not require a realm access ---
\r
42 * The realm of the node manager. Almost all other methods
\r
43 * of this class must be called inside this realm.
\r
48 * Returns the name of the node. This method does not require
\r
49 * that caller is in realm.
\r
51 String getName(Node node);
\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
59 void addNodeListener(Node node, Runnable listener);
\r
62 * Removes previously added listener. This can be called outside of
\r
65 void removeNodeListener(Node node, Runnable listener);
\r
67 // --- Require a realm access ---
\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
74 Node getNode(String path) throws NodeManagerException;
\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
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
87 * @throws NoValueException if the node has no value (and therefore no datatype)
\r
88 * @throws NotInRealmException if not synchronized to the realm
\r
90 Datatype getDatatype(Node node) throws NodeManagerException;
\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
96 Object getValue(Node node, Binding binding) throws NodeManagerException, BindingException;
\r
98 * A variant of {@link #getValue(Object, Binding)} that uses
\r
99 * a binding chosen by the node manager.
\r
101 Variant getValue(Node node) throws NodeManagerException;
\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
108 Object getValue(Node node, String property, Binding binding) throws NodeManagerException, BindingException;
\r
110 * A variant of {@link #getValue(Object, String, Binding)} that uses
\r
111 * a binding chosen by the node manager.
\r
113 Variant getValue(Node node, String property) throws NodeManagerException;
\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
120 void setValue(Node node, Object value, Binding binding) throws NodeManagerException, BindingException;
\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
127 void setValue(Node node, String property, Object value, Binding binding) throws NodeManagerException, BindingException;
\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
133 String getPropertyURI(Node parent, Node property);
\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
142 * @param node the node to classify
\r
143 * @return classifications of the node, empty set if the node has no classifications
\r
145 Set<String> getClassifications(Node node) throws NodeManagerException;
\r