[jboss-svn-commits] JBoss Common SVN: r2218 - common-core/trunk/src/main/java/org/jboss/util/graph
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Dec 12 22:35:03 EST 2006
Author: scott.stark at jboss.org
Date: 2006-12-12 22:34:58 -0500 (Tue, 12 Dec 2006)
New Revision: 2218
Modified:
common-core/trunk/src/main/java/org/jboss/util/graph/DFSVisitor.java
common-core/trunk/src/main/java/org/jboss/util/graph/Graph.java
common-core/trunk/src/main/java/org/jboss/util/graph/Vertex.java
common-core/trunk/src/main/java/org/jboss/util/graph/Visitor.java
common-core/trunk/src/main/java/org/jboss/util/graph/VisitorEX.java
Log:
Cleanup javadoc
Modified: common-core/trunk/src/main/java/org/jboss/util/graph/DFSVisitor.java
===================================================================
--- common-core/trunk/src/main/java/org/jboss/util/graph/DFSVisitor.java 2006-12-13 02:07:44 UTC (rev 2217)
+++ common-core/trunk/src/main/java/org/jboss/util/graph/DFSVisitor.java 2006-12-13 03:34:58 UTC (rev 2218)
@@ -22,7 +22,10 @@
package org.jboss.util.graph;
/**
+ * A spanning tree visitor callback interface
*
+ * @see Graph#dfsSpanningTree(Vertex, DFSVisitor)
+ *
* @author Scott.Stark at jboss.org
* @version $Revision$
*/
Modified: common-core/trunk/src/main/java/org/jboss/util/graph/Graph.java
===================================================================
--- common-core/trunk/src/main/java/org/jboss/util/graph/Graph.java 2006-12-13 02:07:44 UTC (rev 2217)
+++ common-core/trunk/src/main/java/org/jboss/util/graph/Graph.java 2006-12-13 03:34:58 UTC (rev 2218)
@@ -21,8 +21,11 @@
*/
package org.jboss.util.graph;
+import java.util.Collections;
+import java.util.Comparator;
import java.util.LinkedList;
import java.util.ArrayList;
+import java.util.List;
/**
* A directed graph data structure.
@@ -43,7 +46,9 @@
/** Vector<Edge> of edges in the graph */
private ArrayList<Edge<T>> edges;
- // Construct a new graph
+ /**
+ * Construct a new graph without any vertices or edges
+ */
public Graph()
{
verticies = new ArrayList<Vertex<T>>();
@@ -66,7 +71,12 @@
*/
public boolean addVertex(Vertex<T> v)
{
- return verticies.add(v);
+ boolean added = false;
+ if( verticies.contains(v) == false )
+ {
+ added = verticies.add(v);
+ }
+ return added;
}
/**
@@ -90,14 +100,32 @@
}
/**
- * Insert a directed, weighted Edge<T> into the graph
+ * Get the graph verticies
+ *
+ * @return the graph verticies
+ */
+ public List<Vertex<T>> getVerticies()
+ {
+ return this.verticies;
+ }
+
+ /**
+ * Insert a directed, weighted Edge<T> into the graph.
+ *
* @param from - the Edge<T> starting vertex
* @param to - the Edge<T> ending vertex
* @param cost - the Edge<T> weight/cost
* @return true if the Edge<T> was added, false if from already has this Edge<T>
+ * @throws IllegalArgumentException if from/to are not verticies in
+ * the graph
*/
public boolean addEdge(Vertex<T> from, Vertex<T> to, int cost)
+ throws IllegalArgumentException
{
+ if( verticies.contains(from) == false )
+ throw new IllegalArgumentException("from is not in graph");
+ if( verticies.contains(to) == false )
+ throw new IllegalArgumentException("to is not in graph");
Edge<T> e = new Edge<T>(from, to, cost);
if (from.findEdge(to) != null)
return false;
@@ -112,17 +140,30 @@
/**
* Insert a bidirectional Edge<T> in the graph
+ *
* @param from - the Edge<T> starting vertex
* @param to - the Edge<T> ending vertex
* @param cost - the Edge<T> weight/cost
* @return true if edges between both nodes were added, false otherwise
+ * @throws IllegalArgumentException if from/to are not verticies in
+ * the graph
*/
public boolean insertBiEdge(Vertex<T> from, Vertex<T> to, int cost)
+ throws IllegalArgumentException
{
return addEdge(from, to, cost) && addEdge(to, from, cost);
}
/**
+ * Get the graph edges
+ * @return the graph edges
+ */
+ public List<Edge<T>> getEdges()
+ {
+ return this.edges;
+ }
+
+ /**
* Remove a vertex from the graph
* @param from the Vertex to remove
* @return true if the Vertex was removed
@@ -216,6 +257,15 @@
};
this.depthFirstSearch(v, wrapper);
}
+ /**
+ * Perform a depth first serach using recursion. The search may
+ * be cut short if the visitor throws an exception.
+ *
+ * @param v - the Vertex to start the search from
+ * @param visitor - the vistor to inform prior to
+ * @see Visitor#visit(Graph, Vertex)
+ * @throws Exception if visitor.visit throws an exception
+ */
public <E extends Exception> void depthFirstSearch(Vertex<T> v, VisitorEX<T, E> visitor)
throws E
{
@@ -232,7 +282,13 @@
}
}
- // Breadth First Search
+ /**
+ * Perform a breadth first search of this graph, starting at v.
+ *
+ * @param v - the search starting point
+ * @param visitor - the vistor whose vist method is called prior
+ * to visting a vertex.
+ */
public void breadthFirstSearch(Vertex<T> v, final Visitor<T> visitor)
{
VisitorEX<T, RuntimeException> wrapper = new VisitorEX<T, RuntimeException>()
@@ -244,6 +300,16 @@
};
this.breadthFirstSearch(v, wrapper);
}
+ /**
+ * Perform a breadth first search of this graph, starting at v. The
+ * vist may be cut short if visitor throws an exception during
+ * a vist callback.
+ *
+ * @param v - the search starting point
+ * @param visitor - the vistor whose vist method is called prior
+ * to visting a vertex.
+ * @throws Exception if vistor.visit throws an exception
+ */
public <E extends Exception> void breadthFirstSearch(Vertex<T> v, VisitorEX<T, E> visitor)
throws E
{
@@ -270,7 +336,12 @@
}
}
- // Find Spanning Tree
+ /**
+ * Find the spanning tree using a DFS starting from v.
+ * @param v - the vertex to start the search from
+ * @param visitor - visitor invoked after each vertex
+ * is visited and an edge is added to the tree.
+ */
public void dfsSpanningTree(Vertex<T> v, DFSVisitor<T> visitor)
{
v.visit();
@@ -290,14 +361,58 @@
}
}
+ /**
+ * Search the verticies for one with name.
+ *
+ * @param name - the vertex name
+ * @return the first vertex with a matching name, null if no
+ * matches are found
+ */
+ public Vertex<T> findVertexByName(String name)
+ {
+ Vertex<T> match = null;
+ for(Vertex<T> v : verticies)
+ {
+ if( name.equals(v.getName()) )
+ {
+ match = v;
+ break;
+ }
+ }
+ return match;
+ }
- /*
- In order to detect cycles, we use a modified depth first search called a
- colored DFS. All nodes are initially marked white. When a node is
- encountered, it is marked grey, and when its descendants are completely
- visited, it is marked black. If a grey node is ever encountered, then there
- is a cycle.
- */
+ /**
+ * Search the verticies for one with data.
+ *
+ * @param data - the vertex data to match
+ * @param compare - the comparator to perform the match
+ * @return the first vertex with a matching data, null if no
+ * matches are found
+ */
+ public Vertex<T> findVertexByData(T data, Comparator<T> compare)
+ {
+ Vertex<T> match = null;
+ for(Vertex<T> v : verticies)
+ {
+ if( compare.compare(data, v.getData()) == 0 )
+ {
+ match = v;
+ break;
+ }
+ }
+ return match;
+ }
+
+ /** Search the graph for cycles. In order to detect cycles, we use
+ * a modified depth first search called a colored DFS. All nodes are
+ * initially marked white. When a node is encountered, it is marked
+ * grey, and when its descendants are completely visited, it is
+ * marked black. If a grey node is ever encountered, then there is
+ * a cycle.
+ * @return the edges that form cycles in the graph. The array will
+ * be empty if there are no cycles.
+ */
public Edge<T>[] findCycles()
{
ArrayList<Edge<T>> cycleEdges = new ArrayList<Edge<T>>();
@@ -312,6 +427,7 @@
Vertex<T> v = getVertex(n);
visit(v, cycleEdges);
}
+
Edge<T>[] cycles = new Edge[cycleEdges.size()];
cycleEdges.toArray(cycles);
return cycles;
Modified: common-core/trunk/src/main/java/org/jboss/util/graph/Vertex.java
===================================================================
--- common-core/trunk/src/main/java/org/jboss/util/graph/Vertex.java 2006-12-13 02:07:44 UTC (rev 2217)
+++ common-core/trunk/src/main/java/org/jboss/util/graph/Vertex.java 2006-12-13 03:34:58 UTC (rev 2218)
@@ -22,8 +22,11 @@
package org.jboss.util.graph;
import java.util.ArrayList;
+import java.util.List;
/**
+ * A named graph vertex with optional data.
+ *
* @author Scott.Stark at jboss.org
* @version $Revision$
*/
@@ -44,13 +47,18 @@
this(null, null);
}
/**
- * Create a vertex with the given name
+ * Create a vertex with the given name and no data
* @param n
*/
public Vertex(String n)
{
- this(null, null);
+ this(n, null);
}
+ /**
+ * Create a Vertex with name n and given data
+ * @param n - name of vertex
+ * @param data - data associated with vertex
+ */
public Vertex(String n, T data)
{
incomingEdges = new ArrayList<Edge<T>>();
@@ -60,13 +68,16 @@
this.data = data;
}
+ /**
+ * @return the possibly null name of the vertex
+ */
public String getName()
{
return name;
}
/**
- * @return Returns the data.
+ * @return the possibly null data of the vertex
*/
public T getData()
{
@@ -81,8 +92,12 @@
}
/**
+ * Add an edge to the vertex. If edge.from is this vertex, its an
+ * outgoing edge. If edge.to is this vertex, its an incoming
+ * edge. If neither from or to is this vertex, the edge is
+ * not added.
*
- * @param e
+ * @param e - the edge to add
* @return true if the edge was added, false otherwise
*/
public boolean addEdge(Edge<T> e)
@@ -95,10 +110,35 @@
return false;
return true;
}
-
+
/**
+ * Add an outgoing edge ending at to.
*
- * @param e
+ * @param to - the destination vertex
+ * @param cost the edge cost
+ */
+ public void addOutgoingEdge(Vertex<T> to, int cost)
+ {
+ Edge<T> out = new Edge<T>(this, to, cost);
+ outgoingEdges.add(out);
+ }
+ /**
+ * Add an incoming edge starting at from
+ *
+ * @param from - the starting vertex
+ * @param cost the edge cost
+ */
+ public void addIncomingEdge(Vertex<T> from, int cost)
+ {
+ Edge<T> out = new Edge<T>(this, from, cost);
+ incomingEdges.add(out);
+ }
+
+ /**
+ * Check the vertex for either an incoming or outgoing edge
+ * mathcing e.
+ *
+ * @param e the edge to check
* @return
*/
public boolean hasEdge(Edge<T> e)
@@ -111,7 +151,13 @@
return false;
}
- // Remove an edge from this vertex
+ /**
+ * Remove an edge from this vertex
+ *
+ * @param e - the edge to remove
+ * @return true if the edge was removed, false if the
+ * edge was not connected to this vertex
+ */
public boolean remove(Edge<T> e)
{
if (e.getFrom() == this)
@@ -122,54 +168,103 @@
return false;
return true;
}
-
+
+ /**
+ *
+ * @return the count of incoming edges
+ */
public int getIncomingEdgeCount()
{
return incomingEdges.size();
}
-
+
+ /**
+ * Get the ith incoming edge
+ * @param i the index into incoming edges
+ * @return ith incoming edge
+ */
public Edge<T> getIncomingEdge(int i)
{
Edge<T> e = incomingEdges.get(i);
return e;
}
+ /**
+ * Get the incoming edges
+ * @return incoming edge list
+ */
+ public List getIncomingEdges()
+ {
+ return this.incomingEdges;
+ }
+
+ /**
+ *
+ * @return the count of incoming edges
+ */
public int getOutgoingEdgeCount()
{
return outgoingEdges.size();
}
+ /**
+ * Get the ith outgoing edge
+ * @param i the index into outgoing edges
+ * @return ith outgoing edge
+ */
public Edge<T> getOutgoingEdge(int i)
{
Edge<T> e = outgoingEdges.get(i);
return e;
}
-
- // Do we have an edge that goes to dest?
+
+ /**
+ * Get the outgoing edges
+ * @return outgoing edge list
+ */
+ public List getOutgoingEdges()
+ {
+ return this.outgoingEdges;
+ }
+
+ /**
+ * Search the outgoing edges looking for an edge whose's
+ * edge.to == dest.
+ * @return the outgoing edge going to dest if one exists,
+ * null otherwise.
+ */
public Edge<T> findEdge(Vertex<T> dest)
{
- for (int i = 0; i < incomingEdges.size(); i++)
+ for (int i = 0; i < outgoingEdges.size(); i++)
{
- Edge<T> e = incomingEdges.get(i);
+ Edge<T> e = outgoingEdges.get(i);
if (e.getTo() == dest)
return e;
}
return null;
}
- // Do we have the edge e? Only looks at sucessors
+ /**
+ * Search the outgoing edges for a match to e.
+ *
+ * @param e - the edge to check
+ * @return e if its a member of the outgoing edges, null
+ * otherwise.
+ */
public Edge<T> findEdge(Edge<T> e)
{
- if (incomingEdges.contains(e))
+ if (outgoingEdges.contains(e))
return e;
else
return null;
- }
+ }
/**
- * What is the cost to this vertex.
- * Return Integer.MAX_VALUE if we have no edge to dest
- * @param dest
- * @return
+ * What is the cost from this vertext to the dest vertex.
+ *
+ * @param dest - the destination vertex.
+ * @return Return Integer.MAX_VALUE if we have no edge to dest,
+ * 0 if dest is this vertex, the cost of the outgoing edge
+ * otherwise.
*/
public int cost(Vertex<T> dest)
{
@@ -177,52 +272,87 @@
return 0;
Edge<T> e = findEdge(dest);
+ int cost = Integer.MAX_VALUE;
if (e != null)
- return e.getCost();
- else
- return Integer.MAX_VALUE;
+ cost = e.getCost();
+ return cost;
}
-
- // Do we have an edge to dest?
+
+ /**
+ * Is there an outgoing edge ending at dest.
+ *
+ * @param dest - the vertex to check
+ * @return true if there is an outgoing edge ending
+ * at vertex, false otherwise.
+ */
public boolean hasEdge(Vertex<T> dest)
{
return (findEdge(dest) != null);
}
- // Have we been here before?
+ /**
+ * Has this vertex been marked during a visit
+ * @return true is visit has been called
+ */
public boolean visited()
{
return mark;
}
-
+
+ /**
+ * Set the vertex mark flag.
+ *
+ */
public void mark()
{
mark = true;
}
+ /**
+ * Set the mark state to state.
+ *
+ * @param state
+ */
public void setMarkState(int state)
{
markState = state;
}
+ /**
+ * Get the mark state value.
+ * @return
+ */
public int getMarkState()
{
return markState;
}
+ /**
+ * Visit the vertex and set the mark flag to true.
+ *
+ */
public void visit()
{
mark();
}
-
- // Clear the mark
+
+ /**
+ * Clear the visited mark flag.
+ *
+ */
public void clearMark()
{
mark = false;
}
-
+
+ /**
+ * @return a string form of the vertex with in and out
+ * edges.
+ */
public String toString()
{
StringBuffer tmp = new StringBuffer("Vertex(");
tmp.append(name);
+ tmp.append(", data=");
+ tmp.append(data);
tmp.append("), in:[");
for (int i = 0; i < incomingEdges.size(); i++)
{
Modified: common-core/trunk/src/main/java/org/jboss/util/graph/Visitor.java
===================================================================
--- common-core/trunk/src/main/java/org/jboss/util/graph/Visitor.java 2006-12-13 02:07:44 UTC (rev 2217)
+++ common-core/trunk/src/main/java/org/jboss/util/graph/Visitor.java 2006-12-13 03:34:58 UTC (rev 2218)
@@ -23,7 +23,6 @@
/**
* A graph visitor interface.
- * TODO, the spanning tree visitor method should really be a separate interface
*
* @author Scott.Stark at jboss.org
* @version $Revision$
Modified: common-core/trunk/src/main/java/org/jboss/util/graph/VisitorEX.java
===================================================================
--- common-core/trunk/src/main/java/org/jboss/util/graph/VisitorEX.java 2006-12-13 02:07:44 UTC (rev 2217)
+++ common-core/trunk/src/main/java/org/jboss/util/graph/VisitorEX.java 2006-12-13 03:34:58 UTC (rev 2218)
@@ -22,8 +22,8 @@
package org.jboss.util.graph;
/**
- * A graph visitor interface.
- * TODO, the spanning tree visitor method should really be a separate interface
+ * A graph visitor interface that can throw an exception during
+ * a visit callback.
*
* @author Scott.Stark at jboss.org
* @version $Revision$
More information about the jboss-svn-commits
mailing list