Gephi Toolkit Javadoc

org.gephi.graph.api
Interface Graph

All Superinterfaces:
Attributable
All Known Subinterfaces:
DirectedGraph, HierarchicalDirectedGraph, HierarchicalGraph, HierarchicalMixedGraph, HierarchicalUndirectedGraph, MixedGraph, UndirectedGraph

public interface Graph
extends Attributable

Main interface for accessing the graph structure and develop algorithms.

A graph object belongs to a graph model, which really contains the data. Graph objects are therefore only accessors, with all convinient methods to read and modify the structure. Hence, multiple Graph objects can exists.

Get current graph

 GraphController graphController = Lookup.getDefault().lookup(GraphController.class);
 GraphModel model = graphController.getModel();
 Graph graph = model.getGraph();
 
Note: This shows how to get the complete graph, for getting only the currently visualized graph, call model.getGraphVisible() instead.

Graph Locking

Graph structure possess a locking mechanism that avoids multiple threads to modify the structure concurrently. However, several readers are allowed.

There is two different way to perform read locking:

Be always sure you don't leave the structure blocked. use readUnlockAll() to release all the locks.

Note: Write locking is automatically done when modifying th graph (add, remove, ...).

Author:
Mathieu Bastian

Method Summary
 boolean addEdge(Edge edge)
          Add edge to the graph.
 boolean addNode(Node node)
          Add a node to the graph.
 void clear()
          Removes all nodes and edges in the graph.
 void clearEdges()
          Removes all edges in the graph.
 void clearEdges(Node node)
          Removes all edges incident to node.
 boolean contains(Edge edge)
          Returns true if the graph contains edge.
 boolean contains(Node node)
          Returns true if the graph contains node.
 int getDegree(Node node)
          Returns the degree of node.
 Edge getEdge(int id)
          Returns the edge with identifier equals to id.
 Edge getEdge(Node node1, Node node2)
          Finds and returns a directed or undirected edge that connects node1 and node2.
 Edge getEdge(java.lang.String id)
          Returns the edge with identifier equals to id.
 int getEdgeCount()
          Returns the number of edges in the graph
 EdgeIterable getEdges()
          Returns edges contained in the graph.
 EdgeIterable getEdges(Node node)
          Returns edges incident to node.
 int getEdgeVersion()
          Return the current edge version of the graph.
 GraphModel getGraphModel()
          Returns the graph model this graph belongs to.
 NodeIterable getNeighbors(Node node)
          Returns neighbors of node.
 Node getNode(int id)
          Returns the node with identifier equals to id.
 Node getNode(java.lang.String id)
          Returns the node with identifier equals to id.
 int getNodeCount()
          Returns the number of nodes in the graph.
 NodeIterable getNodes()
          Returns nodes contained in the graph.
 int getNodeVersion()
          Return the current node version of the graph.
 Node getOpposite(Node node, Edge edge)
          Returns the adjacent node of node through edge.
 GraphView getView()
          Returns the graph view this graph belongs to.
 boolean isAdjacent(Edge edge1, Edge edge2)
          Returns true if edge1 is adjacent to edge2.
 boolean isAdjacent(Node node1, Node node2)
          Returns true if node1 is adjacent to node2.
 boolean isDirected(Edge edge)
          Returns true if edge is a directed edge in the current graph.
 boolean isSelfLoop(Edge edge)
          Returns true if edge is a self-loop.
 void readLock()
          Acquires a read lock on the graph.
 void readUnlock()
          Releases the read lock on the graph.
 void readUnlockAll()
          Safe method that releases all read locks the calling thread has acquired.
 boolean removeEdge(Edge edge)
          Remove edge from the graph.
 boolean removeNode(Node node)
          Remove node from the graph.
 void setId(Edge edge, java.lang.String id)
          Sets the string identifier of edge.
 void setId(Node node, java.lang.String id)
          Sets the string identifier of node.
 void writeLock()
          Acquires a write lock on the graph.
 void writeUnlock()
          Release the write lock on the graph.
 
Methods inherited from interface org.gephi.graph.api.Attributable
getAttributes
 

Method Detail

addEdge

boolean addEdge(Edge edge)
Add edge to the graph. Graph does not accept parallel edges. Fails if edge is already in the graph.

Parameters:
edge - the edge to add
Returns:
true if add is successful, false otherwise
Throws:
java.lang.IllegalArgumentException - if edge is null, or if nodes are not legal nodes for this edge, or if edge is directed when the graph is undirected, or if edge is undirected when the graph is directed,
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

addNode

boolean addNode(Node node)
Add a node to the graph. Fails if the node already exists.

Parameters:
node - the node to add
Returns:
true if add is successful, false otherwise
Throws:
java.lang.IllegalArgumentException - if node is null
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

removeEdge

boolean removeEdge(Edge edge)
Remove edge from the graph. Fails if the edge doesn't exist.

Parameters:
edge - the edge to remove
Returns:
true if remove is successful, false otherwise
Throws:
java.lang.IllegalArgumentException - if edge is null or nodes not legal in the graph
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

removeNode

boolean removeNode(Node node)
Remove node from the graph. All node's children and incident edges will also be removed.

Parameters:
node - the node to remove
Returns:
true if remove is successful, false otherwise
Throws:
java.lang.IllegalArgumentException - if node is null or not legal in the graph.
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

contains

boolean contains(Node node)
Returns true if the graph contains node.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
node - the node whose presence is required
Returns:
true if the graph contains node
Throws:
java.lang.IllegalArgumentException - if node is null

contains

boolean contains(Edge edge)
Returns true if the graph contains edge.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
edge - the edge whose presence is required
Returns:
true if the graph contains edge
Throws:
java.lang.IllegalArgumentException - if edge is null

getNode

Node getNode(int id)
Returns the node with identifier equals to id. If not found, returns null. This id is generated and can be found in Node.getId().

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
id - a positive number
Returns:
the node with given id, or null if not found

getNode

Node getNode(java.lang.String id)
Returns the node with identifier equals to id. If not found, returns null. This id is set by user and can be found at NodeData.getId(). To set this Id, use Graph.setId().

The node must be present in the view this graph is from.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
id - the string identifier, unique
Returns:
the node with given id, or null if not found

getEdge

Edge getEdge(int id)
Returns the edge with identifier equals to id. If not found, returns null. This id is generated and can be found in Edge.getId().

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
id - a positive number
Returns:
the edge with given id, or null if not found

getEdge

Edge getEdge(java.lang.String id)
Returns the edge with identifier equals to id. If not found, returns null. This id is set by user and can be found at EdgeData.getId(). To set this Id, use Graph.setId().

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
id - the string identifier, unique
Returns:
the edge with given id, or null if not found

getEdge

Edge getEdge(Node node1,
             Node node2)
Finds and returns a directed or undirected edge that connects node1 and node2. Returns null if no such edge is found.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
node1 - the first incident node of the queried edge
node2 - thge second incident node of the queried edge
Returns:
an edge that connects node1 and node2 or null if no such edge exists
Throws:
java.lang.IllegalArgumentException - if node1 or node2 are null or not legal nodes in the graph

getNodes

NodeIterable getNodes()
Returns nodes contained in the graph.

Returns:
a node iterable of nodes contained in the graph.

getEdges

EdgeIterable getEdges()
Returns edges contained in the graph. Self-loops will be present only once.

If the graph is undirected, directed mutual edges will be present only once.

Returns:
an edge iterable of edges contained in the graph.

getNeighbors

NodeIterable getNeighbors(Node node)
Returns neighbors of node. Neighbors are nodes connected to node with any edge of the graph. Neighbors exclude node itself, therefore self-loops are ignored.

Parameters:
node - the node whose neighbors are to be returned
Returns:
a node iterable of node's neighbors
Throws:
java.lang.IllegalArgumentException - if node is null or not legal in the graph.

getEdges

EdgeIterable getEdges(Node node)
Returns edges incident to node.

For directed graph, note that self-loops are repeated only once. Undirected graphs repeats edges once by default.

Parameters:
node - the node whose incident edges are to be returned
Returns:
an edge iterable of edges incident to node
Throws:
java.lang.IllegalArgumentException - if node is null or not legal in the graph.

getNodeCount

int getNodeCount()
Returns the number of nodes in the graph.

Special case of interest:

Warning: This method is not thread safe, be sure to call it in a locked statement.

Returns:
the number of nodes in the graph

getEdgeCount

int getEdgeCount()
Returns the number of edges in the graph

Special case of interest:

Warning: This method is not thread safe, be sure to call it in a locked statement.

Returns:
the number of edges in the graph.

getNodeVersion

int getNodeVersion()
Return the current node version of the graph. When node structure is touched (i.e. add, remove...) the node version is incremented.

External modules can compare local copy of version to determine if update is necessary.

Returns:
the current node version of the graph

getEdgeVersion

int getEdgeVersion()
Return the current edge version of the graph. When edge structure is touched (i.e. add, remove...) the edge version is incremented.

External modules can compare local copy of version to determine if update is necessary.

Returns:
the current edge version of the graph

getOpposite

Node getOpposite(Node node,
                 Edge edge)
Returns the adjacent node of node through edge.

Parameters:
node - the node whose adjacent node is to be returned
edge - the edge whose the opposite node is to be returned
Returns:
the adjacent node of node through edge
Throws:
java.lang.IllegalArgumentException - if node or edge is null, or if node is not incident to edge

getDegree

int getDegree(Node node)
Returns the degree of node. Self-loops are counted twice for directed graphs.

Parameters:
node - the node whose degree is to be returned

Warning: This method is not thread safe, be sure to call it in a locked statement.

Returns:
the degree of node
Throws:
java.lang.IllegalArgumentException - if node is null or not legal in the graph

isSelfLoop

boolean isSelfLoop(Edge edge)
Returns true if edge is a self-loop.

Parameters:
edge - the edge to be queried
Returns:
true if edge is a self-loop, false otherwise
Throws:
java.lang.IllegalArgumentException - if edge is null or adjacent nodes not legal in the graph

isDirected

boolean isDirected(Edge edge)
Returns true if edge is a directed edge in the current graph. Always returns true when the graph is directed and false when the graph is undirected. In case of a mixed graph returns Edge.isDirected().

Parameters:
edge -
Returns:
true is edge is directed
Throws:
java.lang.IllegalArgumentException - if edge is null or adjacent nodes not legal in the graph

isAdjacent

boolean isAdjacent(Node node1,
                   Node node2)
Returns true if node1 is adjacent to node2. Is adjacent when an edge exists between node1 and node2.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
node1 - the first node to be queried
node2 - the seconde node to be queried
Returns:
true if node1 is adjacent to node2
Throws:
java.lang.IllegalArgumentException - if node1 or node2 is null of not legal in the graph

isAdjacent

boolean isAdjacent(Edge edge1,
                   Edge edge2)
Returns true if edge1 is adjacent to edge2. Is adjacent when an node is incident to both edges.

Warning: This method is not thread safe, be sure to call it in a locked statement.

Parameters:
edge1 - the first node to be queried
edge2 - the seconde node to be queried
Returns:
true if edge1 is adjacent to edge2
Throws:
java.lang.IllegalArgumentException - if edge1 or edge2 is null of not legal in the graph

clearEdges

void clearEdges(Node node)
Removes all edges incident to node.

Parameters:
node - the node whose edges is to be cleared
Throws:
java.lang.IllegalArgumentException - if node if null or not legal in the graph
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

clear

void clear()
Removes all nodes and edges in the graph.

Throws:
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

clearEdges

void clearEdges()
Removes all edges in the graph.

Throws:
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

setId

void setId(Node node,
           java.lang.String id)
Sets the string identifier of node. This identifier can be set by users, in contrario of Node.getId() which is set by the system.

Parameters:
id - the id that is to be set for node

setId

void setId(Edge edge,
           java.lang.String id)
Sets the string identifier of edge. This identifier can be set by users, in contrario of Edge.getId() which is set by the system.

Parameters:
id - the id that is to be set for edge

readLock

void readLock()
Acquires a read lock on the graph. Calling thread will be blocked until all write locks are released. Several threads can read but only once can write.

A read lock can be acquired several times by a thread, but be sure to call readUnlock() the same number of time you called this method, or use readUnlockAll() to release all locks.

See Also:
ReentrantReadWriteLock

readUnlock

void readUnlock()
Releases the read lock on the graph. Must be called from the same thread that locked the graph.

Use readUnlockAll() if you ignore the number of times the read lock has been acquired.


readUnlockAll

void readUnlockAll()
Safe method that releases all read locks the calling thread has acquired. Use this method if you are cancelling a task and you don't know how many read locks have been acquired.


writeLock

void writeLock()
Acquires a write lock on the graph. Calling thread will be blocked until all read locks are released. Several threads can read but only once can write.

Throws:
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock
See Also:
ReentrantReadWriteLock

writeUnlock

void writeUnlock()
Release the write lock on the graph. Must be called from the same thread that locked the graph.


getGraphModel

GraphModel getGraphModel()
Returns the graph model this graph belongs to.

Returns:
the graph model this graph belongs to.

getView

GraphView getView()
Returns the graph view this graph belongs to.

Returns:
the graph view this graph belongs to.

Gephi Toolkit Javadoc