Describes how to connect nodes using hyperedges, the differences between IlvLinkImage and IlvHyperEdge, hyperedge ends, and how to retrieve incident hyperedges at nodes.

To connect multiple nodes by a hyperedge, you must create the nodes and add them to the hypergraph. This works in IlvHyperGrapher exactly in the same way as in IlvGrapher.

To add a node:

To connect several nodes by a hyperedge:

The following code example shows how to create a hypergraph, four nodes, and a hyperedge.

The classes IlvLinkImage and IlvHyperEdge differ in the following areas:

Orientation

Normal links ( IlvLinkImage ) have a flag that indicates whether they are oriented. If the links are oriented, an arrowhead will be drawn. The orientation flag is necessary because, if an arrowhead were always drawn, then there would be no way of drawing a link between two nodes that did not represent a flow direction.

Hyperedges are always oriented. Therefore, an arrowhead is drawn at the target nodes and this arrowhead cannot be switched off.

This feature is not a restriction. If you want to draw a hyperedge between several nodes without an arrowhead, create a hyperedge that has all these nodes as sources, but has no target node.

You can also create a hyperedge that has only target nodes, but no source node. In this case, an arrowhead is drawn at all end nodes of the hyperedge.

You can see that hyperedges are much more flexible than normal links.

If a hyperedge has exactly one source node and one target node, then it will look like, and behave approximately as, a normal oriented link.

If a hyperedge has exactly two source nodes and zero target nodes, then it will look like a normal unoriented link.

Changing end nodes of a link

To change the end nodes of an IlvLinkImage object, you must remove the IlvLinkImage from the graph. Then you must change the end nodes and reinsert the link into the graph.

Changing the end nodes of an IlvHyperEdge object is more convenient. The end nodes can be changed while the hyperedge remains in the hypergraph. For example, you can add an empty hyperedge with zero end nodes to the hypergraph. Then you can add source and target nodes later. You must encapsulate all operations that change the end nodes of a hyperedge into applyToObject sessions. See Modifying geometric properties of objects in The Essential Features of JViews Framework user documentation for more details.

The operations that can be carried out on IlvHyperEdge are shown in the following table.

The following code example shows how to create an empty hyperedge, add it to the hypergraph, and then add some source nodes.

Normal links ( IlvLinkImage) can be incident to one node at most twice: if the link is a self-loop, that is, if the source and target of the link is the same node, then the link will occur in the list of incident links at the node twice. Both ends of the link are easily distinguishable, because one is the source end and the other is the target end.

Not only can a hyperedge ( IlvHyperEdge) have multiple end nodes, but it can also have multiple ends at the same node. Therefore this link is incident to the node multiple times. For example, if you call addFrom multiple times for the same node at the same hyperedge, this hyperedge will have multiple source ends at that node. See the following figure.

The interface IlvHyperEdgeEnd serves as the end indicator of a hyperedge. Instances of this interface are called the hyperedge ends. The default implementation is IlvDefaultHyperEdgeEnd.

The hyperedge ends technically belong to the hyperedge and not to the node. They point to the end node.

If a source or target node is added to the hyperedge, a new hyperedge end is created internally and connects the hyperedge to the node. If the hyperedge is removed from the hypergraph, all ends of the hyperedge will also be removed.

If a hyperedge connects to one node multiple times, there will be multiple different instances of IlvHyperEdgeEnd stored in the hyperedge. All these instances point to the node. The hyperedge ends can be distinguished from each other, even though the corresponding end node is the same.

The following table shows methods included in the API of IlvHyperEdgeEnd.

The following table shows the API of IlvHyperEdge in more detail. It explains how the operations influence the hyperedge ends and which additional API exists for manipulating the hyperedge ends directly at the hyperedge.

As a general rule, when the end nodes are retrieved or counted, a node occurs once only, even if there are multiple ends at a node. When the ends are retrieved or counted, multiple ends that point to the same node occur as distinguishable items. Therefore, the following equation is true:

The class IlvHyperEdge has other useful API, such as API for retrieving the ends or end nodes in an array, which is convenient if you need to remove the ends, or for checking whether a given end is source or target. See the reference documentation of IlvHyperEdge for details.

Nodes are any IlvGraphic object that is added to the graph by a call to addNode. Instances of IlvLinkImage or IlvHyperEdge cannot be added as nodes to the hypergraph; they must be added as links (by a call to addLink) or as hyperedges (by a call to addHyperEdge).

The same node can serve as end node for normal links and for hyperedges. IlvHyperGrapher provides different API for retrieving links or hyperedges that are incident to a node.

A hyperedge can have the same source node or the same target node multiple times. Say that a hyperedge, linkA, has the node, nodeB, five times as source node. (See the following figure.) By calling the methods shown in table Methods for retrieving links or hyperedges incident to a node, linkA would occur once only, even if it is incident to a node multiple times; that is, grapher.getHyperEdgesFrom(nodeB) would return linkA once only and grapher.getHyperEdgesFromCount(nodeB) would count linkA once only.

Multiple occurrences of the same source or target node are distinguished by the hyperedge end. The hyperedge linkA has five different hyperedge ends that point to nodeB. Therefore, IlvHyperGrapher provides methods for retrieving the hyperedge ends incident to a node. These methods are shown in the following table.

In the example illustrated by the figure Multiple ends at the same node, grapher.getHyperEdgeEndsFrom(nodeB) returns five different ends for the link linkA and grapher.getHyperEdgeEndsFromCount(nodeB) counts linkA five times, because it actually counts the ends of linkA.