y.layout.hierarchic
Class ConstraintLayerer

java.lang.Object
  y.layout.hierarchic.ConstraintLayerer

All Implemented Interfaces:

Layerer

public class ConstraintLayerer
extends java.lang.Object
implements Layerer, Layerer

ConstraintLayerer considers relative and absolute layering constraints when assigning the nodes to layers.

There are two supported sets of constraints:

• Absolute constraints, i.e. place nodes in the top or bottom layer.
• Relative constraints, i.e. place a node above, below or in the same layer as another node.

Constraints for a given graph can be created by means of a ConstraintLayerer.ConstraintFactory instance, which should be created with createConstraintFactory(Graph) for a given graph instance.

The ConstraintLayerer will try to create a layering for the nodes and edges that have no constraints that resembles the one produced by the core layerer. The result is better if less constraints exist. Ideally, the constrained nodes are just embedded into the layering created by the core layerer.

This class can be used with IncrementalHierarchicLayouter as well as HierarchicLayouter and HierarchicGroupLayouter.

Nested Class Summary

static interface

ConstraintLayerer.ConstraintFactory Interface specification for classes that can create suitable constraints for a ConstraintLayerer instance.

Field Summary

static java.lang.String

EDGE_WEIGHTS_DPKEY A DataProvider key for adding weights to the edges of the graph.

Constructor Summary

ConstraintLayerer()
Creates a new instance of ConstraintLayerer with the default settings.

ConstraintLayerer(Layerer coreLayerer)
Creates an instance of ConstraintLayerer with the given core Layerer instance.

Method Summary

void	assignLayers(LayoutGraph graph, Layers layers, LayoutDataProvider ldp) Assigns all nodes of the graph to layers and adds them to the Layers instance.
int	assignNodeLayer(LayoutGraph graph, NodeMap layerID, EdgeList reversedEdges) Assigns all nodes of the graph to layers
protected void	checkConstraints() Checks whether the current set of strong constraints is consistent (i.e., has no cycles).
static ConstraintLayerer.ConstraintFactory	createConstraintFactory(Graph graph) Creates an instance of ConstraintLayerer.ConstraintFactory that is suitable for this layerer implementation.
Layerer	getCoreLayerer() Returns the core layerer for this ConstraintLayerer instance.
boolean	isAllowSameLayerEdges() Returns whether or not same-layer edges can be created by this instance.
void	setAllowSameLayerEdges(boolean allowSameLayerEdges) Specifies whether or not same-layer edges can be created by this instance.
void	setCoreLayerer(Layerer coreLayerer) Specifies the core layerer for this ConstraintLayerer instance.

Methods inherited from class java.lang.Object

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

Field Detail

EDGE_WEIGHTS_DPKEY

public static final java.lang.String EDGE_WEIGHTS_DPKEY

A DataProvider key for adding weights to the edges of the graph.

The layerer tries to maintain edges with higher weights short.

See Also:

Constant Field Values

Constructor Detail

ConstraintLayerer

public ConstraintLayerer(Layerer coreLayerer)

Creates an instance of ConstraintLayerer with the given core Layerer instance.

Parameters:

coreLayerer - the given Layerer instance

ConstraintLayerer

public ConstraintLayerer()

Creates a new instance of ConstraintLayerer with the default settings.

Method Detail

getCoreLayerer

public Layerer getCoreLayerer()

Returns the core layerer for this ConstraintLayerer instance.

The ConstraintLayerer tries to create a layering for the nodes and edges that have no constraints that resembles the layering that would be created by the core layerer. This works better if less constraints exist. Ideally, the constrained nodes are just embedded into the layering created by the core layerer.

Returns:

the layerer used for unconstrained nodes

See Also:

setCoreLayerer(Layerer)

setCoreLayerer

public void setCoreLayerer(Layerer coreLayerer)

Specifies the core layerer for this ConstraintLayerer instance.

The ConstraintLayerer tries to create a layering for the nodes and edges that have no constraints that resembles the layering that would be created by the core layerer. This works better if less constraints exist. Ideally, the constrained nodes are just embedded into the layering created by the core layerer.

Default Value:

The default value is TopologicalLayerer. A layerer based on topological sorting is used.

Parameters:

coreLayerer - the layerer used for unconstrained nodes

isAllowSameLayerEdges

public boolean isAllowSameLayerEdges()

Returns whether or not same-layer edges can be created by this instance.

This only concerns edges between nodes that have no hard constraints that will force a same-layer edge (i.e., a same-layer constraint).

Returns:

true if unconstrained same-layer edges are allowed, false otherwise

See Also:

setAllowSameLayerEdges(boolean)

setAllowSameLayerEdges

public void setAllowSameLayerEdges(boolean allowSameLayerEdges)

Specifies whether or not same-layer edges can be created by this instance.

This only concerns edges between nodes that have no hard constraints that will force a same-layer edge (i.e., a same-layer constraint).

Default Value:

The default value is false. Same-layer edges are not allowed.

Parameters:

allowSameLayerEdges - true if unconstrained same-layer edges are allowed, false otherwise

assignNodeLayer

public int assignNodeLayer(LayoutGraph graph,
                           NodeMap layerID,
                           EdgeList reversedEdges)

Assigns all nodes of the graph to layers

Parameters:

graph - the graph

layerID - the NodeMap that will be filled by the layout algorithm and returns the zero-based index of the layer to which each node belongs

reversedEdges - an EdgeList containing the edges which had been reversed

Returns:

the number of layers

Throws:

java.lang.IllegalArgumentException - if any strong constraints are inconsistent

checkConstraints

protected void checkConstraints()

Checks whether the current set of strong constraints is consistent (i.e., has no cycles).

This method is called in assignNodeLayer(LayoutGraph, NodeMap, EdgeList) after all explicit constraints have been created and checks whether this constraint network is acyclic. It can be overridden for custom constraint checking.

Throws:

java.lang.IllegalArgumentException - if the constraint network is inconsistent

assignLayers

public void assignLayers(LayoutGraph graph,
                         Layers layers,
                         LayoutDataProvider ldp)

Assigns all nodes of the graph to layers and adds them to the Layers instance.

Specified by:

assignLayers in interface Layerer

Parameters:

graph - the input graph

layers - the Layers instance that will be filled with the results of the calculation

ldp - the LayoutDataProvider used for querying information about the nodes and edges

See Also:

Layers.insert(byte, int), Layer.add(y.base.Node)

createConstraintFactory

public static ConstraintLayerer.ConstraintFactory createConstraintFactory(Graph graph)

Creates an instance of ConstraintLayerer.ConstraintFactory that is suitable for this layerer implementation.

The ConstraintLayerer.ConstraintFactory instance is usually bound to Graph instance graph, i.e., if the input graph for the layerer changes, a new ConstraintLayerer.ConstraintFactory instance must be retrieved. This instance can be used for creating constraints for this graph instance.

You can create a ConstraintLayerer.ConstraintFactory instance without binding it to a graph instance initially by passing a null parameter. In that case, you must bind the returned instance to the graph instance before calculating a layering:

 ConstraintFactory cf = ConstraintLayerer.createConstraintFactory(null);
 ...
 Graph graph = ...;
 graph.addDataProvider(ConstraintFactory.LAYER_CONSTRAINTS_MEMENTO_DPKEY,
    DataProviders.createConstantDataProvider(cf.getMemento())););
 //Calculate layout
 

If you manually registered a DataProvider with the graph using Layouter.NODE_ID_DPKEY, you must use the corresponding node IDs stored in this DataProvider as arguments for all methods that create a constraint. Otherwise, you can just use the node instances themselves.

Parameters:

graph - the graph

Returns:

a ConstraintLayerer.ConstraintFactory instance bound to the input graph

See Also:

ConstraintLayerer.ConstraintFactory.getMemento(), ConstraintLayerer.ConstraintFactory.LAYER_CONSTRAINTS_MEMENTO_DPKEY