com.kuka.graph
Interface Graph<N,E>

Type Parameters:

N - the type of nodes contained in this graph

E - the type of edges contained in this graph

All Superinterfaces:

Iterable<N>

All Known Subinterfaces:

ListenableGraph<N,E>, Path<N,E>

All Known Implementing Classes:

AbstractBaseGraph, AbstractBaseListenableGraph, AbstractGraph, BasePath, DefaultGraph, FastUncheckedGraph, FastUncheckedPath, Subgraph, TransposeGraph

public interface Graph<N,E>
extends Iterable<N>

As implied by its name, this interface models the mathematical graph abstraction. A graph G(N,E) contains a set of nodes N and a set of edges E. Each edge e=(n1,n2) in E connects node n1 to node n2.

Method Summary

boolean	addAllEdges(Collection<E> edges) Adds all of the edges in the specified collection to this graph if they are not already present (optional operation).
boolean	addAllNodes(Collection<N> nodes) Adds all of the nodes in the specified collection to this graph if they are not already present (optional operation).
boolean	addEdge(E edge) Adds the specified edge to this graph if it is not already present (optional operation).
boolean	addNode(N node) Adds the specified node to this graph if it is not already present (optional operation).
void	clear() Removes all nodes and all edges from this graph (optional operation).
boolean	containsAllEdges(Collection<E> edges) Returns true if this graph contains all of the edges of the specified collection.
boolean	containsAllNodes(Collection<N> nodes) Returns true if this graph contains all of the nodes of the specified collection.
boolean	containsEdge(E edge) Returns true if this graph contains the specified edge.
boolean	containsEdge(N source, N target) Returns true if this graph contains the specified edge e=(source,target).
boolean	containsNode(N node) Returns true if this graph contains the specified node.
E	createEdge(N source, N target) Creates a new edge from the specified source node to the target node, adds it to this graph and returns the created edge.
N	createNode() Creates a new node, adds it to this graph and returns the created node.
Set<E>	edges() Returns an unmodifiable Set view of the edges contained in this graph.
Set<E>	edges(GraphElementFilter<? super E> filter) Returns an unmodifiable Set view of the edges contained in this graph that satisfy the specified filter.
int	edgeSize() Returns the number of edges in this graph, i.e. the cardinality of the set of edges.
E	getEdge(N source, N target) Returns the edge e=(source,target) from the specified source node to the target node, or null if this graph contains no such edge.
Set<E>	incomingEdges(N node) Returns the set of all incoming edges of the specified node.
boolean	isEmpty() Returns true if this graph contains no elements.
Set<N>	neighbors(N node) Returns the set of all neighbors of the specified node.
Set<N>	nodes() Returns an unmodifiable Set view of the nodes contained in this graph.
Set<N>	nodes(GraphElementFilter<? super N> filter) Returns an unmodifiable Set view of the nodes contained in this graph that satisfy the specified filter.
int	nodeSize() Returns the number of nodes in this graph, i.e. the cardinality of the set of nodes.
Set<E>	outgoingEdges(N node) Returns the set of all outgoing edges of the specified node.
boolean	removeAllEdges(Collection<E> edges) Removes from this graph all of its edges that are contained in the specified collection (optional operation).
boolean	removeAllNodes(Collection<N> nodes) Removes from this graph all of its nodes that are contained in the specified collection (optional operation).
boolean	removeEdge(E edge) Removes the specified edge e from this graph if it is present (optional operation).
boolean	removeEdge(N source, N target) Removes the edge e=(source,target) connecting the specified source and target node from this graph if it is present (optional operation).
boolean	removeNode(N node) Removes the specified node n from this graph if it is present (optional operation).
boolean	retainAllEdges(Collection<E> edges) Retains only the edges in this graph that are contained in the specified collection (optional operation).
boolean	retainAllNodes(Collection<N> nodes) Retains only the nodes in this graph that are contained in the specified collection (optional operation).

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

nodeSize

int nodeSize()

Returns the number of nodes in this graph, i.e. the cardinality of the set of nodes. If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of nodes in this graph

edgeSize

int edgeSize()

Returns the number of edges in this graph, i.e. the cardinality of the set of edges. If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of edges in this graph

isEmpty

boolean isEmpty()

Returns true if this graph contains no elements.

Returns:

true if this graph contains no elements

containsNode

boolean containsNode(N node)

Returns true if this graph contains the specified node. More formally, returns true if and only if this graph contains a node n* such that node.equals(n*).

Parameters:

node - node whose presence in this graph is to be tested

Returns:

true if this graph contains the specified node

Throws:

NullPointerException - if the specified node is null (optional)

containsEdge

boolean containsEdge(E edge)

Returns true if this graph contains the specified edge. More formally, returns true if and only if this graph contains an edge e* such that edge.equals(e*).

Parameters:

edge - edge whose presence in this graph is to be tested

Returns:

true if this graph contains the specified edge

Throws:

NullPointerException - if the specified edge is null (optional)

containsEdge

boolean containsEdge(N source,
                     N target)

Returns true if this graph contains the specified edge e=(source,target). More formally, returns true if and only if this graph contains an edge e* such that e.equals(e*).

Parameters:

source - the source node of the edge whose presence in this graph is to be tested

target - the target node of the edge whose presence in this graph is to be tested

Returns:

true if this graph contains the specified edge (source,target)

Throws:

NullPointerException - if the specified source node or target node is null (optional)

containsAllNodes

boolean containsAllNodes(Collection<N> nodes)

Returns true if this graph contains all of the nodes of the specified collection. If the specified collection is a set, this method returns true if it is a subset of the node set of this graph.

Parameters:

nodes - collection of nodes to be checked for containment in this graph

Returns:

true if this graph contains all of the nodes of the specified collection

Throws:

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

containsNode(Object)

containsAllEdges

boolean containsAllEdges(Collection<E> edges)

Returns true if this graph contains all of the edges of the specified collection. If the specified collection is a set, this method returns true if it is a subset of the edge set of this graph.

Parameters:

edges - collection of edges to be checked for containment in this graph

Returns:

true if this graph contains all of the edges of the specified collection

Throws:

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

containsEdge(Object)

nodes

Set<N> nodes()

Returns an unmodifiable Set view of the nodes contained in this graph. The set is backed by the graph, so changes to the graph are reflected in the set. If the graph is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:

a set view of the nodes contained in this graph

nodes

Set<N> nodes(GraphElementFilter<? super N> filter)

Returns an unmodifiable Set view of the nodes contained in this graph that satisfy the specified filter. The behavior of this method is the same as that of the nodes() method, except that the nodes in the returned set must satisfy the filter and the set is not backed by the graph, i.e. changes to the graph are not reflected in the set. If the given filter is null then all nodes are accepted. Otherwise, a node satisfies the filter if and only if the value true results when the GraphElementFilter.accept(E) method of the filter is invoked on the node.

Parameters:

filter - a node filter

Returns:

a set view of the nodes contained in this graph that satisfy the specified filter

edges

Set<E> edges()

Returns an unmodifiable Set view of the edges contained in this graph. The set is backed by the graph, so changes to the graph are reflected in the set. If the graph is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:

a set view of the edges contained in this graph

edges

Set<E> edges(GraphElementFilter<? super E> filter)

Returns an unmodifiable Set view of the edges contained in this graph that satisfy the specified filter. The behavior of this method is the same as that of the edges() method, except that the edges in the returned set must satisfy the filter and the set is not backed by the graph, i.e. changes to the graph are not reflected in the set. If the given filter is null then all edges are accepted. Otherwise, an edge satisfies the filter if and only if the value true results when the GraphElementFilter.accept(E) method of the filter is invoked on the edge.

Parameters:

filter - an edge filter

Returns:

a set view of the edges contained in this graph that satisfy the specified filter

getEdge

E getEdge(N source,
          N target)

Returns the edge e=(source,target) from the specified source node to the target node, or null if this graph contains no such edge.

More formally, if this graph contains an edge e* such that e.equals(e*), where e=(source,target), then this method returns e*, otherwise it returns null.

Parameters:

source - the source node of the edge that is to be returned

target - the target node of the edge that is to be returned

Returns:

the the edge from the specified source node to the target node, or null if this graph contains no such edge

Throws:

NullPointerException - if the specified source node or target node is null (optional)

outgoingEdges

Set<E> outgoingEdges(N node)

Returns the set of all outgoing edges of the specified node. If no such edge exists, then the returned set is empty.

More formally, this method returns all edges e in this graph such that the given node is the source node of e, i.e. e=(node,*).

Parameters:

node - the source node

Returns:

the set of all edges with the given node as source

Throws:

NullPointerException - if the specified node is null (optional)

incomingEdges

Set<E> incomingEdges(N node)

Returns the set of all incoming edges of the specified node. If no such edge exists, then the returned set is empty.

More formally, this method returns all edges e in this graph such that the given node is the target node of e, i.e. e=(*,node).

Parameters:

node - the target node

Returns:

the set of all edges with the given node as target

Throws:

NullPointerException - if the specified node is null (optional)

neighbors

Set<N> neighbors(N node)

Returns the set of all neighbors of the specified node. If no such node exists, the the returned set is empty.

Parameters:

node - the node of which all neighboring nodes are to be returned

Returns:

the set of all neighbors of the given node

Throws:

NullPointerException - if the specified node is null (optional)

createNode

N createNode()

Creates a new node, adds it to this graph and returns the created node.

Returns:

the created node

Throws:

UnsupportedOperationException - if the createNode operation is not supported by this graph

createEdge

E createEdge(N source,
             N target)

Creates a new edge from the specified source node to the target node, adds it to this graph and returns the created edge. If graph does not contain the specified nodes they are added, too.

Parameters:

source - the source node of the edge that is to be created

target - the target node of the edge that is to be created

Returns:

the created edge

Throws:

UnsupportedOperationException - if the createEdge operation is not supported by this graph

NullPointerException - if the specified source or target node is null

IllegalArgumentException - if some property of the specified nodes prevents them from being added to this graph

addNode

boolean addNode(N node)

Adds the specified node to this graph if it is not already present (optional operation).

More formally, adds the specified node n to this graph if the graph contains no element n2 such that n.equals(n2)) . If this graph already contains the element, the call leaves the graph unchanged and returns false.

Parameters:

node - node to be added to this graph

Returns:

true if this graph did not already contain the specified node

Throws:

UnsupportedOperationException - if the addNode operation is not supported by this graph

NullPointerException - if the specified node is null

IllegalArgumentException - if some property of the specified node prevents it from being added to this graph

addEdge

boolean addEdge(E edge)

Adds the specified edge to this graph if it is not already present (optional operation).

More formally, adds the specified edge e to this graph if the graph contains no element e2 such that e.equals(e2)) . If this graph already contains the element, the call leaves the graph unchanged and returns false.

Parameters:

edge - edge to be added to this graph

Returns:

true if this graph did not already contain the specified edge

Throws:

UnsupportedOperationException - if the addEdge operation is not supported by this graph

NullPointerException - if the specified edge is null

IllegalArgumentException - if some property of the specified edge prevents it from being added to this graph

addAllNodes

boolean addAllNodes(Collection<N> nodes)

Adds all of the nodes in the specified collection to this graph if they are not already present (optional operation).

If the specified collection is a set, the addAllNodes operation effectively modifies the set of nodes so that its value is the union of the two sets. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

nodes - collection containing nodes to be added to this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the addAllNodes operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null

IllegalArgumentException - if some property of a node in the specified collection prevents it from being added to this graph

See Also:

addNode(Object)

addAllEdges

boolean addAllEdges(Collection<E> edges)

Adds all of the edges in the specified collection to this graph if they are not already present (optional operation).

If the specified collection is a set, the addAllEdges operation effectively modifies the set of edges so that its value is the union of the two sets. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

edges - collection containing edges to be added to this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the addAllEdges operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null

IllegalArgumentException - if some property of an edge in the specified collection prevents it from being added to this graph

See Also:

addEdge(Object)

removeNode

boolean removeNode(N node)

Removes the specified node n from this graph if it is present (optional operation).

More formally, removes a node n* such that n.equals(n*) , if this graph contains such a node. Furthermore, all edges incident to this node are removed. Returns true if this graph contained the node (or equivalently, if this graph changed as a result of the call).

Parameters:

node - node to be removed from this graph, if present

Returns:

true if this graph contained the specified node

Throws:

NullPointerException - if the specified node is null (optional)

UnsupportedOperationException - if the removeNode operation is not supported by this graph

removeEdge

boolean removeEdge(E edge)

Removes the specified edge e from this graph if it is present (optional operation).

More formally, removes an edge e* such that e.equals(e*), if this graph contains such an edge. Returns true if this graph contained the edge (or equivalently, if this graph changed as a result of the call).

Parameters:

edge - edge to be removed from this graph, if present

Returns:

true if this graph contained the specified edge

Throws:

NullPointerException - if the specified edge is null (optional)

UnsupportedOperationException - if the removeEdge operation is not supported by this graph

removeEdge

boolean removeEdge(N source,
                   N target)

Removes the edge e=(source,target) connecting the specified source and target node from this graph if it is present (optional operation).

More formally, removes an edge e* such that e.equals(e*), where e=(source,target), if this graph contains such an edge. Returns true if this graph contained the edge (or equivalently, if this graph changed as a result of the call).

Parameters:

source - the source node of the edge that is to be removed

target - the target node of the edge that is to be removed

Returns:

true if this graph contained the specified edge

Throws:

NullPointerException - if the specified source node or target node is null (optional)

UnsupportedOperationException - if the removeEdge operation is not supported by this graph

removeAllNodes

boolean removeAllNodes(Collection<N> nodes)

Removes from this graph all of its nodes that are contained in the specified collection (optional operation).

If the specified collection is a set, this operation effectively modifies the set of nodes so that its value is the asymmetric set difference of the two sets.

Parameters:

nodes - collection containing nodes to be removed from this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the removeAllNodes operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

removeNode(Object)

removeAllEdges

boolean removeAllEdges(Collection<E> edges)

Removes from this graph all of its edges that are contained in the specified collection (optional operation).

If the specified collection is a set, this operation effectively modifies the set of edges so that its value is the asymmetric set difference of the two sets.

Parameters:

edges - collection containing edges to be removed from this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the removeAllEdges operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

removeEdge(Object)

retainAllNodes

boolean retainAllNodes(Collection<N> nodes)

Retains only the nodes in this graph that are contained in the specified collection (optional operation).

In other words, removes from this graph all of its nodes that are not contained in the specified collection. If the specified collection is a set, this operation effectively modifies the set of nodes so that its value is the intersection of the two sets.

Parameters:

nodes - collection containing nodes to be retained in this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the retainAllNodes operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

removeNode(Object), removeAllNodes(Collection)

retainAllEdges

boolean retainAllEdges(Collection<E> edges)

Retains only the edges in this graph that are contained in the specified collection (optional operation).

In other words, removes from this graph all of its edges that are not contained in the specified collection. If the specified collection is a set, this operation effectively modifies the set of edges so that its value is the intersection of the two sets.

Parameters:

edges - collection containing edges to be retained in this graph

Returns:

true if this graph changed as a result of the call

Throws:

UnsupportedOperationException - if the retainAllEdges operation is not supported by this graph

NullPointerException - if the specified collection contains one or more null elements, or if the specified collection is null (optional)

See Also:

removeEdge(Object), removeAllEdges(Collection)

clear

void clear()

Removes all nodes and all edges from this graph (optional operation). The graph will be empty after this call returns.

Throws:

UnsupportedOperationException - if the clear method is not supported by this graph