cytoscape.graph.dynamic
Interface DynamicGraph

All Superinterfaces:

FixedGraph

All Known Implementing Classes:

CytoscapeFingRootGraph, FingExtensibleRootGraph

public interface DynamicGraph
extends FixedGraph

A graph whose topology can be modified. Edges and nodes are non-negative integers; a given node and a given edge in a single graph can be the same integer.

Field Summary

static byte	DIRECTED_EDGE A nonnegative quantity representing directedness of an edge.
static byte	UNDIRECTED_EDGE A nonnegative quantity representing undirectedness of an edge.

Method Summary

int	edgeCreate(int sourceNode, int targetNode, boolean directed) Creates a new edge in this graph, having source node, target node, and directedness specified.
boolean	edgeRemove(int edge) Removes the specified edge from this graph.
IntEnumerator	edges() Returns an enumeration of all edges currently in this graph.
IntEnumerator	edgesAdjacent(int node, boolean outgoing, boolean incoming, boolean undirected) Returns a non-repeating enumeration of edges adjacent to a node.
IntIterator	edgesConnecting(int node0, int node1, boolean outgoing, boolean incoming, boolean undirected) Returns a non-repeating iteration of edges connecting two nodes.
int	edgeSource(int edge) Determines the source node of an edge.
int	edgeTarget(int edge) Determines the target node of an edge.
byte	edgeType(int edge) Determines the existence and directedness of an edge.
int	nodeCreate() Creates a new node in this graph.
boolean	nodeExists(int node) Determines whether or not a node exists in this graph.
boolean	nodeRemove(int node) Removes the specified node from this graph.
IntEnumerator	nodes() Returns an enumeration of all nodes currently in this graph.

Field Detail

DIRECTED_EDGE

static final byte DIRECTED_EDGE

A nonnegative quantity representing directedness of an edge.

See Also:

Constant Field Values

UNDIRECTED_EDGE

static final byte UNDIRECTED_EDGE

A nonnegative quantity representing undirectedness of an edge.

See Also:

Constant Field Values

Method Detail

nodes

IntEnumerator nodes()

Returns an enumeration of all nodes currently in this graph. Every node in this graph is a unique non-negative integer. A given node and a given edge in one graph may be the same integer.

The returned enumeration becomes invalid as soon as any graph-topology-modifying method on this graph is called. Calling methods on an invalid enumeration will result in undefined behavior of that enumeration. Enumerating through a graph's nodes will never have any effect on the graph.

Specified by:

nodes in interface FixedGraph

Returns:

an enumeration over all nodes currently in this graph; null is never returned.

edges

IntEnumerator edges()

Returns an enumeration of all edges currently in this graph. Every edge in this graph is a unique non-negative integer. A given node and a given edge in one graph may be the same integer.

The returned enumeration becomes invalid as soon as any graph-topology-modifying method on this graph is called. Calling methods on an invalid enumeration will result in undefined behavior of that enumeration. Enumerating through a graph's edges will never have any effect on the graph.

Specified by:

edges in interface FixedGraph

Returns:

an enumeration over all edges currently in this graph; null is never returned.

nodeCreate

int nodeCreate()

Creates a new node in this graph. Returns the new node. Nodes are always non-negative.

Implementations may create nodes with arbitrarily large values. Even if implementations initially create nodes with small values, nodes may take ever-increasing values when nodes are continually being removed and created. Or, implementations may choose to re-use node values as nodes are removed and added again.

Returns:

the newly created node.

nodeRemove

boolean nodeRemove(int node)

Removes the specified node from this graph. Returns true if and only if the specified node was in this graph at the time this method was called. A return value of true implies that the specified node has been successfully removed from this graph.

Note that removal of a node necessitates the removal of any edge touching that node.

Parameters:

node - the node that is to be removed from this graph.

Returns:

true if and only if the specified node existed in this graph at the time this operation was started.

edgeCreate

int edgeCreate(int sourceNode,
               int targetNode,
               boolean directed)

Creates a new edge in this graph, having source node, target node, and directedness specified. Returns the new edge, or -1 if either the source or target node does not exist in this graph. Edges are always non-negative.

Implementations may create edges with arbitrarily large values. Even if implementations initially create edges with small values, edges may take ever-increasing values when edges are continually being removed and created. Or, implementations may choose to re-use edge values as edges are removed and added again.

Parameters:

sourceNode - the source node that the new edge is to have.

targetNode - the target node that the new edge is to have.

directed - the new edge will be directed if and only if this value is true.

Returns:

the newly created edge or -1 if either the source or target node specified does not exist in this graph.

edgeRemove

boolean edgeRemove(int edge)

Removes the specified edge from this graph. Returns true if and only if the specified edge was in this graph at the time this method was called. A return value of true implies that the specified edge has been successfully removed from this graph.

Note that removing an edge does not cause that edge's endpoint nodes to be removed from this graph.

Parameters:

edge - the edge that is to be removed from this graph.

Returns:

true if and only if the specified edge existed in this graph at the time this operation was started.

nodeExists

boolean nodeExists(int node)

Determines whether or not a node exists in this graph. Returns true if and only if the node specified exists.

Note that this method is superfluous in this interface (that is, it could be removed without losing any functionality), because edgesAdjacent(int, boolean, boolean, boolean) can be used to test the presence of a node. However, because nodeExists(int) does not return a complicated object, its performance may be better than that of edgesAdjacent().

Specified by:

nodeExists in interface FixedGraph

Parameters:

node - the [potentially existing] node in this graph whose existence we're querying.

Returns:

the existence of specified node in this graph.

edgeType

byte edgeType(int edge)

Determines the existence and directedness of an edge. Returns -1 if specified edge does not exist in this graph, otherwise returns DIRECTED_EDGE or UNDIRECTED_EDGE.

Specified by:

edgeType in interface FixedGraph

Parameters:

edge - the edge in this graph whose existence and/or directedness we're seeking.

Returns:

DIRECTED_EDGE if specified edge is directed, UNDIRECTED_EDGE if specified edge is undirected, and -1 if specified edge does not exist in this graph.

edgeSource

int edgeSource(int edge)

Determines the source node of an edge. Returns the source node of specified edge or -1 if specified edge does not exist in this graph.

Specified by:

edgeSource in interface FixedGraph

Parameters:

edge - the edge in this graph whose source node we're seeking.

Returns:

the source node of specified edge or -1 if specified edge does not exist in this graph.

edgeTarget

int edgeTarget(int edge)

Determines the target node of an edge. Returns the target node of specified edge or -1 if specified edge does not exist in this graph.

Specified by:

edgeTarget in interface FixedGraph

Parameters:

edge - the edge in this graph whose target node we're seeking.

Returns:

the target node of specified edge or -1 if specified edge does not exist in this graph.

edgesAdjacent

IntEnumerator edgesAdjacent(int node,
                            boolean outgoing,
                            boolean incoming,
                            boolean undirected)

Returns a non-repeating enumeration of edges adjacent to a node. The three boolean input parameters define what is meant by "adjacent edge". If all three boolean input parameters are false, the returned enumeration will have zero elements.

The returned enumeration becomes invalid as soon as any graph-topology-modifying method on this graph is called. Calling methods on an invalid enumeration will result in undefined behavior of that enumeration.

This method returns null if and only if the specified node does not exist in this graph. Therefore, this method can be used to test the existence of a node in this graph.

Specified by:

edgesAdjacent in interface FixedGraph

Parameters:

node - the node in this graph whose adjacent edges we're seeking.

outgoing - all directed edges whose source is the node specified are included in the returned enumeration if this value is true; otherwise, not a single such edge is included in the returned enumeration.

incoming - all directed edges whose target is the node specified are included in the returned enumeration if this value is true; otherwise, not a single such edge is included in the returned enumeration.

undirected - all undirected edges touching the specified node are included in the returned enumeration if this value is true; otherwise, not a single such edge is included in the returned enumeration.

Returns:

an enumeration of edges adjacent to the node specified or null if specified node does not exist in this graph.

edgesConnecting

IntIterator edgesConnecting(int node0,
                            int node1,
                            boolean outgoing,
                            boolean incoming,
                            boolean undirected)

Returns a non-repeating iteration of edges connecting two nodes. The three boolean input parameters define what is meant by "connecting edge". If all three boolean input parameters are false, the returned iteration will have no elements.

The returned iteration becomes invalid as soon as any graph-topology-modifying method on this graph is called. Calling methods on an invalid iteration will result in undefined behavior of that iteration.

I'd like to discuss the motivation behind this interface method. I assume that most implementations of this interface will implement this method in terms of edgesAdjacent(). Why, then, is this method necessary? Because some implementations may choose to optimize the implementation of this method by using a search tree or a hashtable, for example. This method is a hook to provide such optimization.

This method returns an IntIterator as opposed to an IntEnumerator so that non-optimized implementations would not be required to pre-compute the number of edges being returned.

Specified by:

edgesConnecting in interface FixedGraph

Parameters:

node0 - one of the nodes in this graph whose connecting edges we're seeking.

node1 - one of the nodes in this graph whose connecting edges we're seeking.

outgoing - all directed edges whose source is node0 and whose target is node1 are included in the returned iteration if this value is true; otherwise, not a single such edge is included in the returned iteration.

incoming - all directed edges whose source is node1 and whose target is node0 are included in the returned iteration if this value is true; otherwise, not a single such edge is included in the returned iteration.

undirected - all undirected edges E such that E's endpoints are node0 and node1 are included in the returned iteration if this value is true; otherwise, not a single such edge is incuded in the returned iteration.

Returns:

an iteration of edges connecting node0 with node1 in a fashion specified by boolean input parameters or null if either of node0 or node1 does not exist in this graph.