(no commit message)
authorerik <erik@77661180-640e-0410-b3a8-9f9b13e6d0e0>
Fri, 16 May 2008 18:15:10 +0000 (18:15 +0000)
committererik <erik@77661180-640e-0410-b3a8-9f9b13e6d0e0>
Fri, 16 May 2008 18:15:10 +0000 (18:15 +0000)
20 files changed:
trunk/system/general/src/main/java/org/wamblee/system/container/Container.java
trunk/system/general/src/main/java/org/wamblee/system/graph/DefaultEdge.java
trunk/system/general/src/main/java/org/wamblee/system/graph/DefaultNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/Edge.java
trunk/system/general/src/main/java/org/wamblee/system/graph/EdgeFactory.java
trunk/system/general/src/main/java/org/wamblee/system/graph/Graph.java
trunk/system/general/src/main/java/org/wamblee/system/graph/Node.java
trunk/system/general/src/main/java/org/wamblee/system/graph/Visitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ApplyRestrictionsVisitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyProvidedVisitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyRequiredVisitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/CheckStartupDependenciesVisitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ComponentGraph.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ComponentNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ExternalProvidedInterfaceNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ExternalRequiredInterfaceNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/LinkVisitor.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/ProvidedInterfaceNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/RequiredInterfaceNode.java
trunk/system/general/src/main/java/org/wamblee/system/graph/component/RequiredProvidedEdgeFactory.java

index 349e59782cee2eae1251ab216d1648a82f12d815..cfc5b8aa140ad34fe11a65d06c009e4afe288da9 100644 (file)
@@ -16,7 +16,6 @@
 package org.wamblee.system.container;
 
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
index 24a2c7eb7608b19998f980e02875c16e735a6dba..35d648ff7228d4136733e29820d8e2c3931ca1f0 100644 (file)
  */ 
 package org.wamblee.system.graph;
 
+/**
+ * Represents an application-independent edge of a graph. 
+ * Applications might choose to implement the Edge interface
+ * directly. 
+ * 
+ * @author Erik Brakkee
+ */
 public class DefaultEdge implements Edge {
     
     private Node _from; 
index 7a7ff3c528491b9b827fe46fd0e1dc3df530b9f3..925c08c17b407c9c0b96c65812beca591de6a9dc 100644 (file)
  */ 
 package org.wamblee.system.graph;
 
+/**
+ * Default application-independent node. Specific applications of the graph might
+ * implement the Node interface directly.  
+ * @author Erik Brakkee
+ *
+ */
 public class DefaultNode implements Node {
     
     private String _name; 
     
+    /**
+     * Constructs the node. 
+     * @param aName Node name. 
+     */
     public DefaultNode(String aName) { 
         _name = aName; 
     }
 
+    /**
+     * Returns the node name. 
+     */
     @Override
     public String getName() {
         return _name;
index 3aa0d846ab4909aaeb8520157634a9102d0b1d96..a340015af304d732a86d98fadac70bffede33bba 100644 (file)
  */ 
 package org.wamblee.system.graph;
 
+/**
+ * Represents an edge of a graph. 
+ * 
+ * @author Erik Brakkee
+ */
 public interface Edge {
 
+    /**
+     * @return The from part of the edge. 
+     */
     Node getFrom();
+    
+    /**
+     * @return The to part of the edge. 
+     */
     Node getTo();
 }
index 32601e7f9b95114ee4dcd8bd7856127fe3bb3439..4ac39f6fdd07f08d499aa5f83a5bad66e433de80 100644 (file)
@@ -17,6 +17,18 @@ package org.wamblee.system.graph;
 
 import java.util.List;
 
+/**
+ * Edge factory used to extend a graph with new edges. 
+ * @author Erik Brakkee
+ *
+ * @param <NodeType> Type of node. 
+ */
 public interface EdgeFactory<NodeType extends Node> {
+    /**
+     * Computes a number of new edges to be added to the graph. 
+     * @param aFrom From node. 
+     * @param aTo To node. 
+     * @return List of edges from the from to the to node. 
+     */
     List<Edge> create(NodeType aFrom, NodeType aTo); 
 }
index 5d6e6ccddf06333425914dd6963eeacf8f7d8ebf..387d5e4fd3ffc563d2690495078602d9928ccd6c 100644 (file)
@@ -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).
 
index 0becfda6488994a85cad4c0170440fa9defcf666..d1df3c03056cbab65d76efdee77d3c471afc662a 100644 (file)
  */ 
 package org.wamblee.system.graph;
 
+/**
+ * Represents a node in a graph. 
+ * @author Erik Brakkee
+ */
 public interface Node {
     
+    /**
+     * Gets the node name uniquely identifying the node in the graph. 
+     * @return Node name. 
+     */
     String getName();
 
 }
index 9c3240e0a09f92abd85cdedd7ba7308ade6c141b..e65a535c062b4f6c656a1c25b555ad7c00462d89 100644 (file)
  */ 
 package org.wamblee.system.graph;
 
+/**
+ * Visitor of a graph. 
+ * @author Erik Brakkee.
+ *
+ */
 public interface Visitor {
 
+    /**
+     * Visits a node. Called by {@link Graph#accept(Visitor)}.
+     * @param aNode Node to visit. 
+     */
     void visitNode(Node aNode); 
     
+    /**
+     * Visits a node. Called by {@link Graph#accept(Visitor)}.
+     * @param aEdge Edge to visit. 
+     */
     void visitEdge(Edge aEdge); 
 }
index 8213bb8bffcd14cfe4e439a4f4920828f191ad94..72cbc273807cf4f6c4449c515b9f97653a7022c5 100644 (file)
@@ -24,11 +24,22 @@ import org.wamblee.system.graph.Graph;
 import org.wamblee.system.graph.Node;
 import org.wamblee.system.graph.Visitor;
 
+/**
+ * Applies restrictions on a graph by removing all edges that violate the restriction. 
+ * 
+ * @author Erik Brakkee. 
+ *
+ */
 public class ApplyRestrictionsVisitor implements Visitor {
     
     private Graph _graph; 
     private InterfaceRestriction _restriction; 
-    
+
+    /**
+     * Constructs the visitor. 
+     * @param aGraph Graph. 
+     * @param aRestriction Restriction. 
+     */
     public ApplyRestrictionsVisitor(Graph aGraph, InterfaceRestriction aRestriction) { 
         _graph = aGraph; 
         _restriction = aRestriction;
index ef5ea4fb7f024eb459db599b97f2e7ee8ade63e8..c921630b5f9b9f4f73dd83ec31b1dcee413fd582 100644 (file)
@@ -24,10 +24,8 @@ import org.wamblee.system.graph.Node;
 import org.wamblee.system.graph.Visitor;
 
 /**
- * Visitor that checks externally provided
- * <ul>
- *   <li>
- * </ul>
+ * Visitor that checks whether all externally provided interfaces are actually provided 
+ * by any of the internal components. 
  * 
  * @author Erik Brakkee
  *
@@ -35,7 +33,11 @@ import org.wamblee.system.graph.Visitor;
 public class CheckExternallyProvidedVisitor implements Visitor {
     
     private Graph _graph; 
-    
+
+    /**
+     * Constructs the visitor. 
+     * @param aGraph Component graph. 
+     */
     public CheckExternallyProvidedVisitor(Graph aGraph) { 
         _graph = aGraph; 
     }
index 025608a9169eab08fe06ed7afc02d888a2b13973..9e412b6fdbacbb5b3f4e8de6cb4feb1e63bea8b9 100644 (file)
@@ -21,11 +21,8 @@ import org.wamblee.system.graph.Node;
 import org.wamblee.system.graph.Visitor;
 
 /**
- * Visitor that checks externally required services: 
- * <ul>
- *   <li>
- * </ul>
- * 
+ * Visitor that checks whether all required external interfaces of the container
+ * are provided. 
  * @author Erik Brakkee
  *
  */
index 5b50e0925c0b57ce16f3796d2651133a2f9b0ee6..61f4e7045cbcc888952cd17d99db5dff5efc8ae9 100644 (file)
@@ -24,11 +24,21 @@ import org.wamblee.system.graph.Graph;
 import org.wamblee.system.graph.Node;
 import org.wamblee.system.graph.Visitor;
 
+/**
+ * Checks whether the given component graph can be started in component
+ * order without any missing dependencies. 
+ * @author Erik Brakkee
+ *
+ */
 public class CheckStartupDependenciesVisitor implements Visitor {
     
     private Graph _graph; 
     private List<Node> _available; 
-    
+
+    /**
+     * Constructs the visitor. 
+     * @param aGraph Graph. 
+     */
     public CheckStartupDependenciesVisitor(Graph aGraph) { 
         _graph = aGraph; 
         _available = new ArrayList<Node>();
index 20313b5983785b82d8b9d033a929a6fb3942e64f..15f86557ab2a55dccdec85b2d8604d6b3bfcc07a 100644 (file)
@@ -33,26 +33,53 @@ import org.wamblee.system.graph.Node;
 // TODO info superfluous required interfaces
 // TODO check optional external required but mandatory internal.  
 
+/**
+ * Represents a component graph and provides the bridge from the 
+ * component model to a graph model. The graph model is easier
+ * to work with to implement specific actions and validations than 
+ * the component model. 
+ */
 public class ComponentGraph extends Graph {
     
     private CompositeInterfaceRestriction _restriction; 
 
+    /**
+     * Constructs an empty component graph. 
+     */
     public ComponentGraph() { 
         _restriction = new CompositeInterfaceRestriction(); 
     }
     
+    /**
+     * Adds a restriction that must be satisfied by the component model. 
+     * @param aRestriction Restriction. 
+     */
     public void addRestriction(InterfaceRestriction aRestriction) { 
         _restriction.add(aRestriction);
     }
     
+    /**
+     * Adds an externally required interface of a container.  
+     * This should be called before any components of the container are
+     * added. 
+     * @param aInterface Required interface. 
+     */
     public void addRequiredInterface(RequiredInterface aInterface) { 
         addNode(new ExternalRequiredInterfaceNode(aInterface));
     }
     
+    /**
+     * Adds an externally provided interface of a container.
+     * This should be called after all components of the container have been added.  
+     * @param aInterface Provided interface. 
+     */
     public void addProvidedInterface(ProvidedInterface aInterface) { 
         addNode(new ExternalProvidedInterfaceNode(aInterface));
     }
     
+    /**
+     * Validates the component graph. 
+     */
     public void validate() { 
         extend(new RequiredProvidedEdgeFactory());
         accept(new ApplyRestrictionsVisitor(this, _restriction));
@@ -62,6 +89,10 @@ public class ComponentGraph extends Graph {
         accept(new CheckStartupDependenciesVisitor(this));
     }
     
+    /**
+     * Links provided and required interfaces together in the component
+     * model based on the graph model. 
+     */
     public void link() { 
         accept(new LinkVisitor());
     }
@@ -86,6 +117,11 @@ public class ComponentGraph extends Graph {
         return result; 
     }
     
+    /**
+     * Adds a component by adding required interfaces, components, and
+     * provided interfaces. 
+     * @param aComponent Component to add. 
+     */
     public void addComponent(Component aComponent) { 
         // Add required interfaces. 
         Node compNode = new ComponentNode(aComponent);
index 72e7110687cc6b011c20f490f644c78e682d8783..dc344268b0fed6d7bc4203f2032f771348649d86 100644 (file)
@@ -18,6 +18,11 @@ package org.wamblee.system.graph.component;
 import org.wamblee.system.core.Component;
 import org.wamblee.system.graph.Node;
 
+/**
+ * Represents a component node. 
+ * @author Erik Brakkee. 
+ *
+ */
 public class ComponentNode implements Node {
     
     private Component<?> _component; 
index c2c7f21282b87c90c07de6fa711efda9f0829432..388012709538d607b99c8fb9e4702e55fb21a439 100644 (file)
@@ -18,6 +18,11 @@ package org.wamblee.system.graph.component;
 import org.wamblee.system.core.ProvidedInterface;
 import org.wamblee.system.graph.Node;
 
+/**
+ * Represents an external provided interface of a container. 
+ * @author Erik Brakkee
+ *
+ */
 public class ExternalProvidedInterfaceNode implements Node {
 
     private ProvidedInterface _provided; 
index 580bc719697067ed065e0bc309bdef06c07ff49c..3b195a65742089d837680640ddcc89e2383dba10 100644 (file)
@@ -18,6 +18,11 @@ package org.wamblee.system.graph.component;
 import org.wamblee.system.core.RequiredInterface;
 import org.wamblee.system.graph.Node;
 
+/**
+ * Represents an externally required interface of a container. 
+ * @author Erik Brakkee
+ *
+ */
 public class ExternalRequiredInterfaceNode implements Node {
     
     private RequiredInterface _required; 
index 088f05856ffdc1d28c90198651345ef55614fd84..cc2007ff7d47c992ec85cd8c1078e02b2183565a 100644 (file)
@@ -26,6 +26,10 @@ import org.wamblee.system.graph.Visitor;
  * Visitor that creates links between required and provided interfaces as
  * described by the edges in the graph.
  * 
+ * Specically it links together (1) required and provided interfaces of internal component 
+ * of a container and (2) the providers of externally required interfaces and internal required
+ * interfaces. 
+ * 
  * @author Erik Brakkee
  * 
  */
index e2782b09331f6381704cdf1651119e7381399131..2fb2c0f7ec5280d62eb90231aaada36fb61e1fc3 100644 (file)
@@ -19,6 +19,10 @@ import org.wamblee.system.core.Component;
 import org.wamblee.system.core.ProvidedInterface;
 import org.wamblee.system.graph.Node;
 
+/**
+ * Provided interface node. 
+ * @author Erik Brakkee
+ */
 public class ProvidedInterfaceNode implements Node {
     
     private Component _component; 
index 1b053b1891d3d723ecc879ff23982733b2e7674f..b1540512dffb6f542a754c6a48a383b216778b2a 100644 (file)
@@ -19,6 +19,11 @@ import org.wamblee.system.core.Component;
 import org.wamblee.system.core.RequiredInterface;
 import org.wamblee.system.graph.Node;
 
+/**
+ * Required interface node. 
+ * @author Erik Brakkee
+ *
+ */
 public class RequiredInterfaceNode implements Node {
     
     private Component _component; 
index 983acba1c78c61e343f75b7af1f9374c6e5693f0..89f4056c423f11f572be0bc39aeebd7a04a1be95 100644 (file)
@@ -24,7 +24,13 @@ import org.wamblee.system.graph.EdgeFactory;
 import org.wamblee.system.graph.Node;
 
 /**
- * Factory that creates links between required and provided interfaces.
+ * Factory that creates edges between required and provided interfaces.
+ * Speciflcally it creates: 
+ * <ul>
+ *   <li> Edges between provided and required interfaces of a container. </li>
+ *   <li> Edges between required and externally required interfaces </li>
+ *   <li> Edges between externally provided and provided interfaces.  
+ * </ul>
  * 
  * @author Erik Brakkee
  *