y.layout.router
Class BusDescriptor

java.lang.Object
  y.layout.router.BusDescriptor

public class BusDescriptor
extends java.lang.Object

A descriptor for bus-related information to be associated with an edge.

It consists of a bus ID defining the bus of the associated edge, two optional edge group IDs for specifying the edge grouping at the source and target side, respectively, and an optional boolean flag to mark the edge as fixed.

Every object except null can be used as a valid edge group ID. If there is no group ID defined for an edge or if null is set, a default group ID is used. Therefore, all such edges ending at the same node belong to the same group.

At least one of the edges of a bus has to connect two different nodes. Otherwise, if all edges are self-loops (edges that start and end at the same node), the edges are routed separately without constituting a bus structure.

See Also:

BusRouter.EDGE_DESCRIPTOR_DPKEY

Field Summary

static byte	ROUTING_POLICY_ALWAYS A routing policy that indicates that a new route is calculated in any case.
static byte	ROUTING_POLICY_PATH_AS_NEEDED A routing policy that indicates that based on the current path it is automatically determined whether an edge is routed, and if so, the edge gets a whole new path.

Constructor Summary

BusDescriptor(java.lang.Object busID)
Creates a new instance of BusDescriptor for the specified bus ID which is marked as not fixed and uses the default edge group IDs.

BusDescriptor(java.lang.Object busID, boolean fixed)
Creates a new instance of BusDescriptor for the specified parameters and default group IDs.

BusDescriptor(java.lang.Object busID, boolean fixed, java.lang.Object sourceGroupID, java.lang.Object targetGroupID)
Creates a new instance of BusDescriptor for the specified parameters.

BusDescriptor(java.lang.Object busID, boolean fixed, java.lang.Object sourceGroupID, java.lang.Object targetGroupID, byte routingPolicy)
Creates a new instance of BusDescriptor for the specified parameters.

BusDescriptor(java.lang.Object busID, java.lang.Object sourceGroupID, java.lang.Object targetGroupID)
Creates a new instance of BusDescriptor for the specified parameters and marks it as not fixed.

Method Summary

boolean	equals(java.lang.Object obj) Indicates whether or not some other object is "equal to" this one.
java.lang.Object	getID() Returns the bus ID.
byte	getRoutingPolicy() Returns the routing policy indicating if the edge associated with this descriptor is unconditionally routed or if the existing route determines whether a routing is even necessary.
java.lang.Object	getSourceGroupID() Returns the group ID for the source side of the edge.
java.lang.Object	getTargetGroupID() Returns the group ID for the target side of the edge.
int	hashCode() Returns a hash code value for this BusDescriptor instance.
boolean	isFixed() Returns whether or not the associated edge is fixed.
void	setFixed(boolean fixed) Specifies whether or not the associated edge is fixed.
void	setID(java.lang.Object busID) Specifies the bus ID.
void	setRoutingPolicy(byte routingPolicy) Specifies the routing policy indicating if the edge associated with this descriptor is unconditionally routed or if the existing route determines whether a routing is even necessary.
void	setSourceGroupID(java.lang.Object sourceGroupID) Specifies the new group ID for the source side of the edge.
void	setTargetGroupID(java.lang.Object targetGroupID) Specifies the new group ID for the target side of the edge.
java.lang.String	toString() Returns a string representation consisting of the bus ID, the fixed flag, and both group IDs.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROUTING_POLICY_ALWAYS

public static final byte ROUTING_POLICY_ALWAYS

A routing policy that indicates that a new route is calculated in any case.

The existing path of an edge is ignored and the routing algorithm unconditionally generates a whole new path.

See Also:

Constant Field Values

Sample Graphs:

Initial graph

The edges got a new path, ignoring the existing one

ROUTING_POLICY_PATH_AS_NEEDED

public static final byte ROUTING_POLICY_PATH_AS_NEEDED

A routing policy that indicates that based on the current path it is automatically determined whether an edge is routed, and if so, the edge gets a whole new path.

The automatic selection examines the existing, given path of an edge. Based on various criteria it heuristically determines whether or not it needs to be routed. For example, intersections with other elements or a routing style violation are clear indicators. A further criterion is when the port constraints/candidates are not properly satisfied. Edges deemed to be 'good' are not changed.

This policy is convenient for cases where it is not clear which edges the algorithm should route. For example, after a user interaction (moving a node, inserting new elements etc.), routing of edges might become necessary but depending on the action it can not definitely be said which edges need to be corrected.

See Also:

Constant Field Values

Sample Graphs:

Initial graph

The three edges were selected for routing and they got a completely new path

Constructor Detail

BusDescriptor

public BusDescriptor(java.lang.Object busID)

Creates a new instance of BusDescriptor for the specified bus ID which is marked as not fixed and uses the default edge group IDs.

Parameters:

busID - the ID of the bus to which the associated edge belongs

BusDescriptor

public BusDescriptor(java.lang.Object busID,
                     java.lang.Object sourceGroupID,
                     java.lang.Object targetGroupID)

Creates a new instance of BusDescriptor for the specified parameters and marks it as not fixed.

Parameters:

busID - the ID of the bus to which the associated edge belongs

sourceGroupID - the group ID of the source side

targetGroupID - the group ID of the target side

BusDescriptor

public BusDescriptor(java.lang.Object busID,
                     boolean fixed)

Creates a new instance of BusDescriptor for the specified parameters and default group IDs.

Parameters:

busID - the ID of the bus to which the associated edge belongs

fixed - true if associated edge is fixed, false otherwise

BusDescriptor

public BusDescriptor(java.lang.Object busID,
                     boolean fixed,
                     java.lang.Object sourceGroupID,
                     java.lang.Object targetGroupID)

Creates a new instance of BusDescriptor for the specified parameters.

Parameters:

busID - the ID of the bus to which the associated edge belongs

fixed - true if associated edge is fixed, false otherwise

sourceGroupID - the group ID of the source side

targetGroupID - the group ID of the target side

BusDescriptor

public BusDescriptor(java.lang.Object busID,
                     boolean fixed,
                     java.lang.Object sourceGroupID,
                     java.lang.Object targetGroupID,
                     byte routingPolicy)

Creates a new instance of BusDescriptor for the specified parameters.

Parameters:

busID - the ID of the bus to which the associated edge belongs

fixed - true if associated edge is fixed, false otherwise

sourceGroupID - the group ID of the source side

targetGroupID - the group ID of the target side

routingPolicy - one of the predefined routing policies

Method Detail

equals

public boolean equals(java.lang.Object obj)

Indicates whether or not some other object is "equal to" this one.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the reference object with which to compare

Returns:

true if all corresponding parameters are equal, false otherwise

hashCode

public int hashCode()

Returns a hash code value for this BusDescriptor instance.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value

getID

public java.lang.Object getID()

Returns the bus ID.

Edges associated with descriptor instances having the same bus ID belong to a common bus.

Returns:

the bus ID

setID

public void setID(java.lang.Object busID)

Specifies the bus ID.

Edges associated with descriptor instances having the same bus ID belong to a common bus.

Parameters:

busID - the bus ID

getRoutingPolicy

public byte getRoutingPolicy()

Returns the routing policy indicating if the edge associated with this descriptor is unconditionally routed or if the existing route determines whether a routing is even necessary.

The routing policy only applies for edges that are not fixed in the first place. Fixed edges are never changed.

When only routing paths as needed, the algorithm tries to keep a lot of the existing routes and buses. For example, if two edges are defined to be on a common bus, but they are not yet, then only one of the edges is routed (given that the other has a proper orthogonal path) and parts of the other edge as the common bus. If optimizing the overall bus routing quality it might be better to use ROUTING_POLICY_ALWAYS.

The bus routing algorithm does only support policies ROUTING_POLICY_ALWAYS and ROUTING_POLICY_PATH_AS_NEEDED. Only routing specific segments as needed is not supported.

Returns:

one of the two predefined routing policies

See Also:

setRoutingPolicy(byte)

setRoutingPolicy

public void setRoutingPolicy(byte routingPolicy)

Specifies the routing policy indicating if the edge associated with this descriptor is unconditionally routed or if the existing route determines whether a routing is even necessary.

The routing policy only applies for edges that are not fixed in the first place. Fixed edges are never changed.

When only routing paths as needed, the algorithm tries to keep a lot of the existing routes and buses. For example, if two edges are defined to be on a common bus, but they are not yet, then only one of the edges is routed (given that the other has a proper orthogonal path) and parts of the other edge as the common bus. If optimizing the overall bus routing quality it might be better to use ROUTING_POLICY_ALWAYS.

The bus routing algorithm does only support policies ROUTING_POLICY_ALWAYS and ROUTING_POLICY_PATH_AS_NEEDED. Only routing specific segments as needed is not supported.

Default Value:

The default value is ROUTING_POLICY_ALWAYS. The edge is routed, ignoring the existing sketch.

Parameters:

routingPolicy - one of the two predefined routing policies

Throws:

java.lang.IllegalArgumentException - if an unknown routing policy is given

getSourceGroupID

public java.lang.Object getSourceGroupID()

Returns the group ID for the source side of the edge.

Edges incident to the same node v but associated with different group IDs at this endpoint, use separate bus connections at v.

Returns:

the group ID for the source side

setSourceGroupID

public void setSourceGroupID(java.lang.Object sourceGroupID)

Specifies the new group ID for the source side of the edge.

Edges incident to the same node v but associated with different group IDs at this endpoint, use separate bus connections at v.

If there is no group ID defined or if null is set, a default group ID is used. Therefore, all associated edges ending at the same node belong to the same group.

Default Value:

The default value is Object. All associated edges ending at the same node belong to the same group (unless otherwise specified in the constructor).

Parameters:

sourceGroupID - the group ID to set

getTargetGroupID

public java.lang.Object getTargetGroupID()

Returns the group ID for the target side of the edge.

Edges incident to the same node v but associated with different group IDs at this endpoint, use separate bus connections at v.

Returns:

the group ID for the target side

setTargetGroupID

public void setTargetGroupID(java.lang.Object targetGroupID)

Specifies the new group ID for the target side of the edge.

Edges incident to the same node v but associated with different group IDs at this endpoint, use separate bus connections at v.

If there is no group ID defined or if null is set, a default group ID is used. Therefore, all associated edges ending at the same node belong to the same group.

Default Value:

The default value is Object. All associated edges ending at the same node belong to the same group (unless otherwise specified in the constructor).

Parameters:

targetGroupID - the group ID to set

isFixed

public boolean isFixed()

Returns whether or not the associated edge is fixed.

The algorithm doesn't change the route of fixed edges but tries to prevent overlaps with non-fixed edges.

The structure induced by the fixed edges must be orthogonal and cycle-free.

Returns:

true if the associated edge is fixed, false otherwise

setFixed

public void setFixed(boolean fixed)

Specifies whether or not the associated edge is fixed.

The algorithm doesn't change the route of fixed edges but tries to prevent overlaps with non-fixed edges.

The structure induced by the fixed edges must be orthogonal and cycle-free.

Default Value:

The default value is false. The associated edge is not fixed (unless otherwise specified in the constructor).

Parameters:

fixed - true if the associated edge should be fixed, false otherwise

toString

public java.lang.String toString()

Returns a string representation consisting of the bus ID, the fixed flag, and both group IDs.

Overrides:

toString in class java.lang.Object

Returns:

a string representation consisting of the bus ID, the fixed flag, and both group IDs