com.eduworks.ec.graph.Graph Maven / Gradle / Ivy
/*
* Created on Oct 17, 2005
*
* Copyright (c) 2005, the JUNG Project and the Regents of the University
* of California
* All rights reserved.
*
* This software is open-source under the BSD license; see either
* "license.txt" or
* http://jung.sourceforge.net/license.txt for a description.
*/
package com.eduworks.ec.graph;
import org.stjs.javascript.Array;
import java.util.Collection;
/**
* A graph consisting of a set of vertices of type V
* set and a set of edges of type E. Edges of this
* graph type have exactly two endpoints; whether these endpoints
* must be distinct depends on the implementation.
*
* This interface permits, but does not enforce, any of the following
* common variations of graphs:
*
* - directed and undirected edges
*
- vertices and edges with attributes (for example, weighted edges)
*
- vertices and edges of different types (for example, bipartite
* or multimodal graphs)
*
- parallel edges (multiple edges which connect a single set of vertices)
*
- representations as matrices or as adjacency lists or adjacency maps
*
* Extensions or implementations of this interface
* may enforce or disallow any or all of these variations.
*
*
Definitions (with respect to a given vertex v):
*
* incoming edge of v: an edge that can be traversed
* from a neighbor of v to reach v
* outgoing edge of v: an edge that can be traversed
* from v to reach some neighbor of v
* predecessor of v: a vertex at the other end of an
* incoming edge of v
* successor of v: a vertex at the other end of an
* outgoing edge of v
*
*
*
* @author Joshua O'Madadhain
*
* Ported to Javascript by:
* @author Fritz Ray ([email protected])
* @author Tom Buskirk ([email protected])
* @class Graph
* @module com.eduworks.ec
* @extends Hypergraph
*/
public interface Graph extends Hypergraph {
/**
* Returns a Collection view of the incoming edges incident to vertex
* in this graph.
*
* @param vertex the vertex whose incoming edges are to be returned
* @return a Collection view of the incoming edges incident
* to vertex in this graph
* @method getInEdges
*/
Array getInEdges(V vertex);
/**
* Returns a Collection view of the outgoing edges incident to vertex
* in this graph.
*
* @param vertex the vertex whose outgoing edges are to be returned
* @return a Collection view of the outgoing edges incident
* to vertex in this graph
* @method getOutEdges
*/
Array getOutEdges(V vertex);
/**
* Returns a Collection view of the predecessors of vertex
* in this graph. A predecessor of vertex is defined as a vertex v
* which is connected to
* vertex by an edge e, where e is an outgoing edge of
* v and an incoming edge of vertex.
*
* @param vertex the vertex whose predecessors are to be returned
* @return a Collection view of the predecessors of
* vertex in this graph
* @method getPredecessors
*/
Array getPredecessors(V vertex);
/**
* Returns a Collection view of the successors of vertex
* in this graph. A successor of vertex is defined as a vertex v
* which is connected to
* vertex by an edge e, where e is an incoming edge of
* v and an outgoing edge of vertex.
*
* @param vertex the vertex whose predecessors are to be returned
* @return a Collection view of the successors of
* vertex in this graph
* @method getSuccessors
*/
Array getSuccessors(V vertex);
/**
* Returns the number of incoming edges incident to vertex.
* Equivalent to getInEdges(vertex).size().
*
* @param vertex the vertex whose indegree is to be calculated
* @return the number of incoming edges incident to vertex
* @method inDegree
*/
int inDegree(V vertex);
/**
* Returns the number of outgoing edges incident to vertex.
* Equivalent to getOutEdges(vertex).size().
*
* @param vertex the vertex whose outdegree is to be calculated
* @return the number of outgoing edges incident to vertex
* @method outDegree
*/
int outDegree(V vertex);
/**
* Returns true if v1 is a predecessor of v2 in this graph.
* Equivalent to v1.getPredecessors().contains(v2).
*
* @param v1 the first vertex to be queried
* @param v2 the second vertex to be queried
* @return true if v1 is a predecessor of v2, and false otherwise.
* @method isPredecessor
*/
boolean isPredecessor(V v1, V v2);
/**
* Returns true if v1 is a successor of v2 in this graph.
* Equivalent to v1.getSuccessors().contains(v2).
*
* @param v1 the first vertex to be queried
* @param v2 the second vertex to be queried
* @return true if v1 is a successor of v2, and false otherwise.
* @method isSuccessor
*/
boolean isSuccessor(V v1, V v2);
/**
* Returns the number of predecessors that vertex has in this graph.
* Equivalent to vertex.getPredecessors().size().
*
* @param vertex the vertex whose predecessor count is to be returned
* @return the number of predecessors that vertex has in this graph
* @method getPredecessorCount
*/
int getPredecessorCount(V vertex);
/**
* Returns the number of successors that vertex has in this graph.
* Equivalent to vertex.getSuccessors().size().
*
* @param vertex the vertex whose successor count is to be returned
* @return the number of successors that vertex has in this graph
* @method getSuccessorCount
*/
int getSuccessorCount(V vertex);
/**
* If directed_edge is a directed edge in this graph, returns the source;
* otherwise returns null.
* The source of a directed edge d is defined to be the vertex for which
* d is an outgoing edge.
* directed_edge is guaranteed to be a directed edge if
* its EdgeType is DIRECTED.
*
* @param directed_edge
* @return the source of directed_edge if it is a directed edge in this graph, or null otherwise
* @method getSource
*/
V getSource(E directed_edge);
/**
* If directed_edge is a directed edge in this graph, returns the destination;
* otherwise returns null.
* The destination of a directed edge d is defined to be the vertex
* incident to d for which
* d is an incoming edge.
* directed_edge is guaranteed to be a directed edge if
* its EdgeType is DIRECTED.
*
* @param directed_edge
* @return the destination of directed_edge if it is a directed edge in this graph, or null otherwise
* @method getDest
*/
V getDest(E directed_edge);
/**
* Returns true if vertex is the source of edge.
* Equivalent to getSource(edge).equals(vertex).
*
* @param vertex the vertex to be queried
* @param edge the edge to be queried
* @return true iff vertex is the source of edge
* @method isSource
*/
boolean isSource(V vertex, E edge);
/**
* Returns true if vertex is the destination of edge.
* Equivalent to getDest(edge).equals(vertex).
*
* @param vertex the vertex to be queried
* @param edge the edge to be queried
* @return true iff vertex is the destination of edge
*/
boolean isDest(V vertex, E edge);
/**
* Adds edge e to this graph such that it connects
* vertex v1 to v2.
* Equivalent to addEdge(e, new Pair(v1, v2)) .
* If this graph does not contain v1, v2,
* or both, implementations may choose to either silently add
* the vertices to the graph or throw an IllegalArgumentException.
* If this graph assigns edge types to its edges, the edge type of
* e will be the default for this graph.
* See Hypergraph.addEdge() for a listing of possible reasons
* for failure.
*
* @param e the edge to be added
* @param v1 the first vertex to be connected
* @param v2 the second vertex to be connected
* @return true if the add is successful, false otherwise
* @method addEdge
* @see Hypergraph#addEdge(Object, Collection)
* @see #addEdge(Object, Object, Object, EdgeType)
*/
boolean addEdge(E e, V v1, V v2);
/**
* Returns the vertex at the other end of edge from vertex.
* (That is, returns the vertex incident to edge which is not vertex.)
*
* @param vertex the vertex to be queried
* @param edge the edge to be queried
* @return the vertex at the other end of edge from vertex
* @method getOpposite
*/
V getOpposite(V vertex, E edge);
}