y.layout.grouping
Class Grouping

java.lang.Object
  y.layout.grouping.Grouping

All Implemented Interfaces:

GroupingKeys

public class Grouping
extends Object
implements GroupingKeys

Instances of this class can be used by algorithms to efficiently query the structure of such type of graphs. The grouping information is provided through DataProviders, whose keys are defined in the GroupingKeys interface.

Field Summary

Fields inherited from interface y.layout.grouping.GroupingKeys

GROUP_DPKEY, GROUP_NODE_INSETS_DPKEY, MINIMUM_NODE_SIZE_DPKEY, NODE_ID_DPKEY, PARENT_NODE_ID_DPKEY

Constructor Summary

Grouping(Graph graph)
Creates a new instance of Grouping.

Method Summary

protected NodeMap	createInfoMap(Graph graph) Factory method for a NodeMap
void	dispose() Disposes the data structures held by this instance.
protected void	disposeInfoMap(Graph graph, NodeMap infoMap) Factory destructor method for a NodeMap
NodeList	getChildren(Node parent) Returns the children of the given group node as a NodeList.
NodeList	getDescendants(Node parent) Returns all descendants of the given group node as a NodeList.
EdgeList	getEdgesGoingIn(Node groupNode) Convenience method that returns a list of all Edges crossing the group node boundary of the given group node in such a way, that there target is inside the group node and the source does not lie inside the group node.
EdgeList	getEdgesGoingOut(Node groupNode) Convenience method that returns a list of all Edges crossing the group node boundary of the given group node in such a way, that there target is outside the group node and the source does not lie outside the group node.
Graph	getGraph() Returns the Graph instance this object provides information for.
LayoutGraph	getLayoutGraph() Returns the LayoutGraph instance this object provides information for.
Node	getNearestCommonAncestor(Node n1, Node n2) Returns the nearest common ancestor in the hierarchy structure.
Node	getParent(Node node) Returns the parent of the given node or null if the node is at the top of the hierarchy
Node	getRepresentative(Node node, Node inGroup) Convenience method that returns a node that can be used to represent node in the group inGroup, that is either the node itself if it is an immediate child of inGroup, or a node that is a child of inGroup and an ancestor of node at the same time or null if neither of the latter applies.
Node	getRoot() Returns a node instance that can be used as a handle to the virtual root of the node hierarchy.
boolean	hasChildren(Node v) Determines if the given node is a group node with children.
protected void	init() Initializes internal data structures.
static boolean	isFlat(Graph graph) A graph is considered to be flat if it is either not grouped or there is no group node that contains child nodes present in the graph.
static boolean	isGrouped(Graph graph) A graph is considered to be grouped if the three low-level grouping data providers GroupingKeys.GROUP_DPKEY, GroupingKeys.NODE_ID_DPKEY and GroupingKeys.PARENT_NODE_ID_DPKEY are registered.
boolean	isGroupNode(Node node) Determines if the given node is a group node.
boolean	isNormalEdge(Edge e) Determines if the given Edge is a normal edge, i.e. whether it does not cross any group node boundaries.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Grouping

public Grouping(Graph graph)

Creates a new instance of Grouping. Grouping instances provide a convenient way for all kind of algorithms to traverse the node grouping hierarchy. The hierarchy is cached during the call to this constructor. It is build using the information bound to the graph using the DataProviders that are registered with the graph instance. Grouping instances hold a state that with the graph instance that should be disposed once the grouping instance is not needed anymore.

Method Detail

init

protected void init()

Initializes internal data structures. The state of the graph at the moment of this method invocation will be reflected by this instance.

getLayoutGraph

public LayoutGraph getLayoutGraph()

Returns the LayoutGraph instance this object provides information for.

This Grouping instance must have been created with a LayoutGraph

getGraph

public Graph getGraph()

Returns the Graph instance this object provides information for.

createInfoMap

protected NodeMap createInfoMap(Graph graph)

Factory method for a NodeMap

disposeInfoMap

protected void disposeInfoMap(Graph graph,
                              NodeMap infoMap)

Factory destructor method for a NodeMap

getParent

public Node getParent(Node node)

Returns the parent of the given node or null if the node is at the top of the hierarchy

getRoot

public Node getRoot()

Returns a node instance that can be used as a handle to the virtual root of the node hierarchy. This handle can be given to the getChildren() method to obtain the nodes, that are at the top level of the hierarchy. The instance is *not* part of the graph.

getChildren

public NodeList getChildren(Node parent)

Returns the children of the given group node as a NodeList.

getDescendants

public NodeList getDescendants(Node parent)

Returns all descendants of the given group node as a NodeList.

Parameters:

parent - A group node. If null is given, the graph's root is used.

Returns:

A recursively built NodeList containing all descendants of the given group node.

isGroupNode

public boolean isGroupNode(Node node)

Determines if the given node is a group node. Group nodes *may* have children. Normal nodes never have children.

hasChildren

public boolean hasChildren(Node v)

Determines if the given node is a group node with children.

isNormalEdge

public boolean isNormalEdge(Edge e)

Determines if the given Edge is a normal edge, i.e. whether it does not cross any group node boundaries.

getEdgesGoingIn

public EdgeList getEdgesGoingIn(Node groupNode)

Convenience method that returns a list of all Edges crossing the group node boundary of the given group node in such a way, that there target is inside the group node and the source does not lie inside the group node.

getEdgesGoingOut

public EdgeList getEdgesGoingOut(Node groupNode)

Convenience method that returns a list of all Edges crossing the group node boundary of the given group node in such a way, that there target is outside the group node and the source does not lie outside the group node.

getRepresentative

public Node getRepresentative(Node node,
                              Node inGroup)

Convenience method that returns a node that can be used to represent node in the group inGroup, that is either the node itself if it is an immediate child of inGroup, or a node that is a child of inGroup and an ancestor of node at the same time or null if neither of the latter applies.

Parameters:

node - the node for which a representative will be returned

inGroup - the group to which the representative should belong.

dispose

public void dispose()

Disposes the data structures held by this instance. Calling this method renders this instance useless.

isGrouped

public static boolean isGrouped(Graph graph)

A graph is considered to be grouped if the three low-level grouping data providers GroupingKeys.GROUP_DPKEY, GroupingKeys.NODE_ID_DPKEY and GroupingKeys.PARENT_NODE_ID_DPKEY are registered.

An instance of this class requires its graph to be grouped.

isFlat

public static boolean isFlat(Graph graph)

A graph is considered to be flat if it is either not grouped or there is no group node that contains child nodes present in the graph. This method determines whether a graph is flat

getNearestCommonAncestor

public Node getNearestCommonAncestor(Node n1,
                                     Node n2)

Returns the nearest common ancestor in the hierarchy structure.

This method returns the nearest ancestor of n1 and n2 that contains both n1 and n2 or it returns getRoot() if no such node exists. In the special cases of n2 being a child of n1 (or vice versa) or if n1 == n2, the parent of n1 (or n2 respectively) is returned.

Parameters:

n1 - one of the two nodes whose common ancestor is determined.

n2 - one of the two nodes whose common ancestor is determined.

Returns:

The nearest common ancestor node, or getRoot().