y.view.hierarchy
Class HierarchyManager

java.lang.Object
  y.view.hierarchy.HierarchyManager

public class HierarchyManager
extends Object

This class manages a hierarchy of grouped nodes and nested graphs. A graph hierarchy always contains a top level graph called the root graph. Each graph within the hierarchy can have an arbitrary number of nodes. These nodes can either be normal nodes, group nodes or so called folder nodes. Folder nodes serve as proxy elements to access graphs in a lower hierarchy level. The graph that is accessible from a folder node is called the inner graph of that node. A folder node is also called anchor node, since it serves to attach an inner graph to a hierarchically higher graph. The hierarchically higher graph is called the parent graph of the inner graph.

Like a folder node, a group node can also contain other nodes that conceptually belong to a lower hierarchy level. Unlike a folder node, the child nodes of a group nodes belong to the same graph as the group node itself.

A hierarchy manager allows to create and remove new group and folder nodes within a graph. It allows to move part of a graph a level up the hierarchy or a level down the hierarchy. It also allows to group and ungroup nodes.

When moving parts of a graph to another hierarchy level it is possible that the end points of edges come to lie in different graphs. The hierarchy manager will automatically redirect such edges in a clever and consistent way. An edge will always be part of the graph that is the hierarchically highest common ancestor of the graphs that contain the original source and target nodes of the edge. In case the original end point of the edge is not in the same graph, then the folder node hosting this end point will be chosen as local end point of that edge. Such a redirected edge is called an inter-edge, since it actually connects nodes in different graphs. The original end points of an inter-edge are called real node and real target.

A hierarchy manager fires high level events that signal the change of the hierarchic structure and the change of the node elements within the hierarchy. Clients interested in this information must implement the HierarchyListener interface and register to the hierarchy manager. Listeners will be informed by receiving messages of type HierarchyEvent whenever the hierarchy changes.

Note that hierarchy events of type HierarchyEvent.NODE_CHANGED will not be fired by the HierarchyManager itself since it does not know enough about specific nodes. In order to receive NODE_CHANGED hierarchy events it is necessary to add a Graph-, or Graph2DListener to the root graph of the hierarchy that translates the incoming events to HierarchyEvents. Class DefaultNodeChangePropagator for example, serves this purpose.

The hierarchy manager is also responsible for creating new nodes and graphs when the hierarchy grows. A hierarchy manager uses an aggregated factory of type GraphFactory to create these elements. Clients can provide their own factories to customize graph object creation.

Nested Class Summary

static interface

HierarchyManager.NodeVisitor Callback interface that allows to perform some action when nodes within the hierarchy get visited in a certain order.

Constructor Summary

HierarchyManager(Graph root)
Creates a new hierarchy manager that initially manages a flat graph hierarchy whose root graph will be the given graph.

HierarchyManager(Graph root, GraphFactory factory)
Creates a new hierarchy manager that initially manages a flat graph hierarchy whose root graph will be the given graph.

Method Summary

void	addHierarchyListener(HierarchyListener listener) Adds a HierarchyListener to this HierarchyManager;
void	closeGroup(Node groupNode) Convenience method that performs all necessary steps to convert a group node to a folder node.
boolean	contains(Graph graph) Returns whether or not the given graph is part of this graph hierarchy
static boolean	containsGroupNodes(Graph graph) Whether or not the given graph contains any group nodes.
boolean	containsGroups() Queries the hierarchy if it contains any group nodes.
void	convertToFolderNode(Node v) Converts a group node or a normal node to a folder node.
void	convertToFolderNode(Node v, Graph innerGraph) Like convertToFolderNode(y.base.Node) with the additional option to specify the inner graph to be used by the folder node.
void	convertToGroupNode(Node v) Converts a folder node or a normal node to a group node.
void	convertToInterEdge(Edge e, Node realSource, Node realTarget) Converts a normal edge to an inter-edge.
void	convertToNormalEdge(Edge e) Converts an inter-edge to a normal edge.
void	convertToNormalNode(Node v) Converts a group or folder node to a normal node.
Edge	createEdge(Node v, Node w) Convenience method that creates an edge in a nested graph hierarchy.
Node	createFolderNode(Graph parentGraph) Similar to createFolderNode(Node).
Node	createFolderNode(Node parent) Returns a newly created folder node that will be created as a child node of the given folder or group node.
Node	createGroupNode(Graph graph) Similar to createGroupNode(Node).
Node	createGroupNode(Node parent) Returns a newly created group node that will be created as a child node of the given group or folder node.
void	dispose() Disposes this HierarchyManager instance.
protected void	fireHierarchyEvent(HierarchyEvent e) Propagates the given hierarchy event to all registered hierarchy listeners.
void	foldSubgraph(NodeList subNodes, Node folderNode) Moves part of a graph into a folder node.
Node	getAnchorNode(Graph graph) Returns the anchor node of the given graph.
NodeCursor	getChildren(Node node) Returns all direct child nodes of a group or folder node.
NodeList	getFolderNodes(Graph rootGraph, boolean recursive) Returns all folder nodes that are either contained in given graph or contained in the given graph or one of its graph descendants.
Object[]	getFolderPath(Object item) Returns the hierarchy of folder nodes that lie above the given item within this hierarchy.
GraphFactory	getGraphFactory() Returns the registered graph factory of this hierarchy manager.
DataProvider	getGroupNodeDataProvider() Returns a data provider the provides boolean values for each node indicating whether or not the given node is a group node.
Graph	getInnerGraph(Node folderNode) Returns the inner graph accessible from the given folder node.
static HierarchyManager	getInstance(Graph graph) This static method returns the hierarchy manager instance that is responsible for managing the given graph.
InterEdgeConfigurator	getInterEdgeConfigurator() Returns the InterEdgeConfigurator used by this class.
int	getLocalGroupDepth(Node node) Returns the hierarchy level of the given node within its graph.
Graph	getNearestCommonAncestor(Graph g1, Graph g2) Finds the graph that is the nearest common ancestor of two graphs in the hierarchy.
Node	getNearestCommonAncestor(NodeList subNodes) Finds the group or folder node that is the nearest common ancestor of all given nodes.
DataProvider	getNodeIdDataProvider() Returns a data provider the provides a unique ID for each node within the hierarchy.
Graph	getParentGraph(Graph graph) Returns the parent graph of the given graph within this hierarchy.
Node	getParentNode(Node node) Returns the parent node of the given node.
DataProvider	getParentNodeIdDataProvider() Returns a data provider the provides the parent ID for each node within the hierarchy.
Node	getRealSource(Edge e) Returns the real source node associated with the given inter-edge.
Node	getRealTarget(Edge e) Returns the real target node associated with the given inter-edge.
Node	getRepresentative(Node v, Graph inGraph) Convenience method that returns the Node representing a Node in another Graph if the node lies in that graph is an ancestor of the node.
Graph	getRootGraph() Returns the root graph of this hierarchy.
Object[]	getTreePath(Object item) Returns the hierarchy of group and folder nodes that lie above the given item within this hierarchy.
Object[]	getTreePath(Object item, boolean includeItem) Like getTreePath(Object) with the additional option to include the given item as the last element of the path.
void	groupSubgraph(NodeList subNodes, Node groupNode) Assigns the given nodes to the given group node.
boolean	isAncestor(Node presumedAncestor, Node node) Queries the hierarchy if a given node is an ancestor of another node in the hierarchy.
boolean	isFolderNode(Node v) Returns whether or not the given node is a folder node.
boolean	isGroupNode(Node v) Returns whether or not the given node is a group node.
boolean	isInterEdge(Edge e) Returns whether or not the given edge is an inter-edge.
boolean	isNormalNode(Node v) Returns whether or not the given node is a normal node, i.e., neither group nor folder node.
boolean	isRootGraph(Graph graph) Returns whether or not the given graph is the root graph of this hierarchy.
void	moveToFirst(Node childNode) Makes the given node the first child of its parent.
void	moveToLast(Node childNode) Makes the given node the last child of its parent.
void	openFolder(Node folderNode) Convenience method that performs all necessary steps to convert a folder node to a group node.
Iterator	postTraversal() Post-traverse all nodes within the hierarchy.
Iterator	postTraversal(Node rootNode) Post-traverse all nodes within the hierarchy that are descendants of the given group or folder node.
void	postTraverse(HierarchyManager.NodeVisitor visitor) Post-traverse all nodes within the hierarchy.
void	postTraverse(Node rootNode, HierarchyManager.NodeVisitor visitor) Post-traverse all nodes within the hierarchy, that are descendants of the given group or folder node.
Iterator	preTraversal() Pre-traverse all nodes within the hierarchy.
Iterator	preTraversal(Node rootNode) Pre-traverse all nodes within the hierarchy that are descendants of the given group or folder node.
void	preTraverse(HierarchyManager.NodeVisitor visitor) Pre-traverse all nodes within the hierarchy.
void	preTraverse(Node rootNode, HierarchyManager.NodeVisitor visitor) Pre-traverse all nodes within the hierarchy, that are descendants of the given group or folder node.
void	removeFolderNode(Node folderNode) Removes the given node from the graph if it is a folder node.
void	removeGroupNode(Node groupNode) Removes the given group node and all of its descendants within the group node's graph.
void	removeHierarchyListener(HierarchyListener listener) Removes the given HierarchyListener from the list of registered listeners of this HierarchyManager.
void	setGraphFactory(GraphFactory factory) Sets the graph factory used by this manager to create new nodes and graphs.
void	setInterEdgeConfigurator(InterEdgeConfigurator interEdgeConfigurator) Sets the InterEdgeConfigurator for this class.
void	setParentNode(NodeList nodeList, Node parentNode) Assigns the nodes contained in nodeList to a group or folder that is represented by the given parentNode.
void	setParentNode(Node v, Node parentNode) Assigns v to a group or folder that is represented by the given parent node.
void	unfoldSubgraph(Graph innerGraph, NodeList subNodes) Moves part of a nested graph up the hierarchy to the parent graph.
void	ungroupSubgraph(NodeList subNodes) Convenience method that moves all given nodes a hierarchy level up, if possible.

Methods inherited from class java.lang.Object

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

Constructor Detail

HierarchyManager

public HierarchyManager(Graph root)

Creates a new hierarchy manager that initially manages a flat graph hierarchy whose root graph will be the given graph.

See Also:

HierarchyManager(Graph, GraphFactory)

Precondition:

the root must be initially empty Graph factory DefaultHierarchyGraphFactory is used by default.

HierarchyManager

public HierarchyManager(Graph root,
                        GraphFactory factory)

Creates a new hierarchy manager that initially manages a flat graph hierarchy whose root graph will be the given graph.

The given graph factory is used by this manager to create new nodes and graphs. The graph factory is responsible for creating the right kind of node and graph elements within this hierarchy. The factory is also responsible for propagating registered listeners from the parent graph to the newly generated graphs.

The hierarchy manager passes certain hints to the registered graph factory. If the hint for node creation is of type Graph then the created node will be a folder node whose inner graph is represented by the hint. The hint for graph creation is always the parent graph of the newly created graph.

By default a factory of type DefaultHierarchyGraphFactory is set.

Method Detail

getInstance

public static HierarchyManager getInstance(Graph graph)

This static method returns the hierarchy manager instance that is responsible for managing the given graph.

Parameters:

graph - a graph whose associated hierarchy manager is being sought.

Returns:

the hierarchy manager associated with the given graph. Returns null in case the given graph is not part of a hierarchy.

dispose

public void dispose()

Disposes this HierarchyManager instance. To free resources, this method should be called after a HierarchyManager instance is not needed anymore.

createFolderNode

public Node createFolderNode(Node parent)

Returns a newly created folder node that will be created as a child node of the given folder or group node. The registered GraphFactory is responsible for both the creation of the new inner graph accessible by the folder node and the folder node itself.

Emits a HierarchyEvents of type HierarchyEvent.PRE_NODE_STATE_CHANGE, and HierarchyEvent.NODE_STATE_CHANGED.

Parameters:

parent - the node that represents the graph in which to create the folder node.

Returns:

the newly created folder node

createFolderNode

public Node createFolderNode(Graph parentGraph)

Similar to createFolderNode(Node). The newly created folder node will be created as a child node of getAnchorNode(parentGraph)).

removeFolderNode

public void removeFolderNode(Node folderNode)

Removes the given node from the graph if it is a folder node. Note: Since the inner graph of the folded node is already temporarily removed from the graph, calling this method is identical to calling Graph.removeNode(y.base.Node) on the given folder node.

Parameters:

folderNode - the folder node that shall be removed.

createGroupNode

public Node createGroupNode(Node parent)

Returns a newly created group node that will be created as a child node of the given group or folder node. The registered GraphFactory is responsible for the creation and configuration of the group node.

Emits a HierarchyEvent of type HierarchyEvent.PRE_NODE_STATE_CHANGE and HierarchyEvent.NODE_STATE_CHANGED.

Parameters:

parent - the group or folder node that will be the parent of the newly created node.

Returns:

the newly created group node

removeGroupNode

public void removeGroupNode(Node groupNode)

Removes the given group node and all of its descendants within the group node's graph.

Parameters:

groupNode - the group node that shall be removed.

createGroupNode

public Node createGroupNode(Graph graph)

Similar to createGroupNode(Node). The newly created group node will be created as a child node of getAnchorNode(parentGraph)).

convertToGroupNode

public void convertToGroupNode(Node v)

Converts a folder node or a normal node to a group node.

Emits HierarchyEvents of type HierarchyEvent.PRE_NODE_STATE_CHANGE and HierarchyEvent.NODE_STATE_CHANGED.

Parameters:

v - a folder node or a normal node that should be converted to a group node

createEdge

public Edge createEdge(Node v,
                       Node w)

Convenience method that creates an edge in a nested graph hierarchy. Nodes v and w need not reside in the same graph, but must have a common ancestor only. In the case where they don't lie in the same graph an inter-edge is automatically created.
Note that the resulting edge need not necessarily be in any of the two graphs where the nodes reside, nor does the edge's source need to be v or the target be w.

Parameters:

v - the first or source node

w - the second or target node

Returns:

the edge created between the representative nodes in the common ancestor graph

getRepresentative

public Node getRepresentative(Node v,
                              Graph inGraph)

Convenience method that returns the Node representing a Node in another Graph if the node lies in that graph is an ancestor of the node.

Parameters:

v - the node whose representative will be returned

inGraph - the graph for which an representative is sought

Returns:

a node that resides in inGraph and is either v itself or an ancestor folder node of v

convertToFolderNode

public void convertToFolderNode(Node v)

Converts a group node or a normal node to a folder node. A newly created graph will be assigned as inner graph of the node.

Emits HierarchyEvents of type HierarchyEvent.PRE_NODE_STATE_CHANGE and HierarchyEvent.NODE_STATE_CHANGED.

Parameters:

v - a group node or a normal node that should be converted to a folder node

convertToFolderNode

public void convertToFolderNode(Node v,
                                Graph innerGraph)

Like convertToFolderNode(y.base.Node) with the additional option to specify the inner graph to be used by the folder node.

closeGroup

public void closeGroup(Node groupNode)

Convenience method that performs all necessary steps to convert a group node to a folder node. The children contained in the group node will be automatically transfered to the inner graph of the folder node.

openFolder

public void openFolder(Node folderNode)

Convenience method that performs all necessary steps to convert a folder node to a group node. The children contained in the inner graph of the folder node will be automatically transfered to the target group node.

convertToNormalNode

public void convertToNormalNode(Node v)

Converts a group or folder node to a normal node. The group or folder node may not contain any children when this method gets called.

convertToInterEdge

public void convertToInterEdge(Edge e,
                               Node realSource,
                               Node realTarget)

Converts a normal edge to an inter-edge. The inter-edge will be setup to have the given nodes as it's original end points.

The specified real source node must be either identical with the source node of the given edge or the real source node must be contained within the graph hierarchy subtree reachable from the source node of the given edge. The same applies to the given real target node.

The given edge must be a normal edge.

Parameters:

e - the edge to be converted to an inter-edge

realSource - the real source node associated with the inter-edge

realTarget - the real target node associated with the inter-edge

convertToNormalEdge

public void convertToNormalEdge(Edge e)

Converts an inter-edge to a normal edge.

Parameters:

e - the edge to be converted to a normal edge

setGraphFactory

public void setGraphFactory(GraphFactory factory)

Sets the graph factory used by this manager to create new nodes and graphs. The graph factory is responsible for creating the right kind of node and graph elements within this hierarchy. The factory is also responsible for registering graph listeners to the newly generated graphs.

A hierarchy manager passes certain hints to the registered graph factory. If the hint for node creation is of type Graph then the created node will be a folder node whose inner graph is represented by the hint. The hint for graph creation is always the parent graph of the newly created graph.

By default a factory of type DefaultHierarchyGraphFactory is set.

getGraphFactory

public GraphFactory getGraphFactory()

Returns the registered graph factory of this hierarchy manager.

See Also:

setGraphFactory(GraphFactory)

getInterEdgeConfigurator

public InterEdgeConfigurator getInterEdgeConfigurator()

Returns the InterEdgeConfigurator used by this class.

setInterEdgeConfigurator

public void setInterEdgeConfigurator(InterEdgeConfigurator interEdgeConfigurator)

Sets the InterEdgeConfigurator for this class. By default an instance of DefaultInterEdgeConfigurator is set.

preTraverse

public void preTraverse(HierarchyManager.NodeVisitor visitor)

Pre-traverse all nodes within the hierarchy. This method visits the children of a node after its parent has been visited. Also, the children of a node will be visited from first to last child.

preTraverse

public void preTraverse(Node rootNode,
                        HierarchyManager.NodeVisitor visitor)

Pre-traverse all nodes within the hierarchy, that are descendants of the given group or folder node. This method visits the children of a node after its parent has been visited. Also, the children of a node will be visited from first to last child.

postTraverse

public void postTraverse(HierarchyManager.NodeVisitor visitor)

Post-traverse all nodes within the hierarchy. This method visits a node after all of its descendant nodes have been visited. Also, the children of a node will be visited from last to first child.

postTraverse

public void postTraverse(Node rootNode,
                         HierarchyManager.NodeVisitor visitor)

Post-traverse all nodes within the hierarchy, that are descendants of the given group or folder node. This method visits a node after all of its descendant nodes have been visited. Also, the children of a node will be visited from last to first child.

preTraversal

public Iterator preTraversal()

Pre-traverse all nodes within the hierarchy. The Iterator created by this method visits the descendants of a node only after the node has been visited. Also, the children of a node will be visited from first to last child.

preTraversal

public Iterator preTraversal(Node rootNode)

Pre-traverse all nodes within the hierarchy that are descendants of the given group or folder node. The Iterator created by this method visits the descendants of a node only after the node has been visited. Also, the children of a node will be visited from first to last child.

postTraversal

public Iterator postTraversal()

Post-traverse all nodes within the hierarchy. The Iterator created by this method visits a node only after all of its descendant nodes have been visited. Also, the children of a node will be visited from last to first child.

postTraversal

public Iterator postTraversal(Node rootNode)

Post-traverse all nodes within the hierarchy that are descendants of the given group or folder node. The Iterator created by this method visits a node only after all of its descendant nodes have been visited. Also, the children of a node will be visited from last to first child.

getNodeIdDataProvider

public DataProvider getNodeIdDataProvider()

Returns a data provider the provides a unique ID for each node within the hierarchy.

getParentNodeIdDataProvider

public DataProvider getParentNodeIdDataProvider()

Returns a data provider the provides the parent ID for each node within the hierarchy. The following equality will hold:

 getNodeIdDataProvider().get(getParentNode(v)) == getParentNodeDataProvider().get(v)
 

See Also:

getNodeIdDataProvider()

getGroupNodeDataProvider

public DataProvider getGroupNodeDataProvider()

Returns a data provider the provides boolean values for each node indicating whether or not the given node is a group node. The following equality will hold:

 isGroupNode(v) == getGroupNodeDataProvider().getBool(v)
 

containsGroupNodes

public static boolean containsGroupNodes(Graph graph)

Whether or not the given graph contains any group nodes.

getRealSource

public Node getRealSource(Edge e)

Returns the real source node associated with the given inter-edge.

Parameters:

e - the inter-edge for which to return the real source node

Precondition:

isInterEdge(graph,e)

getRealTarget

public Node getRealTarget(Edge e)

Returns the real target node associated with the given inter-edge.

Parameters:

e - the inter-edge for which to return the real target node

Precondition:

isInterEdge(graph,e)

contains

public boolean contains(Graph graph)

Returns whether or not the given graph is part of this graph hierarchy

isInterEdge

public boolean isInterEdge(Edge e)

Returns whether or not the given edge is an inter-edge.

isFolderNode

public boolean isFolderNode(Node v)

Returns whether or not the given node is a folder node.

isGroupNode

public boolean isGroupNode(Node v)

Returns whether or not the given node is a group node.

isNormalNode

public boolean isNormalNode(Node v)

Returns whether or not the given node is a normal node, i.e., neither group nor folder node.

containsGroups

public boolean containsGroups()

Queries the hierarchy if it contains any group nodes.

getInnerGraph

public Graph getInnerGraph(Node folderNode)

Returns the inner graph accessible from the given folder node.

Parameters:

folderNode - the anchor node.

Returns:

the inner graph accessible from folderNode

Precondition:

isFolderNode(folderNode)

Postcondition:

getAnchorNode(getInnerGraph(parent,node)) == node

getAnchorNode

public Node getAnchorNode(Graph graph)

Returns the anchor node of the given graph. If the given graph is the root graph of this hierarchy then there is no anchor node and null gets returned. Otherwise a folder node whose inner graph is the given graph will be returned.

Precondition:

!isRootGraph(graph)

Postcondition:

getInnerGraph(getParentGraph(graph), getAnchorNode(graph)) == graph

getParentNode

public Node getParentNode(Node node)

Returns the parent node of the given node. The parent node can either be a folder node or a group node. The method returns null if the given node has no parent node. In such a case the node belongs to the root graph.

isAncestor

public boolean isAncestor(Node presumedAncestor,
                          Node node)

Queries the hierarchy if a given node is an ancestor of another node in the hierarchy.

Parameters:

presumedAncestor - the presumed ancestor of node

node - the presumed descendant of presumedAncestor

getParentGraph

public Graph getParentGraph(Graph graph)

Returns the parent graph of the given graph within this hierarchy. The parent graph is the graph containing the anchor node of the given graph.

getRootGraph

public Graph getRootGraph()

Returns the root graph of this hierarchy.

isRootGraph

public boolean isRootGraph(Graph graph)

Returns whether or not the given graph is the root graph of this hierarchy.

getFolderPath

public Object[] getFolderPath(Object item)

Returns the hierarchy of folder nodes that lie above the given item within this hierarchy. The returned folder path is the folder node hierarchy traversed from the root node down to the given item.

Parameters:

item - either a graph within this hierarchy or a node contained in such a graph.

Returns:

the folder node path. The first item of the returned array is always the root graph of this hierarchy. The elements to follow are all folder nodes within this hierarchy that lie on the way down to the given item. The given item itself will not be part of the folder path, except it is the root graph itself.

getTreePath

public Object[] getTreePath(Object item)

Returns the hierarchy of group and folder nodes that lie above the given item within this hierarchy. The returned folder path is the group and folder node hierarchy traversed from the root node down to the given item.

Parameters:

item - either a graph within this hierarchy or a node contained in such a graph.

Returns:

the tree path. The first item of the returned array is always the root graph of this hierarchy. The elements to follow are all group or folder nodes within this hierarchy that lie on the way down to the given item. The given item itself will not be part of the folder path, except it is the root graph itself.

getTreePath

public Object[] getTreePath(Object item,
                            boolean includeItem)

Like getTreePath(Object) with the additional option to include the given item as the last element of the path.

Parameters:

includeItem - whether or not to include the given item as the last element of the path.

getNearestCommonAncestor

public Node getNearestCommonAncestor(NodeList subNodes)

Finds the group or folder node that is the nearest common ancestor of all given nodes.

Parameters:

subNodes - arbitrary nodes being part of this hierarchy.

Returns:

the group or folder node that is the nearest common ancestor of all give