0
# Graph System
1

2
Directed graph system for modeling deployment states, transitions, and path finding through the deployment lifecycle. The graph system provides the underlying structure for the state machine that controls application deployment workflows.
3

4
## Capabilities
5

6
### Graph
7

8
Basic directed graph implementation providing nodes, edges, and path-finding capabilities for modeling state transitions.
9

10
```java { .api }
11
/**
12
 * Basic directed graph implementation
13
 */
14
public class Graph {
15
    /** Creates a new empty graph */
16
    public Graph();
17
    
18
    /** Adds a node to the graph */
19
    public void addNode(Node node);
20
    
21
    /** Removes a node from the graph */
22
    public void removeNode(Node node);
23
    
24
    /** Returns all nodes in the graph */
25
    public Set<Node> getNodes();
26
    
27
    /** Sets the nodes in the graph */
28
    public void setNodes(Set<Node> nodes);
29
    
30
    /** Gets a node by its name */
31
    public Node getNodeByName(String name);
32
    
33
    /** Adds an edge to the graph */
34
    public void addEdge(Edge edge);
35
    
36
    /** Adds an edge between named nodes */
37
    public void addEdge(String from, String to);
38
    
39
    /** Removes an edge from the graph */
40
    public void removeEdge(Edge edge);
41
    
42
    /** Removes edge between named nodes */
43
    public void removeEdge(String fromNodeName, String toNodeName);
44
    
45
    /** Returns all edges in the graph */
46
    public Set<Edge> getEdges();
47
    
48
    /** Sets the edges in the graph */
49
    public void setEdges(Set<Edge> edges);
50
    
51
    /** Finds all edges connected to the specified node */
52
    public Set<Edge> findEdges(Node node);
53
    
54
    /** Finds all edges originating from the specified node */
55
    public Set<Edge> findEdgesFrom(Node from);
56
    
57
    /** Gets path between named nodes using BFS algorithm */
58
    public Route getPath(String nodeNameOrigin, String nodeNameDest);
59
    
60
    /** Gets path between nodes using BFS algorithm */
61
    public Route getPath(Node from, Node to);
62
    
63
    /** Inserts a new node on an existing edge */
64
    public void insertNode(Edge edge, String nodeName);
65
    
66
    /** Inserts a new node on an existing edge */
67
    public void insertNode(Edge edge, Node node);
68
}
69
```
70

71
**Usage Examples:**
72

73
```java
74
import org.eclipse.jetty.deploy.graph.*;
75

76
// Create a custom deployment graph
77
Graph deploymentGraph = new Graph();
78

79
// Add nodes for deployment states
80
Node undeployed = new Node("undeployed");
81
Node deploying = new Node("deploying");
82
Node deployed = new Node("deployed");
83
Node starting = new Node("starting");
84
Node started = new Node("started");
85

86
deploymentGraph.addNode(undeployed);
87
deploymentGraph.addNode(deploying);
88
deploymentGraph.addNode(deployed);
89
deploymentGraph.addNode(starting);
90
deploymentGraph.addNode(started);
91

92
// Connect nodes with edges
93
deploymentGraph.addEdge(undeployed, deploying);
94
deploymentGraph.addEdge(deploying, deployed);
95
deploymentGraph.addEdge(deployed, starting);
96
deploymentGraph.addEdge(starting, started);
97

98
// Find path between states
99
Route deploymentPath = deploymentGraph.getPath("undeployed", "started");
100
System.out.println("Deployment path: " + deploymentPath);
101

102
// Insert intermediate state
103
Node configuring = new Node("configuring");
104
Edge deployingToDeployed = new Edge(deploying, deployed);
105
deploymentGraph.insertNode(deployingToDeployed, configuring);
106

107
// Query graph structure
108
Set<Node> allNodes = deploymentGraph.getNodes();
109
Set<Edge> allEdges = deploymentGraph.getEdges();
110
Set<Edge> edgesFromDeployed = deploymentGraph.findEdgesFrom(deployed);
111
```
112

113
### Node
114

115
Represents a basic graph node with a unique name identifier.
116

117
```java { .api }
118
/**
119
 * Represents a basic graph node
120
 */
121
public final class Node {
122
    /** Creates a node with the specified name */
123
    public Node(String name);
124
    
125
    /** Returns the node name */
126
    public String getName();
127
    
128
    /** Returns string representation of the node */
129
    public String toString();
130
    
131
    /** Returns hash code for the node */
132
    public int hashCode();
133
    
134
    /** Checks equality with another object */
135
    public boolean equals(Object obj);
136
}
137
```
138

139
### Edge
140

141
Represents a basic graph edge connecting two nodes with directional flow.
142

143
```java { .api }
144
/**
145
 * Represents a basic graph edge connecting two nodes
146
 */
147
public final class Edge {
148
    /** Creates an edge from one node to another */
149
    public Edge(Node from, Node to);
150
    
151
    /** Returns the source node */
152
    public Node getFrom();
153
    
154
    /** Returns the destination node */
155
    public Node getTo();
156
    
157
    /** Returns string representation of the edge */
158
    public String toString();
159
    
160
    /** Returns hash code for the edge */
161
    public int hashCode();
162
    
163
    /** Checks equality with another object */
164
    public boolean equals(Object obj);
165
}
166
```
167

168
### Route
169

170
Represents a route through the graph as a sequence of edges and nodes, typically the result of path-finding operations.
171

172
```java { .api }
173
/**
174
 * Represents a route through the graph as a sequence of edges and nodes
175
 */
176
public class Route {
177
    /** Creates a new empty route */
178
    public Route();
179
    
180
    /** Adds an edge to the route */
181
    public void add(Edge edge);
182
    
183
    /** Creates a copy of this route */
184
    public Route forkRoute();
185
    
186
    /** Returns the nodes in the route */
187
    public List<Node> getNodes();
188
    
189
    /** Returns the edges in the route */
190
    public List<Edge> getEdges();
191
    
192
    /** Gets node at the specified index */
193
    public Node getNode(int index);
194
    
195
    /** Returns first node in the route */
196
    public Node firstNode();
197
    
198
    /** Returns last node in the route */
199
    public Node lastNode();
200
    
201
    /** Returns number of nodes in the route */
202
    public int nodes();
203
    
204
    /** Returns number of edges in the route */
205
    public int edges();
206
    
207
    /** Returns true if route is empty */
208
    public boolean isEmpty();
209
    
210
    /** Returns first edge in the route */
211
    public Edge firstEdge();
212
    
213
    /** Returns last edge in the route */
214
    public Edge lastEdge();
215
    
216
    /** Gets edge at the specified index */
217
    public Edge getEdge(int index);
218
    
219
    /** Returns string representation of the route */
220
    public String toString();
221
}
222
```
223

224
**Usage Examples:**
225

226
```java
227
// Working with routes from path finding
228
Route route = graph.getPath("undeployed", "started");
229

230
if (!route.isEmpty()) {
231
    System.out.println("Route from undeployed to started:");
232
    
233
    // Iterate through nodes in the route
234
    List<Node> nodes = route.getNodes();
235
    for (int i = 0; i < nodes.size(); i++) {
236
        Node node = route.getNode(i);
237
        System.out.println("Step " + i + ": " + node.getName());
238
    }
239
    
240
    // Access route endpoints
241
    Node start = route.firstNode();
242
    Node end = route.lastNode();
243
    System.out.println("Route: " + start.getName() + " -> " + end.getName());
244
    
245
    // Work with edges in the route
246
    for (int i = 0; i < route.edges(); i++) {
247
        Edge edge = route.getEdge(i);
248
        System.out.println("Transition: " + edge.getFrom().getName() + 
249
                         " -> " + edge.getTo().getName());
250
    }
251
}
252

253
// Create and manipulate routes manually
254
Route customRoute = new Route();
255
customRoute.add(new Edge(new Node("start"), new Node("middle")));
256
customRoute.add(new Edge(new Node("middle"), new Node("end")));
257

258
// Fork routes for parallel processing
259
Route originalRoute = graph.getPath("deployed", "started");
260
Route alternativeRoute = originalRoute.forkRoute();
261
// Modify alternativeRoute independently
262
```
263

264
### GraphOutputDot
265

266
Utility class for outputting graphs in GraphViz Dot format for visualization and debugging.
267

268
```java { .api }
269
/**
270
 * Utility for outputting graphs in GraphViz Dot format
271
 */
272
public class GraphOutputDot {
273
    /** Writes graph to DOT file for GraphViz visualization */
274
    public static void write(Graph graph, File outputFile) throws IOException;
275
}
276
```
277

278
**Usage Examples:**
279

280
```java
281
import org.eclipse.jetty.deploy.graph.GraphOutputDot;
282
import java.io.File;
283
import java.io.IOException;
284

285
// Export graph to DOT format for visualization
286
Graph graph = deploymentManager.getLifeCycle();
287
File dotFile = new File("deployment-lifecycle.dot");
288

289
try {
290
    GraphOutputDot.write(graph, dotFile);
291
    System.out.println("Graph exported to: " + dotFile.getAbsolutePath());
292
    
293
    // The generated DOT file can be used with GraphViz tools:
294
    // dot -Tpng deployment-lifecycle.dot -o deployment-lifecycle.png
295
    // dot -Tsvg deployment-lifecycle.dot -o deployment-lifecycle.svg
296
} catch (IOException e) {
297
    System.err.println("Failed to export graph: " + e.getMessage());
298
}
299

300
// Visualize custom graphs
301
Graph customGraph = new Graph();
302
// ... build custom graph structure ...
303
GraphOutputDot.write(customGraph, new File("custom-states.dot"));
304
```
305

306
## Graph Usage Patterns
307

308
### Building State Machines
309

310
```java
311
// Create a state machine for application deployment
312
Graph stateMachine = new Graph();
313

314
// Define states
315
Node[] states = {
316
    new Node("undeployed"),
317
    new Node("deploying"), 
318
    new Node("deployed"),
319
    new Node("starting"),
320
    new Node("started"),
321
    new Node("stopping"),
322
    new Node("failed")
323
};
324

325
// Add all states to graph
326
for (Node state : states) {
327
    stateMachine.addNode(state);
328
}
329

330
// Define state transitions
331
stateMachine.addEdge("undeployed", "deploying");
332
stateMachine.addEdge("deploying", "deployed");
333
stateMachine.addEdge("deploying", "failed");
334
stateMachine.addEdge("deployed", "starting");
335
stateMachine.addEdge("starting", "started");
336
stateMachine.addEdge("starting", "failed");
337
stateMachine.addEdge("started", "stopping");
338
stateMachine.addEdge("stopping", "deployed");
339
stateMachine.addEdge("stopping", "failed");
340

341
// Any state can transition to failed
342
for (Node state : states) {
343
    if (!"failed".equals(state.getName())) {
344
        stateMachine.addEdge(state, stateMachine.getNodeByName("failed"));
345
    }
346
}
347
```
348

349
### Path Finding and Validation
350

351
```java
352
// Validate that a transition is possible
353
public boolean canTransition(Graph graph, String fromState, String toState) {
354
    Route route = graph.getPath(fromState, toState);
355
    return route != null && !route.isEmpty();
356
}
357

358
// Get all possible next states
359
public Set<String> getNextStates(Graph graph, String currentState) {
360
    Node currentNode = graph.getNodeByName(currentState);
361
    Set<Edge> outgoingEdges = graph.findEdgesFrom(currentNode);
362
    
363
    return outgoingEdges.stream()
364
        .map(edge -> edge.getTo().getName())
365
        .collect(Collectors.toSet());
366
}
367

368
// Find shortest path between states
369
public List<String> getTransitionPath(Graph graph, String from, String to) {
370
    Route route = graph.getPath(from, to);
371
    if (route == null || route.isEmpty()) {
372
        return Collections.emptyList();
373
    }
374
    
375
    return route.getNodes().stream()
376
        .map(Node::getName)
377
        .collect(Collectors.toList());
378
}
379
```