Package org.graphstream.graph

Interface Graph

All Superinterfaces:
AttributeSink, Element, ElementSink, Iterable<Node>, Pipe, Sink, Source, Structure
All Known Implementing Classes:
AbstractGraph, AdjacencyListGraph, DefaultGraph, GraphicGraph, MultiGraph, SingleGraph
public interface Graph
extends Element, Pipe, Iterable<Node>, Structure
An Interface that advises general purpose methods for handling graphs.

This interface is one of the main interfaces of GraphStream. It defines the services provided by a graph structure. Graphs implementations must at least implement this interface (but are free to provide more services).

With Source, Sink and Pipe, this interface is one of the most important. A graph is a Pipe that buffers the graph events and present the graph structure as it is actually.

In other words, it allows to browse the graph structure, to explore it, to modify it, and to implement algorithms on it. This class can be seen as a snapshot of a stream of event at current time.

With factories (NodeFactory, EdgeFactory), users can define their own models of nodes or edges. Problem is that when you define such model, you want to access to elements with the valid type, without cast if possible. To improve the access to elements in such cases, Graph offers implicit genericity to access nodes or edges. The following is an example of an access without genericity : 

        Graph g = ... ;
        g.setNodeFactory( new MyNodeFactory() );
  g.addNode("root");

  MyNode n = (MyNode) g.getNode("root");

  for( Node o : g.getEachNode() )
  {
        MyNode node = (MyNode) o;
        // Do something with node
  }

With implicit genericity offers by Graph, this can be done easier: 

  Graph g = ... ;
        g.setNodeFactory( new MyNodeFactory() );
  g.addNode("root");

  MyNode n = g.getNode("root");

  for( MyNode node : g.getEachNode() )
  {
        // Do something with node
  }

Graph elements (nodes and edges) can be accessed using their identifier or their index. Each node / edge has a unique string identifier assigned when the element is created. Each element has an automatically maintained unique index between 0 and Structure.getNodeCount() - 1 or Structure.getEdgeCount() - 1. When a new element is added, its index is getNodeCount() - 1 or getEdgeCount() - 1. When an element is removed, the element with the biggest index takes its place. Unlike identifiers, indices can change when the graph is modified, but they are always successive. A loop of the form 

 for (int i = 0; i < g.getNodeCount(); i++) {
        Node node = g.getNode(i);
        // Do something with node
 }

will always iterate on all the nodes of g.

  • Method Details

    • getNode

      Node getNode​(String id)
      Get a node by its identifier. This method is implicitly generic and returns something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode node = graph.getNode("...");

      the method will return an ExtendedNode node. If no left part exists, method will just return a Node.

      Parameters:
      id - Identifier of the node to find.
      Returns:
      The searched node or null if not found.

    • getEdge

      Edge getEdge​(String id)
      Get an edge by its identifier. 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 edge = graph.getEdge("...");

      the method will return an ExtendedEdge edge. If no left part exists, method will just return an Edge.

      Parameters:
      id - Identifier of the edge to find.
      Returns:
      The searched edge or null if not found.

    • nodeFactory

      NodeFactory<? extends Node> nodeFactory()
      The factory used to create node instances. The factory can be changed to refine the node class generated for this graph.
      See Also:
      setNodeFactory(NodeFactory), edgeFactory()

    • edgeFactory

      EdgeFactory<? extends Edge> edgeFactory()
      The factory used to create edge instances. The factory can be changed to refine the edge class generated for this graph.
      See Also:
      setEdgeFactory(EdgeFactory), nodeFactory()

    • isStrict

      boolean isStrict()
      Is strict checking enabled? If strict checking is enabled the graph checks for name space conflicts (e.g. insertion of two nodes with the same name), removal of non-existing elements, use of non existing elements (create an edge between two non existing nodes). Graph implementations are free to respect strict checking or not.
      Returns:
      True if enabled.

    • isAutoCreationEnabled

      boolean isAutoCreationEnabled()
      Is the automatic creation of missing elements enabled?. If strict checking is disabled and auto-creation is enabled, when an edge is created and one or two of its nodes are not already present in the graph, the nodes are automatically created.
      Returns:
      True if enabled.

    • getStep

      double getStep()
      The current step.
      Returns:
      The step.

    • setNodeFactory

      void setNodeFactory​(NodeFactory<? extends Node> nf)
      Set the node factory used to create nodes.
      Parameters:
      nf - the new NodeFactory

    • setEdgeFactory

      void setEdgeFactory​(EdgeFactory<? extends Edge> ef)
      Set the edge factory used to create edges.
      Parameters:
      ef - the new EdgeFactory

    • setStrict

      void setStrict​(boolean on)
      Enable or disable strict checking.
      Parameters:
      on - True or false.
      See Also:
      isStrict()

    • setAutoCreate

      void setAutoCreate​(boolean on)
      Enable or disable the automatic creation of missing elements.
      Parameters:
      on - True or false.
      See Also:
      isAutoCreationEnabled()

    • clear

      void clear()
      Empty the graph completely by removing any references to nodes or edges. Every attribute is also removed. However, listeners are kept.
      See Also:
      Source.clearSinks()

    • addNode

      Node addNode​(String id) throws IdAlreadyInUseException
      Add a node in the graph.

      This acts as a factory, creating the node instance automatically (and eventually using the node factory provided). An event is generated toward the listeners. If strict checking is enabled, and a node already exists with this identifier, an IdAlreadyInUseException is raised. Else the error is silently ignored and the already existing node is returned.

      This method is implicitly generic and returns something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode n = graph.addNode("...");

      the method will return an ExtendedNode. If no left part exists, method will just return a Node.

      Parameters:
      id - Arbitrary and unique string identifying the node.
      Returns:
      The created node (or the already existing node).
      Throws:
      IdAlreadyInUseException - If strict checking is enabled the identifier is already used.

    • addEdge

      default Edge addEdge​(String id, String node1, String node2) throws IdAlreadyInUseException, ElementNotFoundException, EdgeRejectedException
      Adds an undirected edge between nodes.

      The behavior of this method depends on many conditions. It can be summarized as follows.

      First of all, the method checks if the graph already contains an edge with the same id. If this is the case and strict checking is enabled, IdAlreadyInUseException is thrown. If the strict checking is disabled the method returns a reference to the existing edge if it has endpoints node1 and node2 (in the same order if the edge is directed) or null otherwise.

      In the case when the graph does not contain an edge with the same id, the method checks if node1 and node2 exist. If one or both of them do not exist, and strict checking is enabled, ElementNotFoundException is thrown. Otherwise if auto-creation is disabled, the method returns null. If auto-creation is enabled, the method creates the missing endpoints.

      When the edge id is not already in use and the both endpoints exist (or created), the edge can still be rejected. It may happen for example when it connects two already connected nodes in a single graph. If the edge is rejected, the method throws EdgeRejectedException if strict checking is enabled or returns null otherwise. Finally, if the edge is accepted, it is created using the corresponding edge factory and a reference to it is returned.

      An edge creation event is sent toward the listeners. If new nodes are created, the corresponding events are also sent to the listeners.

      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 = graph.addEdge("...", "...", "...");

      the method will return an ExtendedEdge. If no left part exists, method will just return an Edge.

      Parameters:
      id - Unique and arbitrary string identifying the edge.
      node1 - The first node identifier.
      node2 - The second node identifier.
      Returns:
      The newly created edge, an existing edge or null (see the detailed description above)
      Throws:
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      ElementNotFoundException - If strict checking is enabled, and 'node1' or 'node2' are not registered in the graph.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.

    • addEdge

      default Edge addEdge​(String id, String from, String to, boolean directed) throws IdAlreadyInUseException, ElementNotFoundException, EdgeRejectedException
      Like addEdge(String, String, String), but this edge can be directed between the two given nodes. If directed, the edge goes in the 'from' -> 'to' direction. An event is sent toward the listeners.
      Parameters:
      id - Unique and arbitrary string identifying the edge.
      from - The first node identifier.
      to - The second node identifier.
      directed - Is the edge directed?
      Returns:
      The newly created edge, an existing edge or null (see the detailed description in addEdge(String, String, String))
      Throws:
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      ElementNotFoundException - If strict checking is enabled, and 'node1' or 'node2' are not registered in the graph.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.
      See Also:
      addEdge(String, String, String)

    • stepBegins

      void stepBegins​(double time)

      Since dynamic graphs are based on discrete event modifications, the notion of step is defined to simulate elapsed time between events. So a step is a event that occurs in the graph, it does not modify it but it gives a kind of timestamp that allows the tracking of the progress of the graph over the time.

      This kind of event is useful for dynamic algorithms that listen to the dynamic graph and need to measure the time in the graph's evolution.

      Parameters:
      time - A numerical value that may give a timestamp to track the evolution of the graph over the time.

    • attributeSinks

      Iterable<AttributeSink> attributeSinks()
      Returns an "iterable" of AttributeSink objects registered to this graph.
      Returns:
      the set of AttributeSink under the form of an iterable object.

    • elementSinks

      Iterable<ElementSink> elementSinks()
      Returns an "iterable" of ElementSink objects registered to this graph.
      Returns:
      the list of ElementSink under the form of an iterable object.

    • read

      default void read​(String filename) throws IOException, GraphParseException, ElementNotFoundException
      Utility method to read a graph. This method tries to identify the graph format by itself and instantiates the corresponding reader automatically. If this process fails, a NotFoundException is raised.
      Parameters:
      filename - The graph filename (or URL).
      Throws:
      ElementNotFoundException - If the file cannot be found or if the format is not recognized.
      GraphParseException - If there is a parsing error while reading the file.
      IOException - If an input output error occurs during the graph reading.

    • read

      default void read​(FileSource input, String filename) throws IOException, GraphParseException
      Utility method to read a graph using the given reader.
      Parameters:
      input - An appropriate reader for the filename.
      filename - The graph filename (or URL).
      Throws:
      ElementNotFoundException - If the file cannot be found or if the format is not recognised.
      GraphParseException - If there is a parsing error while reading the file.
      IOException - If an input/output error occurs during the graph reading.

    • write

      default void write​(String filename) throws IOException
      Utility method to write a graph in DGS format to a file.
      Parameters:
      filename - The file that will contain the saved graph (or URL).
      Throws:
      IOException - If an input/output error occurs during the graph writing.

    • write

      default void write​(FileSink output, String filename) throws IOException
      Utility method to write a graph in the chosen format to a file.
      Parameters:
      filename - The file that will contain the saved graph (or URL).
      output - The output format to use.
      Throws:
      IOException - If an input/output error occurs during the graph writing.

    • display

      Viewer display()
      Utility method that creates a new graph viewer, and register the graph in it. Notice that this method is a quick way to see a graph, and only this. It can be used to prototype a program, but may be limited. This method automatically launch a graph layout algorithm in its own thread to compute best node positions.
      Returns:
      a graph viewer that allows to command the viewer (it often run in another thread).
      See Also:
      Viewer, display(boolean )

    • display

      Viewer display​(boolean autoLayout)
      Utility method that creates a new graph viewer, and register the graph in it. Notice that this method is a quick way to see a graph, and only this. It can be used to prototype a program, but is very limited.
      Parameters:
      autoLayout - If true a layout algorithm is launched in its own thread to compute best node positions.
      Returns:
      a graph viewer that allows to command the viewer (it often run in another thread).
      See Also:
      Viewer, display()

    • getNode

      Node getNode​(int index) throws IndexOutOfBoundsException
      Get a node by its index. This method is implicitly generic and returns something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode node = graph.getNode(index);

      the method will return an ExtendedNode node. If no left part exists, method will just return a Node.

      Parameters:
      index - Index of the node to find.
      Returns:
      The node with the given index
      Throws:
      IndexOutOfBoundsException - If the index is negative or greater than getNodeCount() - 1.

    • getEdge

      Edge getEdge​(int index) throws IndexOutOfBoundsException
      Get an edge by its index. 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 edge = graph.getEdge(index);

      the method will return an ExtendedEdge edge. If no left part exists, method will just return an Edge.

      Parameters:
      index - The index of the edge to find.
      Returns:
      The edge with the given index
      Throws:
      IndexOutOfBoundsException - if the index is less than 0 or greater than getNodeCount() - 1.

    • addEdge

      default Edge addEdge​(String id, int index1, int index2) throws IndexOutOfBoundsException, IdAlreadyInUseException, EdgeRejectedException
      Like addEdge(String, String, String) but the nodes are identified by their indices.
      Parameters:
      id - Unique and arbitrary string identifying the edge.
      index1 - The first node index
      index2 - The second node index
      Returns:
      The newly created edge, an existing edge or null
      Throws:
      IndexOutOfBoundsException - If node indices are negative or greater than getNodeCount() - 1
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.
      See Also:
      addEdge(String, String, String)

    • addEdge

      default Edge addEdge​(String id, int fromIndex, int toIndex, boolean directed) throws IndexOutOfBoundsException, IdAlreadyInUseException, EdgeRejectedException
      Like addEdge(String, String, String, boolean) but the nodes are identified by their indices.
      Parameters:
      id - Unique and arbitrary string identifying the edge.
      toIndex - The first node index
      fromIndex - The second node index
      directed - Is the edge directed?
      Returns:
      The newly created edge, an existing edge or null
      Throws:
      IndexOutOfBoundsException - If node indices are negative or greater than getNodeCount() - 1
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.
      See Also:
      addEdge(String, String, String)

    • addEdge

      default Edge addEdge​(String id, Node node1, Node node2) throws IdAlreadyInUseException, EdgeRejectedException
      Like addEdge(String, String, String) but the node references are given instead of node identifiers.
      Parameters:
      id - Unique and arbitrary string identifying the edge.
      node1 - The first node
      node2 - The second node
      Returns:
      The newly created edge, an existing edge or null
      Throws:
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.
      See Also:
      addEdge(String, String, String)

    • addEdge

      Edge addEdge​(String id, Node from, Node to, boolean directed) throws IdAlreadyInUseException, EdgeRejectedException
      Like addEdge(String, String, String, boolean) but the node references are given instead of node identifiers.
      Parameters:
      id - Unique and arbitrary string identifying the edge.
      from - The first node
      to - The second node
      directed - Is the edge directed?
      Returns:
      The newly created edge, an existing edge or null
      Throws:
      IdAlreadyInUseException - If an edge with the same id already exists and strict checking is enabled.
      EdgeRejectedException - If strict checking is enabled and the edge is not accepted.
      See Also:
      addEdge(String, String, String)

    • removeEdge

      default Edge removeEdge​(int index) throws IndexOutOfBoundsException
      Removes an edge with a given index. An event is sent toward the listeners.

      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 edge = graph.removeEdge(i);

      the method will return an ExtendedEdge edge. If no left part exists, method will just return an Edge.

      Parameters:
      index - The index of the edge to be removed.
      Returns:
      The removed edge
      Throws:
      IndexOutOfBoundsException - if the index is negative or greater than getEdgeCount() - 1

    • removeEdge

      default Edge removeEdge​(int fromIndex, int toIndex) throws IndexOutOfBoundsException, ElementNotFoundException
      Removes an edge between two nodes. Like removeEdge(String, String) but the nodes are identified by their indices.
      Parameters:
      fromIndex - the index of the source node
      toIndex - the index of the target node
      Returns:
      the removed edge or null if no edge is removed
      Throws:
      IndexOutOfBoundsException - If one of the node indices is negative or greater than getNodeCount() - 1.
      ElementNotFoundException - if strict checking is enabled and there is no edge between the two nodes.
      See Also:
      removeEdge(String, String)

    • removeEdge

      Edge removeEdge​(Node node1, Node node2) throws ElementNotFoundException
      Removes an edge between two nodes. Like removeEdge(String, String) but node references are given instead of node identifiers.
      Parameters:
      node1 - the first node
      node2 - the second node
      Returns:
      the removed edge or null if no edge is removed
      Throws:
      ElementNotFoundException - if strict checking is enabled and there is no edge between the two nodes.
      See Also:
      removeEdge(String, String)

    • removeEdge

      default Edge removeEdge​(String from, String to) throws ElementNotFoundException
      Remove an edge given the identifiers of its two endpoints.

      If the edge is directed it is removed only if its source and destination nodes are identified by 'from' and 'to' respectively. If the graph is a multi-graph and there are several edges between the two nodes, one of the edges at random is removed. An event is sent toward the listeners. If strict checking is enabled and at least one of the two given nodes does not exist or if they are not connected, a not found exception is raised. Else the error is silently ignored, and null is returned.

      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 = graph.removeEdge("...", "...");

      the method will return an ExtendedEdge. If no left part exists, method will just return an Edge.

      Parameters:
      from - The origin node identifier to select the edge.
      to - The destination node identifier to select the edge.
      Returns:
      The removed edge, or null if strict checking is disabled and at least one of the two given nodes does not exist or there is no edge between them
      Throws:
      ElementNotFoundException - If the 'from' or 'to' node is not registered in the graph or not connected and strict checking is enabled.

    • removeEdge

      default Edge removeEdge​(String id) throws ElementNotFoundException
      Removes an edge knowing its identifier. An event is sent toward the listeners. If strict checking is enabled and the edge does not exist, ElementNotFoundException is raised. Otherwise the error is silently ignored and null is returned.

      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 = graph.removeEdge("...");

      the method will return an ExtendedEdge. If no left part exists, method will just return an Edge.

      Parameters:
      id - Identifier of the edge to remove.
      Returns:
      The removed edge, or null if strict checking is disabled and the edge does not exist.
      Throws:
      ElementNotFoundException - If no edge matches the identifier and strict checking is enabled.

    • removeEdge

      Edge removeEdge​(Edge edge)
      Removes an edge. An event is sent toward the listeners.

      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 = graph.removeEdge(...);

      the method will return an ExtendedEdge. If no left part exists, method will just return an Edge.

      Parameters:
      edge - The edge to be removed
      Returns:
      The removed edge

    • removeNode

      default Node removeNode​(int index) throws IndexOutOfBoundsException
      Removes a node with a given index.

      An event is generated toward the listeners. Note that removing a node may remove all edges it is connected to. In this case corresponding events will also be generated toward the listeners.

      This method is implicitly generic and return something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode n = graph.removeNode(index);

      the method will return an ExtendedNode. If no left part exists, method will just return a Node.

      Parameters:
      index - The index of the node to be removed
      Returns:
      The removed node
      Throws:
      IndexOutOfBoundsException - if the index is negative or greater than getNodeCount() - 1.

    • removeNode

      default Node removeNode​(String id) throws ElementNotFoundException
      Remove a node using its identifier.

      An event is generated toward the listeners. Note that removing a node may remove all edges it is connected to. In this case corresponding events will also be generated toward the listeners.

      This method is implicitly generic and return something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode n = graph.removeNode("...");

      the method will return an ExtendedNode. If no left part exists, method will just return a Node.

      Parameters:
      id - The unique identifier of the node to remove.
      Returns:
      The removed node. If strict checking is disabled, it can return null if the node to remove does not exist.
      Throws:
      ElementNotFoundException - If no node matches the given identifier and strict checking is enabled.

    • removeNode

      Node removeNode​(Node node)
      Removes a node.

      An event is generated toward the listeners. Note that removing a node may remove all edges it is connected to. In this case corresponding events will also be generated toward the listeners.

      This method is implicitly generic and return something which extends Node. The return type is the one of the left part of the assignment. For example, in the following call : 

       ExtendedNode n = graph.removeNode(...);

      the method will return an ExtendedNode. If no left part exists, method will just return a Node.

      Parameters:
      node - The node to be removed
      Returns:
      The removed node