From: erik Date: Fri, 16 May 2008 18:15:10 +0000 (+0000) Subject: (no commit message) X-Git-Tag: wamblee-utils-0.2~1^2~103 X-Git-Url: http://wamblee.org/gitweb/?a=commitdiff_plain;h=901d0a5b61ed523b15124daf63a053f9c4a5fb4e;p=utils --- diff --git a/system/general/src/main/java/org/wamblee/system/container/Container.java b/system/general/src/main/java/org/wamblee/system/container/Container.java index 349e5978..cfc5b8aa 100644 --- a/system/general/src/main/java/org/wamblee/system/container/Container.java +++ b/system/general/src/main/java/org/wamblee/system/container/Container.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/DefaultEdge.java b/system/general/src/main/java/org/wamblee/system/graph/DefaultEdge.java index 24a2c7eb..35d648ff 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/DefaultEdge.java +++ b/system/general/src/main/java/org/wamblee/system/graph/DefaultEdge.java @@ -15,6 +15,13 @@ */ 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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/DefaultNode.java b/system/general/src/main/java/org/wamblee/system/graph/DefaultNode.java index 7a7ff3c5..925c08c1 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/DefaultNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/DefaultNode.java @@ -15,14 +15,27 @@ */ 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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/Edge.java b/system/general/src/main/java/org/wamblee/system/graph/Edge.java index 3aa0d846..a340015a 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/Edge.java +++ b/system/general/src/main/java/org/wamblee/system/graph/Edge.java @@ -15,8 +15,20 @@ */ 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(); } diff --git a/system/general/src/main/java/org/wamblee/system/graph/EdgeFactory.java b/system/general/src/main/java/org/wamblee/system/graph/EdgeFactory.java index 32601e7f..4ac39f6f 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/EdgeFactory.java +++ b/system/general/src/main/java/org/wamblee/system/graph/EdgeFactory.java @@ -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 Type of node. + */ public interface EdgeFactory { + /** + * 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 create(NodeType aFrom, NodeType aTo); } 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 5d6e6ccd..387d5e4f 100644 --- 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 _nodes; private List _edges; + /** + * Constructs the graph. + */ public Graph() { _nodes = new ArrayList(); _edges = new ArrayList(); } + /** + * Adds a node. + * + * @param aNode + * Node to add. + * @throws IllegalArgumentException + * In case the node already exists. Node equality is checked + * using equals. + */ 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 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 aEdges) { for (Edge edge : aEdges) { addEdge(edge); } } + /** + * Gets the nodes. + * @return Copy of the list of nodes of the graph. + */ public List getNodes() { return new ArrayList(_nodes); } + /** + * Gets the edges. + * @return Copy of the list of edges of the graph. + */ public List getEdges() { return new ArrayList(_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 e for which e.getFrom().getName() = aNode.getName(). + * @param aNode Node for which to find outgoing edges. + * @return List of outgoing edges. + */ public List findOutgoing(Node aNode) { List result = new ArrayList(); 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 e for which e.getTo().getName() = aNode.getName(). + * @param aNode Node for which to find incoming edges. + * @return List of incoming edges. + */ public List findIncoming(Node aNode) { List result = new ArrayList(); 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 nodes = getNodes(); // copy to make sure the visitor can - // modify the + // modify the // list of nodes as part of the loop. List edges = getEdges(); // copy ..... (see above). diff --git a/system/general/src/main/java/org/wamblee/system/graph/Node.java b/system/general/src/main/java/org/wamblee/system/graph/Node.java index 0becfda6..d1df3c03 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/Node.java +++ b/system/general/src/main/java/org/wamblee/system/graph/Node.java @@ -15,8 +15,16 @@ */ 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(); } diff --git a/system/general/src/main/java/org/wamblee/system/graph/Visitor.java b/system/general/src/main/java/org/wamblee/system/graph/Visitor.java index 9c3240e0..e65a535c 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/Visitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/Visitor.java @@ -15,9 +15,22 @@ */ 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); } diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ApplyRestrictionsVisitor.java b/system/general/src/main/java/org/wamblee/system/graph/component/ApplyRestrictionsVisitor.java index 8213bb8b..72cbc273 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ApplyRestrictionsVisitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ApplyRestrictionsVisitor.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyProvidedVisitor.java b/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyProvidedVisitor.java index ef5ea4fb..c921630b 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyProvidedVisitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyProvidedVisitor.java @@ -24,10 +24,8 @@ import org.wamblee.system.graph.Node; import org.wamblee.system.graph.Visitor; /** - * Visitor that checks externally provided - *
    - *
  • - *
+ * 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; } diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyRequiredVisitor.java b/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyRequiredVisitor.java index 025608a9..9e412b6f 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyRequiredVisitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/CheckExternallyRequiredVisitor.java @@ -21,11 +21,8 @@ import org.wamblee.system.graph.Node; import org.wamblee.system.graph.Visitor; /** - * Visitor that checks externally required services: - *
    - *
  • - *
- * + * Visitor that checks whether all required external interfaces of the container + * are provided. * @author Erik Brakkee * */ diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/CheckStartupDependenciesVisitor.java b/system/general/src/main/java/org/wamblee/system/graph/component/CheckStartupDependenciesVisitor.java index 5b50e092..61f4e704 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/CheckStartupDependenciesVisitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/CheckStartupDependenciesVisitor.java @@ -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 _available; - + + /** + * Constructs the visitor. + * @param aGraph Graph. + */ public CheckStartupDependenciesVisitor(Graph aGraph) { _graph = aGraph; _available = new ArrayList(); diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ComponentGraph.java b/system/general/src/main/java/org/wamblee/system/graph/component/ComponentGraph.java index 20313b59..15f86557 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ComponentGraph.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ComponentGraph.java @@ -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); diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ComponentNode.java b/system/general/src/main/java/org/wamblee/system/graph/component/ComponentNode.java index 72e71106..dc344268 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ComponentNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ComponentNode.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ExternalProvidedInterfaceNode.java b/system/general/src/main/java/org/wamblee/system/graph/component/ExternalProvidedInterfaceNode.java index c2c7f212..38801270 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ExternalProvidedInterfaceNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ExternalProvidedInterfaceNode.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ExternalRequiredInterfaceNode.java b/system/general/src/main/java/org/wamblee/system/graph/component/ExternalRequiredInterfaceNode.java index 580bc719..3b195a65 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ExternalRequiredInterfaceNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ExternalRequiredInterfaceNode.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/LinkVisitor.java b/system/general/src/main/java/org/wamblee/system/graph/component/LinkVisitor.java index 088f0585..cc2007ff 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/LinkVisitor.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/LinkVisitor.java @@ -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 * */ diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/ProvidedInterfaceNode.java b/system/general/src/main/java/org/wamblee/system/graph/component/ProvidedInterfaceNode.java index e2782b09..2fb2c0f7 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/ProvidedInterfaceNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/ProvidedInterfaceNode.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/RequiredInterfaceNode.java b/system/general/src/main/java/org/wamblee/system/graph/component/RequiredInterfaceNode.java index 1b053b18..b1540512 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/RequiredInterfaceNode.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/RequiredInterfaceNode.java @@ -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; diff --git a/system/general/src/main/java/org/wamblee/system/graph/component/RequiredProvidedEdgeFactory.java b/system/general/src/main/java/org/wamblee/system/graph/component/RequiredProvidedEdgeFactory.java index 983acba1..89f4056c 100644 --- a/system/general/src/main/java/org/wamblee/system/graph/component/RequiredProvidedEdgeFactory.java +++ b/system/general/src/main/java/org/wamblee/system/graph/component/RequiredProvidedEdgeFactory.java @@ -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: + *
    + *
  • Edges between provided and required interfaces of a container.
    • + *
  • Edges between required and externally required interfaces
    • + *
  • Edges between externally provided and provided interfaces. + *
* * @author Erik Brakkee *