edu.uci.ics.jung.graph
Interface ArchetypeEdge

All Superinterfaces:

UserDataContainer

All Known Subinterfaces:

DirectedEdge, Edge, GraphCollapser.CollapsedEdge, Hyperedge, UndirectedEdge

All Known Implementing Classes:

AbstractSparseEdge, BipartiteGraphCollapser.CollapsedBipartiteEdge, DirectedSparseEdge, GraphCollapser.DirectedCollapsedEdge, GraphCollapser.UndirectedCollapsedEdge, HyperedgeBPG, UndirectedSparseEdge

public interface ArchetypeEdge

extends UserDataContainer

A interface for edge implementations in generalized graphs.

Edges are added to graphs in a two-stage process. First the user calls the edge constructor, yielding an instance, e, of ArchetypeEdge. Then the user calls g.addEdge(e), where g is an implementation of ArchetypeGraph.

The two-stage nature of this process makes it possible to create "orphaned" edges that are not part of a graph. This was done as a compromise between common practices in Java APIs regarding the side effects of constructors, and the semantics of graphs. However, the behavior of ArchetypeEdge methods, with the exception of getGraph(), is unspecified on orphaned edges. The JUNG Project implementations will never create orphaned edges, and we strongly recommend that users follow this practice by nesting the constructor call inside the call to addEdge(), as in the following example:

g.addEdge(new UndirectedSparseEdge(v1, v2));

where v1 and v2 are vertices in g that this new edge is connecting.

An ill-formed edge is one that is incident to the wrong number of vertices. JUNG implementations will never create ill-formed edges, and will prune such edges if they are generated (for example, by a vertex removal).

Author:

Danyel Fisher, Joshua O'Madadhain, Scott White

See Also:

ArchetypeGraph, ArchetypeVertex

Nested Class Summary

Nested classes inherited from class edu.uci.ics.jung.utils.UserDataContainer

UserDataContainer.CopyAction

Method Summary

ArchetypeEdge	copy(ArchetypeGraph g) Creates a copy of this edge in graph g.
ArchetypeEdge	getEqualEdge(ArchetypeGraph g) Returns the edge in graph g, if any, that is equivalent to this edge.
ArchetypeEdge	getEquivalentEdge(ArchetypeGraph g) Deprecated. As of version 1.4, renamed to getEqualEdge(g).
ArchetypeGraph	getGraph() Returns a reference to the graph that contains this edge.
java.util.Set	getIncidentVertices() Returns the set of vertices which are incident to this edge.
boolean	isIncident(ArchetypeVertex v) Returns true if the specified vertex v is incident to this edge, and false otherwise.
int	numVertices() Returns the number of vertices which are incident to this edge.

Methods inherited from interface edu.uci.ics.jung.utils.UserDataContainer

addUserDatum, containsUserDatumKey, getUserDatum, getUserDatumCopyAction, getUserDatumKeyIterator, importUserData, removeUserDatum, setUserDatum

Method Detail

getGraph

public ArchetypeGraph getGraph()

Returns a reference to the graph that contains this edge. If this edge is not contained by any graph (is an "orphaned" edge), returns null.

getIncidentVertices

public java.util.Set getIncidentVertices()

Returns the set of vertices which are incident to this edge. Each of the vertices returned should implement ArchetypeVertex. For example, returns the source and destination vertices of a directed edge.

Returns:

the vertices incident to this edge

getEqualEdge

public ArchetypeEdge getEqualEdge(ArchetypeGraph g)

Returns the edge in graph g, if any, that is equivalent to this edge. Two edges are equivalent if one of them is an ancestor (via copy()) of the other.

See Also:

copy(ArchetypeGraph), ArchetypeVertex.getEqualVertex(ArchetypeGraph g)

getEquivalentEdge

public ArchetypeEdge getEquivalentEdge(ArchetypeGraph g)

Deprecated. As of version 1.4, renamed to getEqualEdge(g).

numVertices

public int numVertices()

Returns the number of vertices which are incident to this edge.

isIncident

public boolean isIncident(ArchetypeVertex v)

Returns true if the specified vertex v is incident to this edge, and false otherwise. The behavior of this method is undefined if v is not an element of this edge's graph.

copy

public ArchetypeEdge copy(ArchetypeGraph g)

Creates a copy of this edge in graph g. The edge created will be equivalent to this edge: given e = this.copy(g), then this.getEquivalentEdge(g) == e, and this.equals(e) == true.

Given the set of vertices S that are incident to this edge, the copied edge will be made incident to the set of vertices S' in g that are equivalent to S. S must be copied into g before this edge can be copied into g. If there is no such set of vertices in g, this method throws IllegalArgumentException.

Thus, for example, given the following code:

      Graph g1 = new Graph();
      Vertex v1 = g1.addVertex(new DirectedSparseVertex());
      Vertex v2 = g1.addVertex(new DirectedSparseVertex());
      ... 
      Edge e = g1.addEdge(new DirectedSparseEdge(v1, v2));
      Vertex v3 = v1.getEquivalentVertex(g2);
      Vertex v4 = v2.getEquivalentVertex(g2);
 

then e.copy(g2) will create a directed edge connecting v3 to v4 in g2.

Parameters:

g - the graph in which the copied edge will be placed

Returns:

the edge created

Throws:

java.lang.IllegalArgumentException

See Also:

getEqualEdge(ArchetypeGraph), ArchetypeVertex.getEqualVertex(ArchetypeGraph)