y.layout
Class PortCandidateSet

java.lang.Object
  y.layout.PortCandidateSet

public class PortCandidateSet
extends java.lang.Object

This class associates PortCandidates with the nodes of a graph.

PortCandidates defined on nodes specify sides or even exact locations at which edges can be connected. This means that an edge can be connected to any of the available node ports (unless edge PortCandidates are specified too). Each node PortCandidate has a capacity, i.e., a maximum number of edges allowed to connect to it.

Information about PortCandidates on nodes is held by a DataProvider that stores a PortCandidateSet for each node and is registered with the graph using key NODE_DP_KEY.

The PortCandidates are retrieved from the PortCandidateSet through a PortCandidateSet.Entry that holds the information about the actual PortCandidate. This object is also used for retrieving the best candidate from a PortCandidateSet based on the cost (lower costs are considered first) and the available capacity of each candidate. Custom searching for the best PortCandidate can be achieved by implementing PortCandidateSet.CandidateMatcher interface.

Example of node port candidates. Circular ports represent node port candidates on source nodes of each edge. Square and rectangular ports are possible port candidates on the target node. Rectangular ports have zero cost of usage and unit capacity whereas square rectangles have unit cost and capacity.

Not all layout and routing algorithms are able to handle PortCandidates. Major layout algorithms that obey them are IncrementalHierarchicLayouter, EdgeRouter, ChannelEdgeRouter and BusRouter.

PortCandidateAssignmentStage can be appended to any layout algorithm that cannot handle port constraints in order to assign edges to the ports specified by PortConstraints or PortCandidates after calling the core layout algorithm.

In case that both PortConstraints and PortCandidates (on edges and/or nodes) are defined for a graph, the layout or the routing algorithm will try to match both of them in order to find an appropriate port. The matching process depends on the actual algorithm.

Nested Class Summary

static interface	PortCandidateSet.CandidateMatcher A PortCandidateSet.CandidateMatcher retrieves the best matching entries from a PortCandidateSet.
static interface	PortCandidateSet.Entry This interface represents an entry of a PortCandidateSet and provides access to the actual PortCandidate instance and the maximum number of edges allowed to connect to it.

Field Summary

static java.lang.Object

NODE_DP_KEY A DataProvider key for specifying a port candidate set for each node.

Constructor Summary

PortCandidateSet()
Creates a new empty PortCandidateSet instance.

Method Summary

void	add(PortCandidate p) Adds a PortCandidate with capacity 1 to this PortCandidateSet.
void	add(PortCandidate p, int connections) Adds a PortCandidate with the given capacity to this PortCandidateSet.
PortCandidateSet.CandidateMatcher	createMatcher() Creates a PortCandidateSet.CandidateMatcher that retrieves entries from this PortCandidateSet.
int	getConnectionCount() Returns the total number of connections allowed by the PortCandidates described by this PortCandidateSet or Integer.MAX_VALUE if the number is unbounded.
protected double	getCost(PortCandidateSet.Entry entry, Edge edge, boolean source, double xOffset, double yOffset) Calculates the penalty cost for the usage of the given entry and the given parameters.
java.util.Iterator	getEntries() Returns an Iterator over the list of candidate entries of this PortCandidateSet.
protected double	getPriority(PortCandidateSet.Entry entry, Edge edge, boolean source) Calculates the priority of the given entry.
void	remove(PortCandidateSet.Entry entry) Removes the given entry from the list of candidate entries.

Methods inherited from class java.lang.Object

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

Field Detail

NODE_DP_KEY

public static final java.lang.Object NODE_DP_KEY

A DataProvider key for specifying a port candidate set for each node.

Constructor Detail

PortCandidateSet

public PortCandidateSet()

Creates a new empty PortCandidateSet instance.

Addition of PortCandidates to this set can be performed using add(PortCandidate) or add(PortCandidate, int).

Method Detail

add

public void add(PortCandidate p)

Adds a PortCandidate with capacity 1 to this PortCandidateSet.

Addition of PortCandidates with capacity greater than 1 can be performed using add(PortCandidate, int).

Parameters:

p - the PortCandidate to add

See Also:

add(PortCandidate, int)

add

public void add(PortCandidate p,
                int connections)

Adds a PortCandidate with the given capacity to this PortCandidateSet.

The capacity value defines the maximum number of edges allowed to connect to the candidate. If no limitation for this number exists, Integer.MAX_VALUE can be used.

The capacity must be greater than zero.

Parameters:

p - the PortCandidate to add

connections - the capacity of the given port

Throws:

java.lang.IllegalArgumentException - if the given capacity is less than or equal to zero

getConnectionCount

public int getConnectionCount()

Returns the total number of connections allowed by the PortCandidates described by this PortCandidateSet or Integer.MAX_VALUE if the number is unbounded.

Returns:

the number of connections allowed by this PortCandidateSet

remove

public void remove(PortCandidateSet.Entry entry)

Removes the given entry from the list of candidate entries.

Parameters:

entry - the entry to remove

getEntries

public java.util.Iterator getEntries()

Returns an Iterator over the list of candidate entries of this PortCandidateSet.

Returns:

an Iterator over the list of PortCandidateSet.Entrys

createMatcher

public PortCandidateSet.CandidateMatcher createMatcher()

Creates a PortCandidateSet.CandidateMatcher that retrieves entries from this PortCandidateSet.

Each next best matching candidate is determined based on its cost, its current available capacity and based on whether or not its direction is consistent with the desired one.

This method may be overridden to support custom implementations of PortCandidateSet.CandidateMatcher.

While the EdgeRouter supports PortCandidateSets, it doesn't support custom PortCandidateSet.CandidateMatcher implementations.

Returns:

a new PortCandidateSet.CandidateMatcher instance

getCost

protected double getCost(PortCandidateSet.Entry entry,
                         Edge edge,
                         boolean source,
                         double xOffset,
                         double yOffset)

Calculates the penalty cost for the usage of the given entry and the given parameters.

The cost is equal to the cost of usage of the associated port candidate.

This method may be overridden to customize the calculation of the cost of usage of an entry.

Parameters:

entry - the entry for which the cost is computed

edge - the edge that will connect to the PortCandidate associated with the entry

source - true if the given edge connects to its source node, false otherwise

xOffset - the preferred X-offset of the port relative to the center of the node

yOffset - the preferred Y-offset of the port relative to the center of the node

Returns:

the penalty cost for the usage of the given PortCandidateSet.Entry

getPriority

protected double getPriority(PortCandidateSet.Entry entry,
                             Edge edge,
                             boolean source)

Calculates the priority of the given entry.

Higher priority means that the entry will be considered earlier by a PortCandidateSet.CandidateMatcher.

This method may be overridden to customize the calculation of the priority of entries.

Parameters:

entry - the entry for which the cost is computed

edge - the edge that will connect to the PortCandidate associated with the entry

source - true if the given edge connects to its source node, false otherwise

Returns:

the priority of the given PortCandidateSet.Entry