21 * questions.
22 */
23 package org.graalvm.graphio;
24
25 import java.util.Collection;
26 import java.util.Map;
27
28 /**
29 * Interface that defines structure of a compiler graph. The structure of a graph is composed from
30 * nodes with properties, the classes of individual nodes, and ports associated with each node that
31 * may contain edges to other nodes. The structure of a graph is assumed to be immutable for the
32 * time of {@link GraphOutput operations} on it.
33 *
34 * @param <G> the type of the (root node of a) graph
35 * @param <N> the type of nodes
36 * @param <C> the type of node classes
37 * @param <P> the type of node ports
38 */
39 public interface GraphStructure<G, N, C, P> {
40 /**
41 * Casts the provided object to graph, if possible. If the given object <code>obj</code> can be
42 * seen as a graph or sub-graph of a graph, then return the properly typed instance. Otherwise
43 * return <code>null</code>
44 *
45 * @param currentGraph the currently processed graph
46 * @param obj an object to check and view as a graph
47 * @return appropriate graph object or <code>null</code> if the object doesn't represent a graph
48 */
49 G graph(G currentGraph, Object obj);
50
51 /**
52 * Nodes of a graph. Each graph is composed from a fixed set of nodes. This method returns an
53 * iterable which provides access to all of them - the number of nodes provided by the iterable
54 * must match the number returned by {@link #nodesCount(java.lang.Object)} method.
55 *
56 * @see #nodesCount(java.lang.Object)
57 * @param graph the graph to query for nodes
58 * @return iterable with all the graph's nodes
59 */
60 Iterable<? extends N> nodes(G graph);
61
62 /**
63 * Number of nodes in a graph. The number must match the content returned by
64 * {@link #nodes(java.lang.Object)} method.
65 *
66 * @param graph the graph to query
67 * @return the number of nodes that will be returned by {@link #nodes(java.lang.Object)}
68 */
69 int nodesCount(G graph);
70
71 /**
72 * Id of a node. Each node in the graph is uniquely identified by a integer value. If two nodes
73 * have the same id, then they shall be <code>==</code> to each other.
74 *
75 * @param node the node to query for an id
76 * @return the id of the node
77 */
78 int nodeId(N node);
79
80 /**
81 * Checks if there is a predecessor for a node.
82 *
83 * @param node the node to check
84 * @return <code>true</code> if it has a predecessor, <code>false</code> otherwise
85 */
86 boolean nodeHasPredecessor(N node);
87
88 /**
89 * Collects node properties. Each node can be associated with additional properties identified
90 * by their name. This method shall copy them into the provided map.
91 *
92 * @param graph the current graph
93 * @param node the node to collect properties for
94 * @param properties the map to put the properties to
95 */
96 void nodeProperties(G graph, N node, Map<String, ? super Object> properties);
97
98 /**
99 * Finds the node class for the provided object, if possible. If the given object
100 * <code>obj</code> can be seen as an instance of node class or it is a node in this graph,
101 * return the properly typed instance of the node class. Otherwise return <code>null</code>
102 *
103 * @param obj an object to find node class for
104 * @return appropriate graph object or <code>null</code> if the object doesn't represent a graph
105 */
106 C nodeClass(Object obj);
107
108 /**
109 * The template used to build the name of nodes of this class. The template may use references
110 * to inputs ({i#inputName}) and its properties ({p#propertyName}).
111 *
112 * @param nodeClass the node class to find name template for
113 * @return the string representing the template
114 */
115 String nameTemplate(C nodeClass);
116
117 /**
118 * Java class for a node class.
119 *
120 * @param nodeClass the node class
121 * @return the {@link Class} or other type representation of the node class
122 */
123 Object nodeClassType(C nodeClass);
124
125 /**
126 * Input ports of a node class. Each node class has a fixed set of ports where individual edges
|
21 * questions.
22 */
23 package org.graalvm.graphio;
24
25 import java.util.Collection;
26 import java.util.Map;
27
28 /**
29 * Interface that defines structure of a compiler graph. The structure of a graph is composed from
30 * nodes with properties, the classes of individual nodes, and ports associated with each node that
31 * may contain edges to other nodes. The structure of a graph is assumed to be immutable for the
32 * time of {@link GraphOutput operations} on it.
33 *
34 * @param <G> the type of the (root node of a) graph
35 * @param <N> the type of nodes
36 * @param <C> the type of node classes
37 * @param <P> the type of node ports
38 */
39 public interface GraphStructure<G, N, C, P> {
40 /**
41 * Casts {@code obj} to graph, if possible. If the given object <code>obj</code> can be seen as
42 * a graph or sub-graph of a graph, then return the properly typed instance. Otherwise return
43 * <code>null</code>
44 *
45 * @param currentGraph the currently processed graph
46 * @param obj an object to check and view as a graph
47 * @return appropriate graph object or <code>null</code> if the object doesn't represent a graph
48 */
49 G graph(G currentGraph, Object obj);
50
51 /**
52 * Nodes of a graph. Each graph is composed from a fixed set of nodes. This method returns an
53 * iterable which provides access to all of them - the number of nodes provided by the iterable
54 * must match the number returned by {@link #nodesCount(java.lang.Object)} method.
55 *
56 * @see #nodesCount(java.lang.Object)
57 * @param graph the graph to query for nodes
58 * @return iterable with all the graph's nodes
59 */
60 Iterable<? extends N> nodes(G graph);
61
62 /**
63 * Number of nodes in a graph. The number must match the content returned by
64 * {@link #nodes(java.lang.Object)} method.
65 *
66 * @param graph the graph to query
67 * @return the number of nodes that will be returned by {@link #nodes(java.lang.Object)}
68 */
69 int nodesCount(G graph);
70
71 /**
72 * Id of {@code node}. Each node in the graph is uniquely identified by an integer value. If two
73 * nodes have the same id, then they shall be <code>==</code> to each other.
74 *
75 * @param node the node to query for an id
76 * @return the id of the node
77 */
78 int nodeId(N node);
79
80 /**
81 * Checks if there is a predecessor for a node.
82 *
83 * @param node the node to check
84 * @return <code>true</code> if it has a predecessor, <code>false</code> otherwise
85 */
86 boolean nodeHasPredecessor(N node);
87
88 /**
89 * Collects node properties. Each node can be associated with additional properties identified
90 * by their name. This method shall copy them into the provided map.
91 *
92 * @param graph the current graph
93 * @param node the node to collect properties for
94 * @param properties the map to put the properties to
95 */
96 void nodeProperties(G graph, N node, Map<String, ? super Object> properties);
97
98 /**
99 * Finds a node for {@code obj}, if possible. If the given object <code>obj</code> can be seen
100 * as an instance of node return the properly typed instance of the node class. Otherwise return
101 * <code>null</code>.
102 *
103 * @param obj an object to find node for
104 * @return appropriate graph object or <code>null</code> if the object doesn't represent a node
105 */
106 N node(Object obj);
107
108 /**
109 * Finds a node class for {@code obj}, if possible. If the given object <code>obj</code> can be
110 * seen as an instance of node class return the properly typed instance of the node class.
111 * Otherwise return <code>null</code>.
112 *
113 * @param obj an object to find node class for
114 * @return appropriate graph object or <code>null</code> if the object doesn't represent a node
115 * class
116 */
117 C nodeClass(Object obj);
118
119 /**
120 * Finds a node class for {@code node}.
121 *
122 * @param node an instance of node in this graph
123 * @return the node's node class, never <code>null</code>
124 */
125 C classForNode(N node);
126
127 /**
128 * The template used to build the name of nodes of this class. The template may use references
129 * to inputs ({i#inputName}) and its properties ({p#propertyName}).
130 *
131 * @param nodeClass the node class to find name template for
132 * @return the string representing the template
133 */
134 String nameTemplate(C nodeClass);
135
136 /**
137 * Java class for a node class.
138 *
139 * @param nodeClass the node class
140 * @return the {@link Class} or other type representation of the node class
141 */
142 Object nodeClassType(C nodeClass);
143
144 /**
145 * Input ports of a node class. Each node class has a fixed set of ports where individual edges
|