org.graphstream.graph.Node Maven / Gradle / Ivy
Show all versions of gs-core Show documentation
/*
* Copyright 2006 - 2015
* Stefan Balev
* Julien Baudry
* Antoine Dutot
* Yoann Pigné
* Guilhelm Savin
*
* This file is part of GraphStream .
*
* GraphStream is a library whose purpose is to handle static or dynamic
* graph, create them from scratch, file or any source and display them.
*
* This program is free software distributed under the terms of two licenses, the
* CeCILL-C license that fits European law, and the GNU Lesser General Public
* License. You can use, modify and/ or redistribute the software under the terms
* of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
* URL or under the terms of the GNU LGPL as published by
* the Free Software Foundation, either version 3 of the License, or (at your
* option) any later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT ANY
* WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
* PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see Important
*
* Implementing classes should indicate the complexity of their implementation
* for each method.
*
*
* @since July 12 2007
*/
public interface Node extends Element, Iterable {
/**
* Parent graph. Some elements are not able to give their parent graph.
*
* @return The graph containing this node or null if unknown.
*/
Graph getGraph();
/**
* Total number of relations with other nodes or this node.
*
* @return The number of edges/relations/links.
*/
int getDegree();
/**
* Number of leaving edges.
*
* @return the count of edges that only leave this node plus all undirected
* edges.
*/
int getOutDegree();
/**
* Number of entering edges.
*
* @return the count of edges that only enter this node plus all undirected
* edges.
*/
int getInDegree();
/**
* True if an edge leaves this node toward node 'id'.
*
* @param id
* Identifier of the target node.
* @return True if a directed edge goes from this node to 'id' or if an
* undirected edge exists.
*/
boolean hasEdgeToward(String id);
/**
* True if an edge enters this node from node 'id'.
*
* @param id
* Identifier of the source node.
* @return True if a directed edge goes from this node to 'id' or if an
* undirected edge exists.
*/
boolean hasEdgeFrom(String id);
/**
* True if an edge exists between this node and node 'id'.
*
* @param id
* Identifier of another node.
* @return True if a edge exists between this node and node 'id'.
*/
boolean hasEdgeBetween(String id);
/**
* Retrieve an edge that leaves this node toward 'id'.
*
* This method selects only edges leaving this node an pointing at node 'id'
* (this also selects undirected edges).
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeToward("...");
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param id
* Identifier of the target node.
* @return Directed edge going from this node to 'id', or undirected edge if
* it exists, else null.
*/
T getEdgeToward(String id);
/**
* Retrieve an edge that leaves node 'id' toward this node.
*
* This method selects only edges leaving node 'id' an pointing at this node
* (this also selects undirected edges).
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeFrom("...");
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param id
* Identifier of the source node.
* @return Directed edge going from node 'id' to this node, or undirected
* edge if it exists, else null.
*/
T getEdgeFrom(String id);
/**
* Retrieve an edge between this node and the node 'id', if it exits.
*
* This method selects directed or undirected edges. If the edge is
* directed, its direction is not important and leaving or entering edges
* will be selected.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeBetween("...");
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param id
* Identifier of the opposite node.
* @return Edge between node 'id' and this node if it exists, else null.
*/
T getEdgeBetween(String id);
/**
* Iterator on the set of connected edges.
*
* This iterator iterates on all edges leaving and entering (this includes
* any non-directed edge present, and a non-directed edge is only iterated
* once).
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedEdge> ite = node.getEdgeIterator();
*
*
* the method will return an Iterator<ExtendedEdge>. If no left part
* exists, method will just return an Iterator<Edge>.
*
*
* @return The iterator, edges are iterated in arbitrary order.
*/
Iterator getEdgeIterator();
/**
* Iterator only on leaving edges.
*
* This iterator iterates only on directed edges going from this node to
* others (non-directed edges are included in the iteration).
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedEdge> ite = node.getEnteringEdgeIterator();
*
*
* the method will return an Iterator<ExtendedEdge>. If no left part
* exists, method will just return an Iterator<Edge>.
*
*
* @return The iterator, edges are iterated in arbitrary order.
*/
Iterator getEnteringEdgeIterator();
/**
* Iterator only on entering edges.
*
* This iterator iterates only on directed edges going from other nodes
* toward this node (non-directed edges are included in the iteration).
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedEdge> ite = node.getLeavingEdgeIterator();
*
*
* the method will return an Iterator<ExtendedEdge>. If no left part
* exists, method will just return an Iterator<Edge>.
*
*
* @return The iterator, edges are iterated in arbitrary order.
*/
Iterator getLeavingEdgeIterator();
/**
* Iterator on the set of neighbor nodes connected to this node via one or
* more edges. This iterator iterates across any leaving, entering and non
* directed edges (nodes are neighbors even if they only have a directed
* edge from them toward this node). If there are multiple edges connecting
* the same node, it might be iterated several times.
*
* @return The iterator, neighbors are iterated in arbitrary order.
*/
Iterator getNeighborNodeIterator();
/**
* I-th edge. Edges are stored in no given order.
*
* However this method allows to iterate very quickly on all edges, or to
* choose a given edge with direct access.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdge(i);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param i
* Index of the edge.
* @return The i-th edge.
* @throws IndexOutOfBoundException
* if i is negative or greater than or equal to the
* degree
*/
T getEdge(int i);
/**
* I-th entering edge. Edges are stored in no given order.
*
* However this method allows to iterate very quickly on all entering edges,
* or to choose a given entering edge with direct access.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEnteringEdge(i);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param i
* Index of the edge.
* @return The i-th entering edge.
* @throws IndexOutOfBoundException
* if i is negative or greater than or equal to the
* in-degree
*/
T getEnteringEdge(int i);
/**
* I-th leaving edge. Edges are stored in no given order.
*
* However this method allows to iterate very quickly on all leaving edges,
* or to choose a given leaving edge with direct access.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getLeavingEdge(i);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param i
* Index of the edge.
* @return The i-th leaving edge.
* @throws IndexOutOfBoundException
* if i is negative or greater than or equal to the
* out-degree
*/
T getLeavingEdge(int i);
/**
* Iterator for breadth first exploration of the graph, starting at this
* node.
*
* If the graph is not connected, only a part of it will be explored. By
* default, this iterator will respect edge orientation.
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Node. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedNode> ite = node.getBreadthFirstIterator();
*
*
* the method will return an Iterator<ExtendedNode>. If no left part
* exists, method will just return an Iterator<Node>.
*
*
* @return An iterator able to explore the graph in a breadth first way
* starting at this node.
*/
Iterator getBreadthFirstIterator();
/**
* Iterator for breadth first exploration of the graph, starting at this
* node.
*
* If the graph is not connected, only a part of it will be explored.
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Node. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedNode> ite = node.getBreadthFirstIterator(true);
*
*
* the method will return an Iterator<ExtendedNode>. If no left part
* exists, method will just return an Iterator<Node>.
*
*
* @param directed
* If false, the iterator will ignore edge orientation (the
* default is "True").
* @return An iterator able to explore the graph in a breadth first way
* starting at this node.
*/
Iterator getBreadthFirstIterator(boolean directed);
/**
* Iterator for depth first exploration of the graph, starting at this node.
*
* If the graph is not connected, only a part of it will be explored. By
* default, this iterator will respect edge orientation.
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Node. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedNode> ite = node.getDepthFirstIterator();
*
*
* the method will return an Iterator<ExtendedNode>. If no left part
* exists, method will just return an Iterator<Node>.
*
*
* @return An iterator able to explore the graph in a depth first way
* starting at this node.
* @complexity of the depth first iterator O(n+m) with n the number of nodes
* and m the number of edges.
*/
Iterator getDepthFirstIterator();
/**
* Iterator for depth first exploration of the graph, starting at this node.
*
* If the graph is not connected, only a part of it will be explored.
*
*
* This method is implicitly generic and return an Iterator over something
* which extends Node. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterator<ExtendedNode> ite = node.getDepthFirstIterator(true);
*
*
* the method will return an Iterator<ExtendedNode>. If no left part
* exists, method will just return an Iterator<Node>.
*
*
* @param directed
* If false, the iterator will ignore edge orientation (the
* default is "True").
* @return An iterator able to explore the graph in a depth first way
* starting at this node.
*/
Iterator getDepthFirstIterator(boolean directed);
/**
* Set of all entering and leaving edges.
*
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection containing all directed and undirected edges,
* leaving or entering.
*/
Iterable getEachEdge();
/**
* Set of all leaving edges.
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getLeavingEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection of only edges that leave this node plus all
* undirected edges.
*/
Iterable getEachLeavingEdge();
/**
* Set of all entering edges.
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getEnteringEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection of only edges that enter this node plus all
* undirected edges.
*/
Iterable getEachEnteringEdge();
/**
* Set of all entering and leaving edges.
*
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection containing all directed and undirected edges,
* leaving or entering.
*/
Collection getEdgeSet();
/**
* Set of all leaving edges.
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getLeavingEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection of only edges that leave this node plus all
* undirected edges.
*/
Collection getLeavingEdgeSet();
/**
* Set of all entering edges.
*
* This method is implicitly generic and return an Iterable over something
* which extends Edge. The return type is the one of the left part of the
* assignment. For example, in the following call :
*
*
* Iterable<ExtendedEdge> ite = node.getEnteringEdgeSet();
*
*
* the method will return an Iterable<ExtendedEdge>. If no left part
* exists, method will just return an Iterable<Edge>.
*
*
* @return A collection of only edges that enter this node plus all
* undirected edges.
*/
Collection getEnteringEdgeSet();
/**
* Override the Object.toString() method.
*/
String toString();
// New methods
/**
* True if an edge leaves this node toward a given node.
*
* @param node
* The target node.
* @return True if a directed edge goes from this node to the other node or
* if an undirected edge exists.
*/
boolean hasEdgeToward(Node node);
/**
* True if an edge leaves this node toward a node with given index.
*
* @param index
* Index of the target node.
* @return True if a directed edge goes from this node to the other node or
* if an undirected edge exists.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
boolean hasEdgeToward(int index) throws IndexOutOfBoundsException;
/**
* True if an edge enters this node from a given node.
*
* @param node
* The source node.
* @return True if a directed edge goes from the other node to this node or
* if an undirected edge exists.
*/
boolean hasEdgeFrom(Node node);
/**
* True if an edge enters this node from a node with given index.
*
* @param index
* Index of the source node.
* @return True if a directed edge goes from the other node to this node or
* if an undirected edge exists.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
boolean hasEdgeFrom(int index) throws IndexOutOfBoundsException;
/**
* True if an edge exists between this node and another node.
*
* @param node
* Another node.
* @return True if an edge exists between this node and the other node.
*/
boolean hasEdgeBetween(Node node);
/**
* True if an edge exists between this node and a node with given index.
*
* @param index
* Index of another node.
* @return True if an edge exists between this node and the other node.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
boolean hasEdgeBetween(int index) throws IndexOutOfBoundsException;
/**
* Retrieves an edge that leaves this node toward another node.
*
* This method selects only edges leaving this node an pointing at the
* parameter node (this also selects undirected edges).
*
*
* This method is implicitly generic and returns something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeToward(...);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param node
* The target node.
* @return Directed edge going from this node to the parameter node, or
* undirected edge if it exists, else null.
*/
T getEdgeToward(Node node);
/**
* Retrieves an edge that leaves this node toward the node with given index.
*
* This method selects only edges leaving this node an pointing at the
* parameter node (this also selects undirected edges).
*
*
* This method is implicitly generic and returns something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeToward(...);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param index
* Index of the target node.
* @return Directed edge going from this node to the parameter node, or
* undirected edge if it exists, else null.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
T getEdgeToward(int index)
throws IndexOutOfBoundsException;
/**
* Retrieves an edge that leaves given node toward this node.
*
* This method selects only edges leaving the other node an pointing at this
* node (this also selects undirected edges).
*
*
* This method is implicitly generic and returns something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeFrom(...);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param node
* The source node.
* @return Directed edge going from the parameter node to this node, or
* undirected edge if it exists, else null.
*/
T getEdgeFrom(Node node);
/**
* Retrieves an edge that leaves node with given index toward this node.
*
* This method selects only edges leaving the other node an pointing at this
* node (this also selects undirected edges).
*
*
* This method is implicitly generic and returns something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeFrom("...");
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param index
* Index of the source node.
* @return Directed edge going from the parameter node to this node, or
* undirected edge if it exists, else null.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
T getEdgeFrom(int index) throws IndexOutOfBoundsException;
/**
* Retrieves an edge between this node and and another node if one exists.
*
* This method selects directed or undirected edges. If the edge is
* directed, its direction is not important and leaving or entering edges
* will be selected.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeBetween(...);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param node
* The opposite node.
* @return Edge between this node and the parameter node if it exists, else
* null.
*/
T getEdgeBetween(Node node);
/**
* Retrieves an edge between this node and the node with index i if one
* exists.
*
* This method selects directed or undirected edges. If the edge is
* directed, its direction is not important and leaving or entering edges
* will be selected.
*
*
* This method is implicitly generic and return something which extends
* Edge. The return type is the one of the left part of the assignment. For
* example, in the following call :
*
*
* ExtendedEdge e = node.getEdgeBetween(...);
*
*
* the method will return an ExtendedEdge. If no left part exists, method
* will just return an Edge.
*
*
* @param index
* The index of the opposite node.
* @return Edge between node with index i and this node if it exists, else
* null.
* @throws IndexOutOfBoundsException
* if the index is negative or greater than {@code
* getNodeCount() - 1}.
*/
T getEdgeBetween(int index)
throws IndexOutOfBoundsException;
}