public interface Graph extends Element, Pipe, Iterable<Node>, Structure
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
.
Modifier and Type | Method and Description |
---|---|
<T extends Edge> |
addEdge(String id,
int index1,
int index2)
Like
addEdge(String, String, String) but the nodes are
identified by their indices. |
<T extends Edge> |
addEdge(String id,
int fromIndex,
int toIndex,
boolean directed)
Like
addEdge(String, String, String, boolean) but the nodes are
identified by their indices. |
<T extends Edge> |
addEdge(String id,
Node node1,
Node node2)
Like
addEdge(String, String, String) but the node references are
given instead of node identifiers. |
<T extends Edge> |
addEdge(String id,
Node from,
Node to,
boolean directed)
Like
addEdge(String, String, String, boolean) but the node
references are given instead of node identifiers. |
<T extends Edge> |
addEdge(String id,
String node1,
String node2)
Adds an undirected edge between nodes.
|
<T extends Edge> |
addEdge(String id,
String from,
String to,
boolean directed)
Like
addEdge(String, String, String) , but this edge can be
directed between the two given nodes. |
<T extends Node> |
addNode(String id)
Add a node in the graph.
|
Iterable<AttributeSink> |
attributeSinks()
Returns an "iterable" of
AttributeSink objects registered to this
graph. |
void |
clear()
Empty the graph completely by removing any references to nodes or edges.
|
Viewer |
display()
Utility method that creates a new graph viewer, and register the graph in
it.
|
Viewer |
display(boolean autoLayout)
Utility method that creates a new graph viewer, and register the graph in
it.
|
EdgeFactory<? extends Edge> |
edgeFactory()
The factory used to create edge instances.
|
Iterable<ElementSink> |
elementSinks()
Returns an "iterable" of
ElementSink objects registered to this
graph. |
<T extends Edge> |
getEdge(int index)
Get an edge by its index.
|
<T extends Edge> |
getEdge(String id)
Get an edge by its identifier.
|
<T extends Node> |
getNode(int index)
Get a node by its index.
|
<T extends Node> |
getNode(String id)
Get a node by its identifier.
|
double |
getStep()
The current step.
|
boolean |
isAutoCreationEnabled()
Is the automatic creation of missing elements enabled?.
|
boolean |
isStrict()
Is strict checking enabled?
|
NodeFactory<? extends Node> |
nodeFactory()
The factory used to create node instances.
|
boolean |
nullAttributesAreErrors()
If true, when accessing an attribute that does not exist (or is not of
the expected type), a
NullAttributeException is thrown. |
void |
read(FileSource input,
String filename)
Utility method to read a graph using the given reader.
|
void |
read(String filename)
Utility method to read a graph.
|
<T extends Edge> |
removeEdge(Edge edge)
Removes an edge.
|
<T extends Edge> |
removeEdge(int index)
Removes an edge with a given index.
|
<T extends Edge> |
removeEdge(int fromIndex,
int toIndex)
Removes an edge between two nodes.
|
<T extends Edge> |
removeEdge(Node node1,
Node node2)
Removes an edge between two nodes.
|
<T extends Edge> |
removeEdge(String id)
Removes an edge knowing its identifier.
|
<T extends Edge> |
removeEdge(String from,
String to)
Remove an edge given the identifiers of its two endpoints.
|
<T extends Node> |
removeNode(int index)
Removes a node with a given index.
|
<T extends Node> |
removeNode(Node node)
Removes a node.
|
<T extends Node> |
removeNode(String id)
Remove a node using its identifier.
|
void |
setAutoCreate(boolean on)
Enable or disable the automatic creation of missing elements.
|
void |
setEdgeFactory(EdgeFactory<? extends Edge> ef)
Set the edge factory used to create edges.
|
void |
setNodeFactory(NodeFactory<? extends Node> nf)
Set the node factory used to create nodes.
|
void |
setNullAttributesAreErrors(boolean on)
Should a
NullAttributeException be thrown when one tries to
access a non existing attribute, or an attribute whose type is not the
expected one?. |
void |
setStrict(boolean on)
Enable or disable strict checking.
|
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.
|
void |
write(FileSink output,
String filename)
Utility method to write a graph in the chosen format to a file.
|
void |
write(String filename)
Utility method to write a graph in DGS format to a file.
|
addAttribute, addAttributes, changeAttribute, clearAttributes, getArray, getAttribute, getAttribute, getAttributeCount, getAttributeKeyIterator, getAttributeKeySet, getEachAttributeKey, getFirstAttributeOf, getFirstAttributeOf, getHash, getId, getIndex, getLabel, getNumber, getVector, hasArray, hasAttribute, hasAttribute, hasHash, hasLabel, hasNumber, hasVector, removeAttribute, setAttribute
addAttributeSink, addElementSink, addSink, clearAttributeSinks, clearElementSinks, clearSinks, removeAttributeSink, removeElementSink, removeSink
edgeAttributeAdded, edgeAttributeChanged, edgeAttributeRemoved, graphAttributeAdded, graphAttributeChanged, graphAttributeRemoved, nodeAttributeAdded, nodeAttributeChanged, nodeAttributeRemoved
edgeAdded, edgeRemoved, graphCleared, nodeAdded, nodeRemoved, stepBegins
forEach, iterator, spliterator
getEachEdge, getEachNode, getEdgeCount, getEdgeIterator, getEdgeSet, getNodeCount, getNodeIterator, getNodeSet
<T extends Node> T getNode(String id)
ExtendedNode node = graph.getNode("...");the method will return an ExtendedNode node. If no left part exists, method will just return a Node.
id
- Identifier of the node to find.<T extends Edge> T getEdge(String id)
ExtendedEdge edge = graph.getEdge("...");the method will return an ExtendedEdge edge. If no left part exists, method will just return an Edge.
id
- Identifier of the edge to find.NodeFactory<? extends Node> nodeFactory()
setNodeFactory(NodeFactory)
,
edgeFactory()
EdgeFactory<? extends Edge> edgeFactory()
setEdgeFactory(EdgeFactory)
,
nodeFactory()
boolean isStrict()
boolean isAutoCreationEnabled()
boolean nullAttributesAreErrors()
NullAttributeException
is thrown. Else null
is returned.double getStep()
void setNullAttributesAreErrors(boolean on)
NullAttributeException
be thrown when one tries to
access a non existing attribute, or an attribute whose type is not the
expected one?.on
- if true, exceptions will be thrown when accessing a non
existing attribute.void setNodeFactory(NodeFactory<? extends Node> nf)
nf
- the new NodeFactoryvoid setEdgeFactory(EdgeFactory<? extends Edge> ef)
ef
- the new EdgeFactoryvoid setStrict(boolean on)
on
- True or false.isStrict()
void setAutoCreate(boolean on)
on
- True or false.isAutoCreationEnabled()
void clear()
Source.clearSinks()
<T extends Node> T addNode(String id) throws IdAlreadyInUseException
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.
id
- Arbitrary and unique string identifying the node.IdAlreadyInUseException
- If strict checking is enabled the identifier is already used.<T extends Node> T removeNode(String id) throws ElementNotFoundException
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.
id
- The unique identifier of the node to remove.ElementNotFoundException
- If no node matches the given identifier and strict checking
is enabled.<T extends Edge> T addEdge(String id, String node1, String node2) throws IdAlreadyInUseException, ElementNotFoundException, EdgeRejectedException
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.
id
- Unique and arbitrary string identifying the edge.node1
- The first node identifier.node2
- The second node identifier.null
(see the
detailed description above)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.<T extends Edge> T addEdge(String id, String from, String to, boolean directed) throws IdAlreadyInUseException, ElementNotFoundException
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.id
- Unique and arbitrary string identifying the edge.node1
- The first node identifier.node2
- The second node identifier.directed
- Is the edge directed?null
(see the
detailed description above)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(String, String, String)
<T extends Edge> T removeEdge(String from, String to) throws ElementNotFoundException
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.
from
- The origin node identifier to select the edge.to
- The destination node identifier to select the edge.ElementNotFoundException
- If the 'from' or 'to' node is not registered in the graph or
not connected and strict checking is enabled.<T extends Edge> T removeEdge(String id) throws ElementNotFoundException
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.
id
- Identifier of the edge to remove.ElementNotFoundException
- If no edge matches the identifier and strict checking is
enabled.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.
time
- A numerical value that may give a timestamp to track the
evolution of the graph over the time.Iterable<AttributeSink> attributeSinks()
AttributeSink
objects registered to this
graph.AttributeSink
under the form of an iterable
object.Iterable<ElementSink> elementSinks()
ElementSink
objects registered to this
graph.ElementSink
under the form of an iterable
object.void read(String filename) throws IOException, GraphParseException, ElementNotFoundException
filename
- The graph filename (or URL).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.void read(FileSource input, String filename) throws IOException, GraphParseException
input
- An appropriate reader for the filename.filename
- The graph filename (or URL).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.void write(String filename) throws IOException
filename
- The file that will contain the saved graph (or URL).IOException
- If an input/output error occurs during the graph writing.void write(FileSink output, String filename) throws IOException
filename
- The file that will contain the saved graph (or URL).output
- The output format to use.IOException
- If an input/output error occurs during the graph writing.Viewer display()
Viewer
,
display(boolean )
Viewer display(boolean autoLayout)
<T extends Node> T getNode(int index) throws IndexOutOfBoundsException
ExtendedNode node = graph.getNode(index);the method will return an ExtendedNode node. If no left part exists, method will just return a Node.
index
- Index of the node to find.IndexOutOfBoundsException
- If the index is negative or greater than getNodeCount() - 1
.<T extends Edge> T getEdge(int index) throws IndexOutOfBoundsException
ExtendedEdge edge = graph.getEdge(index);the method will return an ExtendedEdge edge. If no left part exists, method will just return an Edge.
index
- The index of the edge to find.IndexOutOfBoundsException
- if the index is less than 0 or greater than getNodeCount() - 1
.<T extends Edge> T addEdge(String id, int index1, int index2) throws IndexOutOfBoundsException, IdAlreadyInUseException, EdgeRejectedException
addEdge(String, String, String)
but the nodes are
identified by their indices.id
- Unique and arbitrary string identifying the edge.index1
- The first node indexindex2
- The second node indexnull
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.addEdge(String, String, String)
<T extends Edge> T addEdge(String id, int fromIndex, int toIndex, boolean directed) throws IndexOutOfBoundsException, IdAlreadyInUseException, EdgeRejectedException
addEdge(String, String, String, boolean)
but the nodes are
identified by their indices.id
- Unique and arbitrary string identifying the edge.toIndex
- The first node indexfromIndex
- The second node indexdirected
- Is the edge directed?null
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.addEdge(String, String, String)
<T extends Edge> T addEdge(String id, Node node1, Node node2) throws IdAlreadyInUseException, EdgeRejectedException
addEdge(String, String, String)
but the node references are
given instead of node identifiers.id
- Unique and arbitrary string identifying the edge.node1
- The first nodenode2
- The second nodenull
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.addEdge(String, String, String)
<T extends Edge> T addEdge(String id, Node from, Node to, boolean directed) throws IdAlreadyInUseException, EdgeRejectedException
addEdge(String, String, String, boolean)
but the node
references are given instead of node identifiers.id
- Unique and arbitrary string identifying the edge.from
- The first nodeto
- The second nodedirected
- Is the edge directed?null
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.addEdge(String, String, String)
<T extends Edge> T removeEdge(int index) throws IndexOutOfBoundsException
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.
index
- The index of the edge to be removed.IndexOutOfBoundsException
- if the index is negative or greater than getEdgeCount() - 1
<T extends Edge> T removeEdge(int fromIndex, int toIndex) throws IndexOutOfBoundsException, ElementNotFoundException
removeEdge(String, String)
but the nodes are identified by their
indices.fromIndex
- the index of the source nodetoIndex
- the index of the target nodenull
if no edge is removedIndexOutOfBoundsException
- 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.removeEdge(String, String)
<T extends Edge> T removeEdge(Node node1, Node node2) throws ElementNotFoundException
removeEdge(String, String)
but node references are given instead
of node identifiers.node1
- the first nodenode2
- the second nodenull
if no edge is removedElementNotFoundException
- if strict checking is enabled and there is no edge between
the two nodes.removeEdge(String, String)
<T extends Edge> T removeEdge(Edge edge)
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.
edge
- The edge to be removed<T extends Node> T removeNode(int index) throws IndexOutOfBoundsException
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.
index
- The index of the node to be removedIndexOutOfBoundsException
- if the index is negative or greater than getNodeCount() - 1
.<T extends Node> T removeNode(Node 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.
node
- The node to be removedWebARTS Library Licensed Under the GNU - General Public License. Other Libraries licensed under their respective Open Source Licenses