gumbo.visualize.data.layout
Class GraphNodeRanking

java.lang.Object
  |
  +--gumbo.visualize.data.layout.GraphNodeRanking

public class GraphNodeRanking
extends java.lang.Object

A ranking of graph nodes by distance from one or more seed nodes in the graph. A ranking consists of none or more ranks of nodes, with each rank containing none or more nodes at the same distance for a given metric.

The nodes in a ranking constitute a set, with no nulls or duplicates. As such, each rank in a ranking is also a set. Placing a node in a ranking does not affect the topology of its graph, and a given node can be placed in more than one ranking (with the exception that GraphLayoutNode.setRanking() only allows a single ranking).

Version:
$Revision: 1.10 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Constructor Summary
GraphNodeRanking()
           
 
Method Summary
 void addNode(int rankI, GraphLayoutNode node)
          Adds a node to a rank in this ranking.
 void addNodes(int rankI, java.util.Collection nodes)
          Adds a group of nodes to a rank in this ranking.
 void addRank()
          Appends an empty rank to this ranking.
 void addRank(java.util.Collection rank)
          Appends a (possibly empty) rank to this ranking.
 void addRank(int rankI, java.util.Collection rank)
          Adds a (possibly empty) rank at the specified rank index, shifting the remaining ranks towards the tail.
 void addRanks(GraphNodeRanking ranking)
          Appends the (possibly empty) ranks of a ranking to this ranking.
 void clear()
          Clears this ranking, making the rank count zero.
 void clearRank(int rankI)
          Clears a rank, making the rank size zero.
 void clearRanks()
          Clears all ranks in this ranking.
 void compactRanks()
          Compact ranks, which removes any empty ranks from the ranking, with nodes in shifted ranks being offset.
 boolean containsNode(GraphLayoutNode node)
          Returns true if this ranking contains the specified node.
 int getNodeCount()
          Gets the number of nodes in this ranking.
 java.util.Set getNodes()
          Returns an immutable view of the nodes in this ranking.
 java.util.Set getNodes(int bgnRankI, int endRankI)
          Returns a new set containing the nodes in and between the specified ranks.
 java.util.Set getRank(GraphLayoutNode node)
          Gets an immutable view of the rank containing a gven node in this ranking.
 java.util.Set getRank(int rankI)
          Gets an immutable view of a rank in this ranking.
 int getRankCount()
          Gets the number of ranks in this ranking.
 int getRankIndex(GraphLayoutNode node)
          Gets the rank index of a node in this ranking.
 void initNodes()
          Initializes the fundamental aspects of the nodes in this ranking that are related to ranking.
 boolean isEmpty()
          Returns true if there are no nodes in this ranking, either as a result of no ranks or all the ranks are empty.
 void offsetNode(int offset, GraphLayoutNode node)
          Adds an offset to the rank of a node.
 void offsetNodes(int offset, java.util.Collection nodes)
          Adds an offset to the rank of each node in a set.
 void removeLastRank()
          Removes the last rank in the ranking, empty or not.
 void removeNode(GraphLayoutNode node)
          Removes a node from this ranking.
 void removeNodes(java.util.Collection nodes)
          Removes a group of nodes from this ranking.
 void setRank(int rankI, java.util.Collection rank)
          Sets a rank in this ranking, replacing the previous rank.
 void setRankCount(int count)
          Sets the number of ranks in this ranking.
 java.lang.String toRankingString()
          Returns a string with the ranking class on a line, the rank and node count on a line, followed by a line for each ranking rank.
static java.lang.String toRankString(java.util.Collection rank)
          Returns a string with the rank size, and each node separated by a space, with no newline.
 java.lang.String toRankString(int rankI)
          Returns a string with the rank index, rank size, and each node separated by a space, with no newline.
static java.lang.String toRankString(int rankI, java.util.Collection rank)
          Returns a string with the rank index and size, and each node separated by a space, with no newline.
 void trimTailRanks()
          Removes any empty ranks at the end of the ranking.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GraphNodeRanking

public GraphNodeRanking()
Method Detail

isEmpty

public boolean isEmpty()
Returns true if there are no nodes in this ranking, either as a result of no ranks or all the ranks are empty.


getNodes

public java.util.Set getNodes()
Returns an immutable view of the nodes in this ranking.

Returns:
Reference to an immutable view (GraphLayoutNode). Never null.

getNodes

public java.util.Set getNodes(int bgnRankI,
                              int endRankI)
Returns a new set containing the nodes in and between the specified ranks.

Parameters:
bgnRankI - Beginning rank index. Throws an exception if out of bounds.
endRankI - Ending rank index. Throws an exception if out of bounds.
Returns:
New set of nodes (GraphLayoutNode). Empty if endRankI less than bgnRankI. Never null.

clear

public void clear()
Clears this ranking, making the rank count zero.


clearRank

public void clearRank(int rankI)
Clears a rank, making the rank size zero.

Parameters:
rankI - Rank index. Throws an exception if out of bounds.

clearRanks

public void clearRanks()
Clears all ranks in this ranking. The rank count is unchanged.


setRank

public void setRank(int rankI,
                    java.util.Collection rank)
Sets a rank in this ranking, replacing the previous rank.

Parameters:
rankI - Rank index. Throws an exception if out of bounds.
rank - Value of the node rank (GraphLayoutNode). Possibly empty. Never null. Throws an exception if a node is already in this ranking.

addRank

public void addRank()
Appends an empty rank to this ranking.


addRank

public void addRank(java.util.Collection rank)
Appends a (possibly empty) rank to this ranking.

Parameters:
rank - Rank nodes (GraphLayoutNode), by value. If null or empty, an empty rank is added. Throws an exception if a node is already in this ranking.

addRank

public void addRank(int rankI,
                    java.util.Collection rank)
Adds a (possibly empty) rank at the specified rank index, shifting the remaining ranks towards the tail.


addRanks

public void addRanks(GraphNodeRanking ranking)
Appends the (possibly empty) ranks of a ranking to this ranking.

Parameters:
ranking - A node ranking, by value. Ignored if null, this ranking, or is empty. Throws an exception if a node is already in this ranking.

removeLastRank

public void removeLastRank()
Removes the last rank in the ranking, empty or not.


trimTailRanks

public void trimTailRanks()
Removes any empty ranks at the end of the ranking.


compactRanks

public void compactRanks()
Compact ranks, which removes any empty ranks from the ranking, with nodes in shifted ranks being offset.


getRank

public java.util.Set getRank(int rankI)
Gets an immutable view of a rank in this ranking.

Parameters:
rankI - Rank index. Throws an exception if out of bounds.
Returns:
Immutable view of the rank (GraphLayoutNode). Never null.

getRank

public java.util.Set getRank(GraphLayoutNode node)
Gets an immutable view of the rank containing a gven node in this ranking.

Parameters:
node - Reference to the node. Ignored if null or missing.
Returns:
Immutable view of the rank (GraphLayoutNode). Null if node not found.

getRankIndex

public int getRankIndex(GraphLayoutNode node)
Gets the rank index of a node in this ranking.

Parameters:
node - Reference to the node. Ignored if null or missing.
Returns:
Rank index. -1 if node not found.

getRankCount

public int getRankCount()
Gets the number of ranks in this ranking.

Returns:
Rank count.

setRankCount

public void setRankCount(int count)
Sets the number of ranks in this ranking. Extra tail ranks will be added or removed as needed.

Parameters:
count - New rank count.

getNodeCount

public int getNodeCount()
Gets the number of nodes in this ranking.

Returns:
Rank count.

containsNode

public boolean containsNode(GraphLayoutNode node)
Returns true if this ranking contains the specified node.

Parameters:
node - Reference to the node. returns false if null.
Returns:
True if the node was found.

addNode

public void addNode(int rankI,
                    GraphLayoutNode node)
Adds a node to a rank in this ranking. Its links are unaffected.

Parameters:
rankI - Rank index. Throws an exception if out of bounds.
node - Reference to the node. Ignored if null.
Throws:
java.lang.IllegalArgumentException - Node is already in this ranking.

removeNode

public void removeNode(GraphLayoutNode node)
Removes a node from this ranking. Its links are unaffected.

Parameters:
node - Reference to the node. Ignored if null or missing.

addNodes

public void addNodes(int rankI,
                     java.util.Collection nodes)
Adds a group of nodes to a rank in this ranking.

Parameters:
rankI - Rank index. Throws an exception if out of bounds.
nodes - Value of the nodes (GraphLayoutNode). Ignored if null. Throws an exception if a node is already in this ranking.

removeNodes

public void removeNodes(java.util.Collection nodes)
Removes a group of nodes from this ranking.

Parameters:
nodes - Value of the nodes (GraphLayoutNode). Ignored if null. Ignores missing nodes.

offsetNode

public void offsetNode(int offset,
                       GraphLayoutNode node)
Adds an offset to the rank of a node. New ranks will be added as needed.

Parameters:
offset - Rank offset. Throws an exception if a negative rank occurs.
node - Reference to the node. Ignored if missing or null.

offsetNodes

public void offsetNodes(int offset,
                        java.util.Collection nodes)
Adds an offset to the rank of each node in a set. New ranks will be added as needed.

Parameters:
offset - Rank offset. Throws an exception if a negative rank occurs.
nodes - Reference to the nodes (GraphLayoutNode). Ignored if null. Ignores missing nodes.

initNodes

public void initNodes()
Initializes the fundamental aspects of the nodes in this ranking that are related to ranking. Includes setting the before and after rank nodes.

Throws:
java.lang.IllegalStateException - A ranking node not in a rank.

toRankString

public java.lang.String toRankString(int rankI)
Returns a string with the rank index, rank size, and each node separated by a space, with no newline.

Parameters:
rankI - Rank index. Ignored if <0.
Returns:
New string. Never null.

toRankingString

public java.lang.String toRankingString()
Returns a string with the ranking class on a line, the rank and node count on a line, followed by a line for each ranking rank.

Returns:
New string. Never null.

toRankString

public static java.lang.String toRankString(int rankI,
                                            java.util.Collection rank)
Returns a string with the rank index and size, and each node separated by a space, with no newline.

Parameters:
rankI - Rank index.
rank - The rank (GraphLayoutNode). Never null.
Returns:
New string. Never null.

toRankString

public static java.lang.String toRankString(java.util.Collection rank)
Returns a string with the rank size, and each node separated by a space, with no newline.

Parameters:
rank - The rank (GraphLayoutNode). Never null.
Returns:
New string. Never null.