y.layout.hierarchic.incremental
Class HierarchicLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.hierarchic.incremental.HierarchicLayouter

All Implemented Interfaces:

Layouter

public class HierarchicLayouter
extends CanonicMultiStageLayouter

This class can be used to create hierarchical layouts of graphs. It has built-in support for incrementally adding elements to a previously calculated layout or optimizing existing elements of a previously calculated layout.

In order to customize this layout algorithm, modify the Layerer, Sequencer, PortAllocator, DrawingDistanceCalculator, and NodePlacer instances.

Use the INCREMENTAL_HINTS_DPKEY DataProvider key to associate incremental hints with the elements in the graph.
Incremental Hints can be obtained from the IncrementalHintsFactory. They are used by the algorithm to determine which elements in the graph have to be inserted/updated incrementally.

This layout algorithm respects PortConstraints, that are bound to the graph using the PortConstraintKeys.SOURCE_PORT_CONSTRAINT_KEY and PortConstraintKeys.TARGET_PORT_CONSTRAINT_KEY as well as PortConstraintKeys.SOURCE_GROUPID_KEY and PortConstraintKeys.TARGET_GROUPID_KEY DataProviders that can be used to create bus-like edge routings.

Fine-grained configuration of the layout style is supported via DataProviders that are bound to the graph using the EDGE_LAYOUT_DESCRIPTOR_DPKEY and NODE_LAYOUT_DESCRIPTOR_DPKEY DataProvider keys.
They can be used to associate NodeLayoutDescriptor and EdgeLayoutDescriptor instances with each element in the graph. These may be shared.

This algorithm sets a LabelLayoutTranslator instance as the current CanonicMultiStageLayouter.getLabelLayouter() and configures it so that the node labels are passed to by setting LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) to true.
In order to enable integrated edge labeling of this algorithm, make sure LabelLayoutTranslator is registered and edge labels are being translated and written back after the layout.

This algorithm also support swimlane style drawings. This can be enabled by associating SwimLaneDescriptor instances with the nodes in the graph using the SWIMLANE_DESCRIPTOR_DPKEY DataProvider key.

Moreover, this algorithm supports sequence constraints. These constraints can be specified using a SequenceConstraintFactory.

See Also:

IncrementalHierarchicLayouter, Layerer, Sequencer, PortAllocator, DrawingDistanceCalculator, NodePlacer

Nested Class Summary

static class

HierarchicLayouter.IncrementalHint Hint objects used internally by this layout algorithm implementation.

Field Summary

static Object	EDGE_LAYOUT_DESCRIPTOR_DPKEY DataProvider key used to retrieve EdgeLayoutDescriptor instances for each edge in the graph.
static Object	INCREMENTAL_HINTS_DPKEY DataProvider key used to retrieve incremental layout hint objects for nodes and edges that have been set using the IncrementalHintsFactory which itself can be obtained from the createIncrementalHintsFactory() method.
static Object	INCREMENTAL_NODES_DPKEY DataProvider key used to hold boolean values for each node in the graph that indicate whether the node has to be added incrementally.
static Object	LAYER_VALUE_HOLDER_DPKEY Used for publishing the final layering information.
static Object	NODE_LAYOUT_DESCRIPTOR_DPKEY DataProvider key used to retrieve NodeLayoutDescriptor instances for each node in the graph.
static Object	SEQUENCE_VALUE_HOLDER_DPKEY Used for publishing the final sequencing information.
static Object	SWIMLANE_DESCRIPTOR_DPKEY DataProvider key used to store SwimLaneDescriptor instances for each node in the graph.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

HierarchicLayouter()
Creates a new instance of HierarchicLayouter with default settings.

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Always returns true.
protected DrawingDistanceCalculator	createDrawingDistanceCalculator() Factory method that is called lazily upon first usage.
protected EdgeReverser	createEdgeReverser() Factory method that is called during doLayoutCore(LayoutGraph).
protected Grouping	createGrouping(LayoutGraph graph) Factory method that is called during doLayoutCore(LayoutGraph).
IncrementalHintsFactory	createIncrementalHintsFactory() Returns an IncrementalHintsFactory implementation that can be used to obtain hint objects that can be associated with nodes and edges in the graph prior to the invocation of the layout algorithm using an appropriate DataProvider implementation and the INCREMENTAL_HINTS_DPKEY DataProvider key.
protected Layerer	createIncrementalLayerer() Factory method that is called during doLayoutCore(LayoutGraph).
protected void	createItemData(LayoutGraph g, ItemFactory itemFactory) Callback method that is called during doLayoutCore(LayoutGraph).
protected LayoutStage	createLabelLayouter() Factory method for the label layouter used by this layouter.
LayerConstraintFactory	createLayerConstraintFactory(Graph graph)
protected Layerer	createLayerer() Factory method that is called lazily upon first usage.
protected Layers	createLayers(LayoutDataProvider ldp) Factory method that is called during doLayoutCore(LayoutGraph).
protected NodePlacer	createNodePlacer() Factory method that is called lazily upon first usage.
protected PortAllocator	createPortAllocator() Factory method that is called lazily upon first usage.
protected PortConstraintOptimizer	createPortConstraintOptimizer() Factory method that is called lazily upon first usage.
SequenceConstraintFactory	createSequenceConstraintFactory(Graph graph)
protected Sequencer	createSequencer() Factory method that is called lazily upon first usage.
protected Sequencer	createSubgraphLayerSequencer() Factory method that is called during doLayoutCore(LayoutGraph).
void	doLayoutCore(LayoutGraph graph) Layouts the given graph.
Object	getAlgorithmProperty(Object key) Provides access to implementation specific properties of the algorithms used.
DrawingDistanceCalculator	getDrawingDistanceCalculator() Returns the current DrawingDistanceCalculator instance.
protected DataProvider	getEdgeLayoutDescriptors(LayoutGraph graph) Callback method that is called during doLayoutCore(LayoutGraph).
protected DataProvider	getIncrementalHints(LayoutGraph graph) Callback method that is called during doLayoutCore(LayoutGraph).
Layerer	getLayerer() Returns the current Layerer instance.
long	getMaximalDuration() Returns the time limit (in milliseconds) set for the layout algorithm.
protected DataProvider	getNodeLayoutDescriptors(LayoutGraph graph) Callback method that is called during doLayoutCore(LayoutGraph).
NodePlacer	getNodePlacer() Returns the current NodePlacer instance.
PortAllocator	getPortAllocator() Returns the current PortAllocator instance.
PortConstraintOptimizer	getPortConstraintOptimizer() Returns the current PortConstraintOptimizer instance.
Sequencer	getSequencer() Returns the current Sequencer instance.
protected DataProvider	getSwimLaneDescriptors(LayoutGraph graph) Callback method that is called during doLayoutCore(LayoutGraph).
protected void	publishLayers(LayoutGraph graph, Layers layers) Callback method that publishes the layering information
protected void	publishSequences(LayoutGraph graph, Layers layers, LayoutDataProvider ldp) Callback method that publishes the sequencing information
protected void	reduceBendCount(LayoutGraph graph) Removes bends from the edges which are obviously not necessary.
void	setAlgorithmProperty(Object key, Object value) Provides access to implementation specific properties of the algorithms used internally.
void	setDrawingDistanceCalculator(DrawingDistanceCalculator drawingDistanceCalculator) Sets the DrawingDistanceCalculator implementation that is used in the next run.
void	setLayerer(Layerer layerer) Sets the Layerer implementation that is used in the next run.
void	setMaximalDuration(long maximalDuration) Sets a preferred time limit (in milliseconds) for the layout algorithm.
void	setNodePlacer(NodePlacer placer) Sets the NodePlacer implementation that is used in the next run.
void	setPortAllocator(PortAllocator allocator) Sets the PortAllocator implementation that is used in the next run.
void	setPortConstraintOptimizer(PortConstraintOptimizer optimizer) Sets the PortConstraintOptimizer implementation that is used in the next run.
void	setSequencer(Sequencer sequencer) Sets the Sequencer implementation that is used in the next run.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setComponentLayouterEnabled, setGroupNodeHider, setGroupNodeHidingEnabled, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setOrientationLayouterEnabled, setParallelEdgeLayouter, setParallelEdgeLayouterEnabled, setSelfLoopLayouter, setSelfLoopLayouterEnabled, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Field Detail

INCREMENTAL_HINTS_DPKEY

public static final Object INCREMENTAL_HINTS_DPKEY

DataProvider key used to retrieve incremental layout hint objects for nodes and edges that have been set using the IncrementalHintsFactory which itself can be obtained from the createIncrementalHintsFactory() method. Note that HierarchicLayouter uses the registered DataProvider to get layout hint objects as well for nodes as for edges so neither Graph.createNodeMap() nor Graph.createEdgeMap() may be used to create this provider.

EDGE_LAYOUT_DESCRIPTOR_DPKEY

public static final Object EDGE_LAYOUT_DESCRIPTOR_DPKEY

DataProvider key used to retrieve EdgeLayoutDescriptor instances for each edge in the graph. Different settings will affect the routing of the edges during the layout.

See Also:

EdgeData.getEdgeLayoutDescriptor()

NODE_LAYOUT_DESCRIPTOR_DPKEY

public static final Object NODE_LAYOUT_DESCRIPTOR_DPKEY

DataProvider key used to retrieve NodeLayoutDescriptor instances for each node in the graph. Different settings will affect node placement and port assignment during the layout.

See Also:

NodeData.getNodeLayoutDescriptor()

SWIMLANE_DESCRIPTOR_DPKEY

public static final Object SWIMLANE_DESCRIPTOR_DPKEY

DataProvider key used to store SwimLaneDescriptor instances for each node in the graph. If this key is present during the layout. The layout algorithm will arrange nodes in swim lanes. The information about the swim lanes is finally written back into the descriptor instances. Instances can be shared among multiple nodes in the same lane, but don't have to be shared.

See Also:

SwimLaneDescriptor, NodeData.getSwimLaneDescriptor()

LAYER_VALUE_HOLDER_DPKEY

public static final Object LAYER_VALUE_HOLDER_DPKEY

Used for publishing the final layering information. If the DataProvider associated to this key is also a DataAcceptor, the integer layer id of each node is stored using the acceptor's setInt method. Otherwise, the provider's values should be of type IntValueHolder and the value holder's setValue method is used to store the integer layer ids of each node.

SEQUENCE_VALUE_HOLDER_DPKEY

public static final Object SEQUENCE_VALUE_HOLDER_DPKEY

Used for publishing the final sequencing information. If the DataProvider associated to this key is also a DataAcceptor, the sequence order number of each node is stored using the acceptor's setInt method. Otherwise, the provider's values should be of type IntValueHolder and the value holder's setValue method is used to store the sequence order number of each node.

INCREMENTAL_NODES_DPKEY

public static final Object INCREMENTAL_NODES_DPKEY

DataProvider key used to hold boolean values for each node in the graph that indicate whether the node has to be added incrementally. This key is used by the incremental versions of Layerer, such as TopologicalIncrementalLayerer to determine which nodes need to be inserted incrementally, as well as the Sequencer implementation that determines incrementally sequenced nodes.

Constructor Detail

HierarchicLayouter

public HierarchicLayouter()

Creates a new instance of HierarchicLayouter with default settings.

See Also:

createLayerer(), createIncrementalLayerer(), createSequencer(), createDrawingDistanceCalculator(), createNodePlacer()

Method Detail

createLabelLayouter

protected LayoutStage createLabelLayouter()

Factory method for the label layouter used by this layouter. In order to use the the integrated node label awareness feature one has to use an LabelLayoutTranslator instance with LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) set to true.
Likewise in order to make use of the integrated edge labeling LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) must be set to true and LabelLayoutTranslator.setWriteBackEdgeLabelsEnabled(boolean) must be set to true also (which is the default).

Returns:

a new LabelLayoutTranslator with node translation enabled and "node label write back" disabled.

createLayerer

protected Layerer createLayerer()

Factory method that is called lazily upon first usage.

Returns:

a default implementation (new MultiComponentLayerer(new OldLayererWrapper(new WeightedLayerer())))

See Also:

getLayerer(), MultiComponentLayerer, OldLayererWrapper, WeightedLayerer

getMaximalDuration

public long getMaximalDuration()

Returns the time limit (in milliseconds) set for the layout algorithm.

Returns:

the time limit.

See Also:

setMaximalDuration(long)

setMaximalDuration

public void setMaximalDuration(long maximalDuration)

Sets a preferred time limit (in milliseconds) for the layout algorithm. Note that restricting the maximal duration may result in a worse layout quality. Furthermore, the real runtime may exceed the maximal duration since the layout algorithm still have to find a valid solution.

Parameters:

maximalDuration - the time limit.

See Also:

getMaximalDuration()

createSequencer

protected Sequencer createSequencer()

Factory method that is called lazily upon first usage.

Returns:

a default implementation (new DefaultLayerSequencer())

See Also:

getSequencer(), DefaultLayerSequencer

createDrawingDistanceCalculator

protected DrawingDistanceCalculator createDrawingDistanceCalculator()

Factory method that is called lazily upon first usage.

Returns:

a default implementation (new DefaultDrawingDistanceCalculator())

See Also:

getDrawingDistanceCalculator()

createPortAllocator

protected PortAllocator createPortAllocator()

Factory method that is called lazily upon first usage.

Returns:

a default implementation (new DefaultPortAllocator())

See Also:

getPortAllocator()

createPortConstraintOptimizer

protected PortConstraintOptimizer createPortConstraintOptimizer()

Factory method that is called lazily upon first usage.

Returns:

null

See Also:

getPortConstraintOptimizer()

createNodePlacer

protected NodePlacer createNodePlacer()

Factory method that is called lazily upon first usage.

Returns:

a default implementation (new SimplexNodePlacer)

See Also:

getNodePlacer(), SimplexNodePlacer

setLayerer

public void setLayerer(Layerer layerer)

Sets the Layerer implementation that is used in the next run. For the default see createLayerer().

Throws:

NullPointerException - if the argument is null

Parameters:

layerer - the new implementation to use.

getLayerer

public Layerer getLayerer()

Returns the current Layerer instance.

Returns:

the layerer

See Also:

createLayerer()

setSequencer

public void setSequencer(Sequencer sequencer)

Sets the Sequencer implementation that is used in the next run. For the default see createSequencer().

Throws:

NullPointerException - if the argument is null

Parameters:

sequencer - the new implementation to use.

getSequencer

public Sequencer getSequencer()

Returns the current Sequencer instance.

Returns:

the sequencer

See Also:

createSequencer()

setNodePlacer

public void setNodePlacer(NodePlacer placer)

Sets the NodePlacer implementation that is used in the next run. For the default see createNodePlacer().

Throws:

NullPointerException - if the argument is null

Parameters:

placer - the new implementation to use.

getNodePlacer

public NodePlacer getNodePlacer()

Returns the current NodePlacer instance.

Returns:

the layerer

See Also:

createNodePlacer()

setPortAllocator

public void setPortAllocator(PortAllocator allocator)

Sets the PortAllocator implementation that is used in the next run. For the default see createPortAllocator().

Throws:

NullPointerException - if the argument is null

Parameters:

allocator - the new implementation to use.

getPortAllocator

public PortAllocator getPortAllocator()

Returns the current PortAllocator instance.

Returns:

the port allocator

See Also:

createPortAllocator()

setPortConstraintOptimizer

public void setPortConstraintOptimizer(PortConstraintOptimizer optimizer)

Sets the PortConstraintOptimizer implementation that is used in the next run. For the default see createPortConstraintOptimizer().

Parameters:

optimizer - the new implementation to use.

getPortConstraintOptimizer

public PortConstraintOptimizer getPortConstraintOptimizer()

Returns the current PortConstraintOptimizer instance.

Returns:

the port constraint optimizer

See Also:

createPortConstraintOptimizer()

setDrawingDistanceCalculator

public void setDrawingDistanceCalculator(DrawingDistanceCalculator drawingDistanceCalculator)

Sets the DrawingDistanceCalculator implementation that is used in the next run. For the default see createDrawingDistanceCalculator().

Throws:

NullPointerException - if the argument is null

Parameters:

drawingDistanceCalculator - the new implementation to use.

getDrawingDistanceCalculator

public DrawingDistanceCalculator getDrawingDistanceCalculator()

Returns the current DrawingDistanceCalculator instance.

Returns:

the drawingDistanceCalculator

See Also:

createDrawingDistanceCalculator()

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Always returns true.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the graph to check

Returns:

true

getAlgorithmProperty

public Object getAlgorithmProperty(Object key)

Provides access to implementation specific properties of the algorithms used.
Used for internal purposes.

Parameters:

key - the key to a property

Returns:

the associated value or null

See Also:

setAlgorithmProperty(Object,Object)

setAlgorithmProperty

public void setAlgorithmProperty(Object key,
                                 Object value)

Provides access to implementation specific properties of the algorithms used internally.
Used for internal purposes.

Parameters:

key - the key to a property

value - the value to associate with the key

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Layouts the given graph.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the graph to layout

createGrouping

protected Grouping createGrouping(LayoutGraph graph)

Factory method that is called during doLayoutCore(LayoutGraph).

Parameters:

graph - the graph to obtain the grouping information from.

Returns:

a Grouping or null if there is no grouping information associated with the graph.

getIncrementalHints

protected DataProvider getIncrementalHints(LayoutGraph graph)

Callback method that is called during doLayoutCore(LayoutGraph). This method returns a DataProvider that holds the incremental hint information.

Parameters:

graph - the graph to obtain the information from.

Returns:

a DataProvider instance or null

See Also:

INCREMENTAL_HINTS_DPKEY

getEdgeLayoutDescriptors

protected DataProvider getEdgeLayoutDescriptors(LayoutGraph graph)

Callback method that is called during doLayoutCore(LayoutGraph). This method returns a DataProvider that holds the EdgeLayoutDescriptor information.

Parameters:

graph - the graph to obtain the information from.

Returns:

a DataProvider instance or null

See Also:

EdgeLayoutDescriptor, EDGE_LAYOUT_DESCRIPTOR_DPKEY

getNodeLayoutDescriptors

protected DataProvider getNodeLayoutDescriptors(LayoutGraph graph)

Callback method that is called during doLayoutCore(LayoutGraph). This method returns a DataProvider that holds the NodeLayoutDescriptor information.

Parameters:

graph - the graph to obtain the information from.

Returns:

a DataProvider instance or null

See Also:

NodeLayoutDescriptor, NODE_LAYOUT_DESCRIPTOR_DPKEY

getSwimLaneDescriptors

protected DataProvider getSwimLaneDescriptors(LayoutGraph graph)

Callback method that is called during doLayoutCore(LayoutGraph). This method returns a DataProvider that holds the SwimLaneDescriptor information.

Parameters:

graph - the graph to obtain the information from.

Returns:

a DataProvider instance or null

See Also:

SwimLaneDescriptor, SWIMLANE_DESCRIPTOR_DPKEY

createItemData

protected void createItemData(LayoutGraph g,
                              ItemFactory itemFactory)

Callback method that is called during doLayoutCore(LayoutGraph). This method creates the NodeData and EdgeData instances and binds them to the elements using the itemFactory.

Parameters:

g - the graph to obtain the grouping information from.

itemFactory - the ItemFactory to use

createSubgraphLayerSequencer

protected Sequencer createSubgraphLayerSequencer()

Factory method that is called during doLayoutCore(LayoutGraph).

Returns:

a Sequencer implementation that can sequence subgraphs incrementally.

createLayers

protected Layers createLayers(LayoutDataProvider ldp)

Factory method that is called during doLayoutCore(LayoutGraph). Creates an appropriate Layers implementation using the LayoutDataProvider

Parameters:

ldp - provides the layout data

Returns:

a Layers implementation

createIncrementalLayerer

protected Layerer createIncrementalLayerer()

Factory method that is called during doLayoutCore(LayoutGraph). Creates an appropriate IncrementalLayerer implementation

Returns:

an implementation

createEdgeReverser

protected EdgeReverser createEdgeReverser()

Factory method that is called during doLayoutCore(LayoutGraph). Creates an appropriate EdgeReverser implementation

Returns:

an implementation

publishLayers

protected void publishLayers(LayoutGraph graph,
                             Layers layers)

Callback method that publishes the layering information

Parameters:

graph - the graph that contains the elements

layers - the Layers implementation to get the layering information from

See Also:

LAYER_VALUE_HOLDER_DPKEY

publishSequences

protected void publishSequences(LayoutGraph graph,
                                Layers layers,
                                LayoutDataProvider ldp)

Callback method that publishes the sequencing information

Parameters:

graph - the graph that contains the elements

layers - the Layers implementation to get the layering information from

ldp - the LayoutDataProvider to get the node information from

See Also:

SEQUENCE_VALUE_HOLDER_DPKEY

reduceBendCount

protected void reduceBendCount(LayoutGraph graph)

Removes bends from the edges which are obviously not necessary. This method removes bends from the graph that are collinear.

Parameters:

graph - the graph to obtain the edges from

createIncrementalHintsFactory

public IncrementalHintsFactory createIncrementalHintsFactory()

Returns an IncrementalHintsFactory implementation that can be used to obtain hint objects that can be associated with nodes and edges in the graph prior to the invocation of the layout algorithm using an appropriate DataProvider implementation and the INCREMENTAL_HINTS_DPKEY DataProvider key.

Returns:

an instance that can be used with this layouter instance

See Also:

INCREMENTAL_HINTS_DPKEY

createSequenceConstraintFactory

public SequenceConstraintFactory createSequenceConstraintFactory(Graph graph)

createLayerConstraintFactory

public LayerConstraintFactory createLayerConstraintFactory(Graph graph)