mapss.dif.graph.hierarchy
Class Hierarchy

java.lang.Object
  mapss.dif.graph.hierarchy.Hierarchy

Direct Known Subclasses:

DIFHierarchy

public class Hierarchy
extends java.lang.Object

Hierarchy class is a wrapper around a mocgraph.Graph object for implementing hierarchical features. These features include defining ports for connecting a graph as a subgraph and defining connections between a parent (super) graph and a child (sub) graph.

For more information about how to use this class refer to the package documentation.

Version:

$Id: Hierarchy.java 409 2007-05-13 19:47:16Z plishker $

Author:

Fuat Keceli, Shuvra S. Bhattacharyya, Ming-Yung Ko

See Also:

Graph

Field Summary

protected mocgraph.Graph	_graph Underlying graph of this hierarchy.
protected java.lang.String	_hierarchyName Name of the hierarchy.
protected Hierarchy	_parent Parent of this graph (if it is set as a sub-graph of another hierarchy).
protected PortList	_ports Ports of this hierarchy.
protected SuperNodeMap	_superNodes Maps super nodes (type: Node) to sub-graphs (type: Hierarchy).

Constructor Summary

Hierarchy(mocgraph.Graph graph)
Construct a hierarchy object with the name "_hierarchy".

Hierarchy(mocgraph.Graph graph, java.lang.String name)
Construct a hierarchy object with a name.

Method Summary

protected mocgraph.Edge	_copyEdge(mocgraph.Edge edge, mocgraph.Node source, mocgraph.Node sink) Returns a copy of the edge with the given source and sink nodes as well as adding the new edge to the underlying graph.
protected mocgraph.Graph	_graphType() Returns an empty graph of the most general type that this object can use as its backing graph.
protected mocgraph.analysis.strategy.MirrorTransformerStrategy	_mirrorGraph(mocgraph.Graph graph) Returns a mirror transformation for the backing graph, which will be used in the mirror(boolean) function.
protected void	_putSuperNode(mocgraph.Node node, Hierarchy hierarchy) Put supernode to sub-hierarchy mapping in superNodeMap without disconnecting sub-hierarchy.
protected void	_removeSuperNode(mocgraph.Node node) Remove supernode to sub-hierarchy mapping in superNodeMap without disconnecting sub-hierarchy.
void	addSuperNode(mocgraph.Node node, Hierarchy hierarchy) Converts a node to a super node.
boolean	deepFlatten() Flattens this hierarchy all the way down to its bottom.
java.util.List	deepPurge() Runs purge() deep into the bottom of this hierarchy.
void	disconnect() Disconnects this hierarchy from its super hierarchy.
void	disconnectSuperNode(mocgraph.Node node) Disconnects a sub-hierarchy from this hierarchy.
boolean	flatten() Flattens all the super nodes on this level of the hierarchy.
Hierarchy	flatten(mocgraph.Node superNode) Flattens a super node by merging its sub-graph to this graph.
mocgraph.Graph	getGraph() Returns the graph object that backs this hierarchy.
java.lang.String	getName() Returns the name of this hierarchy.
Hierarchy	getParent() Returns the hierarchy in which this hierarchy is defined as a sub-hierarchy.
PortList	getPorts() Returns the list of ports in this hierarchy.
SuperNodeMap	getSuperNodes() Returns a map of nodes that are defined as super nodes.
mocgraph.DirectedAcyclicGraph	hierarchyGraph() Returns a DAG representation of the hierarchy structure (i.e.
boolean	isDirected() Returns true if the hierarchy contains at least one directed port.
Hierarchy	mirror(boolean cloneWeights) Mirrors a hierarchy without copying the information about its parent so it can be connected to another parent.
java.util.List	purge() Checks if all super nodes in this hierarchy can be flattened.
java.lang.String	setName(java.lang.String name) Sets the name of the hierarchy to a new string.
java.lang.String	toString() Returns the basic information about this hierarchy.

Methods inherited from class java.lang.Object

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

Field Detail

_graph

protected mocgraph.Graph _graph

Underlying graph of this hierarchy.

_hierarchyName

protected java.lang.String _hierarchyName

Name of the hierarchy. Initially set to "_hierarchy".

_ports

protected PortList _ports

Ports of this hierarchy. All values are irreversible; new ports can be added any time but they cannot be changed or erased.

_superNodes

protected SuperNodeMap _superNodes

Maps super nodes (type: Node) to sub-graphs (type: Hierarchy).

_parent

protected Hierarchy _parent

Parent of this graph (if it is set as a sub-graph of another hierarchy).

Constructor Detail

Hierarchy

public Hierarchy(mocgraph.Graph graph)

Construct a hierarchy object with the name "_hierarchy".

Parameters:

graph - The graph object that backs the hierarchy.

Hierarchy

public Hierarchy(mocgraph.Graph graph,
                 java.lang.String name)

Construct a hierarchy object with a name.

Parameters:

graph - The graph object that backs the hierarchy.

name - Name of the hierarchy.

Throws:

HierarchyException - If Conventions.labelConvention(java.lang.String) returns an error.

Method Detail

addSuperNode

public void addSuperNode(mocgraph.Node node,
                         Hierarchy hierarchy)

Converts a node to a super node. If the node is already a super node or or the hierarchy has another super hierarchy, they are disconnected first.

Parameters:

node - Super node.

hierarchy - Sub-hierarchy to be associated with the node.

Throws:

HierarchyException - If HierarchyException.checkSuperNode(mapss.dif.graph.hierarchy.Hierarchy, mapss.dif.graph.hierarchy.Hierarchy) returns an exception.

CyclicHierarchyException - If a cycle is detected in the hierarchy structure. (Checked by CyclicHierarchyException.checkCycle(mapss.dif.graph.hierarchy.Hierarchy, mapss.dif.graph.hierarchy.Hierarchy))

deepFlatten

public boolean deepFlatten()

Flattens this hierarchy all the way down to its bottom. After this operation there will be no super nodes left in the hierarchy.

Returns:

True if the hierarchy has changed as a result of this operation.

Throws:

HierarchyException - If any of the individual flatten operations throw an exception.

See Also:

deepPurge()

deepPurge

public java.util.List deepPurge()

Runs purge() deep into the bottom of this hierarchy. After this operation deepFlatten() can be called with no exceptions.

Returns:

A list of sub-hierarchies that are disconnected.

disconnect

public void disconnect()

Disconnects this hierarchy from its super hierarchy. This method is the same as parent.disconnectSuperNode(node) in which node is the super node of this hierarchy. It does nothing if this hierarchy has no super hierarchy.

disconnectSuperNode

public void disconnectSuperNode(mocgraph.Node node)

Disconnects a sub-hierarchy from this hierarchy. This method is the same as child.disconnect(). It does nothing if the node is not a super node.

Parameters:

node - A super node in this hierarchy.

flatten

public boolean flatten()

Flattens all the super nodes on this level of the hierarchy. However super nodes coming from the sub hierarchies won't be flattened.

Returns:

True if the hierarchy has changed as a result of this operation.

Throws:

HierarchyException - If any of the individual flatten operations throw an exception.

See Also:

purge()

flatten

public Hierarchy flatten(mocgraph.Node superNode)

Flattens a super node by merging its sub-graph to this graph. All connections will be made as specified in the port definitions of the sub-hierarchy. Super node and its incident edges which are not connected to ports will be removed. Sub-hierarchy object is still usable but all of its super nodes are disconnected and moved to this hierarchy. Sub-hierarchy is also disconnected from this hierarchy.

Parameters:

superNode - A super node in this hierarchy.

Returns:

The hierarchy that has been flattened.

Throws:

HierarchyException - If an exception is returned by HierarchyException.checkFlatten(mapss.dif.graph.hierarchy.Hierarchy, mocgraph.Node).

getGraph

public mocgraph.Graph getGraph()

Returns the graph object that backs this hierarchy.

Returns:

Graph object that backs this hierarchy.

getName

public java.lang.String getName()

Returns the name of this hierarchy.

Returns:

Name of this hierarchy.

getParent

public Hierarchy getParent()

Returns the hierarchy in which this hierarchy is defined as a sub-hierarchy.

Returns:

Parent hierarchy. Null is there is no parent.

getPorts

public PortList getPorts()

Returns the list of ports in this hierarchy.

Returns:

The list of ports.

getSuperNodes

public SuperNodeMap getSuperNodes()

Returns a map of nodes that are defined as super nodes. Order of the nodes returned is the order they are added as super nodes.

Returns:

A map of nodes to hierarchies.

hierarchyGraph

public mocgraph.DirectedAcyclicGraph hierarchyGraph()

Returns a DAG representation of the hierarchy structure (i.e. If A is a subgraph of B there exists an edge that connects node(A) to node(B)) starting from this graph.

Returns:

DAG representation of the hierarchy structure starting from this hierarchy object. Weight of each node in the DAG is a hierarchy object.

See Also:

HierarchyToDot.hierarchyGraphToDot(mapss.dif.graph.hierarchy.Hierarchy)

isDirected

public boolean isDirected()

Returns true if the hierarchy contains at least one directed port.

Returns:

True if the hierarchy contains at least one directed port.

mirror

public Hierarchy mirror(boolean cloneWeights)

Mirrors a hierarchy without copying the information about its parent so it can be connected to another parent.

The backing graph is mirrored using MirrorTransformerStrategy. Necessary edge and node conversions are done using transformedVersionOf of the transformer object. All ports are mirrored using Port.mirror(mapss.dif.graph.hierarchy.Hierarchy, mocgraph.analysis.strategy.MirrorTransformerStrategy).

Parameters:

cloneWeights - Weights of the nodes and edges will be cloned if true.

Returns:

Mirror hierarchy.

purge

public java.util.List purge()

Checks if all super nodes in this hierarchy can be flattened. Disconnects the super nodes that cannot be flattened. After this operation flatten() can be called with no exceptions.

Returns:

A list of sub-hierarchies that are disconnected.

See Also:

HierarchyException.checkFlatten(mapss.dif.graph.hierarchy.Hierarchy, mocgraph.Node)

setName

public java.lang.String setName(java.lang.String name)

Sets the name of the hierarchy to a new string.

Parameters:

name - New name.

Returns:

The old name.

Throws:

HierarchyException - If this is a sub-hierarchy and its parent already has another hierarchy with the same name. This check is performed using SuperNodeMap.isDefined(java.lang.String).

toString

public java.lang.String toString()

Returns the basic information about this hierarchy. This information includes name, port names, sub-hierarchy names and parent name of this hierarchy.

Overrides:

toString in class java.lang.Object

Returns:

Information string of this hierarchy.

_copyEdge

protected mocgraph.Edge _copyEdge(mocgraph.Edge edge,
                                  mocgraph.Node source,
                                  mocgraph.Node sink)

Returns a copy of the edge with the given source and sink nodes as well as adding the new edge to the underlying graph. This function only copies (by reference) the weight of the edge in this implementation. If an extended version uses a different kind of graph, additional information attributed to an edge should be copied too.

Parameters:

edge - Original edge.

source - New source node.

sink - New sink node.

Returns:

The new edge.

_graphType

protected mocgraph.Graph _graphType()

Returns an empty graph of the most general type that this object can use as its backing graph.

Returns:

A graph of type Graph.

_mirrorGraph

protected mocgraph.analysis.strategy.MirrorTransformerStrategy _mirrorGraph(mocgraph.Graph graph)

Returns a mirror transformation for the backing graph, which will be used in the mirror(boolean) function. This implementation returns a MirrorTransformerStrategy object. In case that a special type of graph backs an extension of the Hierarchy class, this method can be overridden to return the transformer of that class.

Parameters:

graph - The graph to be mirrored.

Returns:

Mirror graph.

_putSuperNode

protected void _putSuperNode(mocgraph.Node node,
                             Hierarchy hierarchy)

Put supernode to sub-hierarchy mapping in superNodeMap without disconnecting sub-hierarchy. If disconnecting sub-hierarchy, the related node and related port of the outer port also removed. However, in some cases, the derived subclasses may still want to have the inter references. Be careful to use this method. In other cases, use addSuperNode(mocgraph.Node, mapss.dif.graph.hierarchy.Hierarchy) instead.

Parameters:

node - Super node.

hierarchy - Sub-hierarchy to be associated with the node.

Throws:

HierarchyException - If HierarchyException.checkSuperNode(mapss.dif.graph.hierarchy.Hierarchy, mapss.dif.graph.hierarchy.Hierarchy) returns an exception.

CyclicHierarchyException - If a cycle is detected in the hierarchy structure. (Checked by CyclicHierarchyException.checkCycle(mapss.dif.graph.hierarchy.Hierarchy, mapss.dif.graph.hierarchy.Hierarchy))

_removeSuperNode

protected void _removeSuperNode(mocgraph.Node node)

Remove supernode to sub-hierarchy mapping in superNodeMap without disconnecting sub-hierarchy. If disconnecting sub-hierarchy, the related node and related port of the outer port also removed. However, in some cases, the derived subclasses may still want to have the inter references. Be careful to use this method. In other cases, use disconnectSuperNode(mocgraph.Node) instead.

Parameters:

node - A super node in this hierarchy.