(no commit message)

[utils] / system / general / src / main / java / org / wamblee / system / graph / Graph.java

diff --git a/system/general/src/main/java/org/wamblee/system/graph/Graph.java b/system/general/src/main/java/org/wamblee/system/graph/Graph.java
index 5d6e6ccddf06333425914dd6963eeacf8f7d8ebf..387d5e4fd3ffc563d2690495078602d9928ccd6c 100644 (file)
--- a/system/general/src/main/java/org/wamblee/system/graph/Graph.java
+++ b/system/general/src/main/java/org/wamblee/system/graph/Graph.java
@@ -18,16 +18,33 @@ package org.wamblee.system.graph;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents a graph consisting of nodes and edges.
+ * 
+ * @author Erik Brakkee
+ */
 public class Graph {
 
     private List<Node> _nodes;
     private List<Edge> _edges;
 
+    /**
+     * Constructs the graph.
+     */
     public Graph() {
         _nodes = new ArrayList<Node>();
         _edges = new ArrayList<Edge>();
     }
 
+    /**
+     * Adds a node.
+     * 
+     * @param aNode
+     *            Node to add.
+     * @throws IllegalArgumentException
+     *             In case the node already exists. Node equality is checked
+     *             using <code>equals</code>.
+     */
     public void addNode(Node aNode) {
         if (_nodes.contains(aNode)) {
             throw new IllegalArgumentException("Node '" + aNode.getName()
@@ -35,16 +52,32 @@ public class Graph {
         }
         _nodes.add(aNode);
     }
-    
-    public Node findNode(String aName) { 
-        for (Node node: _nodes) { 
-            if ( node.getName().equals(aName)) { 
-                return node; 
+
+    /**
+     * Finds a node with the given name.
+     * 
+     * @param aName
+     *            Node name.
+     * @return Node or null if not found.
+     */
+    public Node findNode(String aName) {
+        for (Node node : _nodes) {
+            if (node.getName().equals(aName)) {
+                return node;
             }
         }
-        return null; 
+        return null;
     }
 
+    /**
+     * Removes a node.
+     * 
+     * @param aNode
+     *            Node to remove.
+     * @return True iff the node was removed.
+     * @throws IllegalArgumentException
+     *             In case there are edges of which the node is a part.
+     */
     public boolean removeNode(Node aNode) {
         if (!findOutgoing(aNode).isEmpty() || !findIncoming(aNode).isEmpty()) {
             throw new IllegalArgumentException("Cannot remove node '"
@@ -54,12 +87,30 @@ public class Graph {
         return _nodes.remove(aNode);
     }
 
+    /**
+     * Adds a list of nodes.
+     * 
+     * @param aNodes
+     *            Nodes to add.
+     * 
+     * @see #addNode(Node)
+     */
     public void addNodes(List<Node> aNodes) {
         for (Node node : aNodes) {
             addNode(node);
         }
     }
 
+    /**
+     * Adds an edge.
+     * 
+     * @param aEdge
+     *            Edge to add.
+     * @throws IllegalArgumentException
+     *             In case one of the nodes of the edges is not part of the
+     *             graph or if the same edge (as determined by
+     *             {@link #equals(Object)} is already a part of the graph.
+     */
     public void addEdge(Edge aEdge) {
         if (_edges.contains(aEdge)) {
             throw new IllegalArgumentException("Edge '" + aEdge
@@ -76,24 +127,46 @@ public class Graph {
         _edges.add(aEdge);
     }
 
+    /**
+     * Removes an edge. 
+     * @param aEdge Edge to remove. 
+     * @return True if the edge was removed. 
+     */
     public boolean removeEdge(Edge aEdge) {
         return _edges.remove(aEdge);
     }
 
+    /**
+     * Adds a number of edges. 
+     * @param aEdges Edges to add. 
+     */
     public void addEdges(List<Edge> aEdges) {
         for (Edge edge : aEdges) {
             addEdge(edge);
         }
     }
 
+    /**
+     * Gets the nodes. 
+     * @return Copy of the list of nodes of the graph. 
+     */
     public List<Node> getNodes() {
         return new ArrayList<Node>(_nodes);
     }
 
+    /**
+     * Gets the edges. 
+     * @return Copy of the list of edges of the graph. 
+     */
     public List<Edge> getEdges() {
         return new ArrayList<Edge>(_edges);
     }
 
+    /**
+     * Extends the graph with edges using an edge factory. All combinations of 
+     * nodes are passed to the factory which creates additional edges. 
+     * @param aFactory Edge factory. 
+     */
     public void extend(EdgeFactory aFactory) {
         for (Node from : _nodes) {
             for (Node to : _nodes) {
@@ -102,6 +175,12 @@ public class Graph {
         }
     }
 
+    /**
+     * Finds all outgoing edges of a node. More specifically, finds 
+     * all edges <code>e</code> for which <code>e.getFrom().getName() = aNode.getName()</code>.
+     * @param aNode Node for which to find outgoing edges. 
+     * @return List of outgoing edges. 
+     */
     public List<Edge> findOutgoing(Node aNode) {
         List<Edge> result = new ArrayList<Edge>();
         for (Edge edge : _edges) {
@@ -112,6 +191,13 @@ public class Graph {
         return result;
     }
 
+    /**
+     * Finds all incoming edges of a node. 
+     * More specifically, finds 
+     * all edges <code>e</code> for which <code>e.getTo().getName() = aNode.getName()</code>.
+     * @param aNode Node for which to find incoming edges. 
+     * @return List of incoming edges. 
+     */
     public List<Edge> findIncoming(Node aNode) {
         List<Edge> result = new ArrayList<Edge>();
         for (Edge edge : _edges) {
@@ -122,9 +208,15 @@ public class Graph {
         return result;
     }
 
+    /**
+     * Implements a visitor design pattern.
+     * This loops over all nodes and all edges and invokes the appropriate visit
+     * methods on the visitor.  
+     * @param aVisitor Visitor. 
+     */
     public void accept(Visitor aVisitor) {
         List<Node> nodes = getNodes(); // copy to make sure the visitor can
-                                        // modify the
+        // modify the
         // list of nodes as part of the loop.
         List<Edge> edges = getEdges(); // copy ..... (see above).