uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.utils

Class GraphUtils

java.lang.Object

uk.ac.ebi.arrayexpress2.magetab.datamodel.graph.utils.GraphUtils

public class GraphUtils
extends Object

A class containing some useful utility methods for navigating graphs utilising the structures in uk.ac.ebi.arrayexpress2.magetab.datamodel.graph. The utility methods in this class are only guaranteed to work correctly on completely constructed graphs.

Author:

Tony Burdett

See Also:

uk.ac.ebi.arrayexpress2.magetab.datamodel.graph, SDRF, ADF

Constructor Summary

Constructors

Constructor and Description
GraphUtils()

Method Summary

Methods

Modifier and Type	Method and Description
static <T extends Node> Collection<T>	findDownstreamNodes(Node currentNode, Class<T> downstreamNodeType) Finds nodes downstream of the given node in the graph, searching for nodes of a particular type.
static Collection<? extends Node>	findDownstreamNodes(Node currentNode, String downstreamNodeType) Finds nodes downstream of the given node in the graph, searching for nodes of a particular type.
static <T extends Node> Collection<T>	findUpstreamNodes(Node currentNode, Class<T> upstreamNodeType) Finds nodes upstream of the given node in the graph, searching for nodes of a particular type.
static Collection<? extends Node>	findUpstreamNodes(Node currentNode, String upstreamNodeType) Finds nodes upstream of the given node in the graph, searching for nodes of a particular type.
static boolean	isDirectlyDownstream(Node currentNode, Node maybeDownstreamNode) Determine whether the query node, "maybeDownstreamNode", is downstream of the current node in the given SDRF graph.
static boolean	isDirectlyUpstream(Node currentNode, Node maybeUpstreamNode) Determine whether the query node, "maybeUpstreamNode", is upstream of the current node in the given graph.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GraphUtils

public GraphUtils()

Method Detail

findUpstreamNodes

public static <T extends Node> Collection<T> findUpstreamNodes(Node currentNode,
                                               Class<T> upstreamNodeType)

Finds nodes upstream of the given node in the graph, searching for nodes of a particular type. This returns all nodes upstream of the given node, of the supplied type - this includes both those directly upstream or those further hops away. So, for example, if you have nodes a (type A), b1 (type B), b2 (type B) and c (type C) and your graph looks like:

     a -> b1 -> b2 -> c
 

If you call findUpstreamNodes(sdrf, c, B.class); your answer will contain b1 and b2.

Note that this method will return a snapshot of the nodes currently upstream of the queried node if this method is called whilst the graph is being constructed. Even if you wish to do this, often results will be correct, except where pooling occurs upstream of the queried node from a node that has not yet been read.

Parameters:

currentNode - the current node - this method will locate all nodes upstream of this node

upstreamNodeType - the type of nodes you are interested in locating

Returns:

the collection of nodes, of the "upstreamNodeType" type, upstream of "currentNode"

findUpstreamNodes

public static Collection<? extends Node> findUpstreamNodes(Node currentNode,
                                           String upstreamNodeType)

Finds nodes upstream of the given node in the graph, searching for nodes of a particular type. This returns all nodes upstream of the given node, where the value of upstreamNode.getNodeType() equals the type specified. This includes both those directly upstream or those further hops away. So, for example, if you have nodes a (type A), b1 (type B), b2 (type B) and c (type C) and your graph looks like:

     a -> b1 -> b2 -> c
 

If you call findUpstreamNodes(sdrf, c, "B"); your answer will contain b1 and b2.

Note that this method will return a snapshot of the nodes currently upstream of the queried node if this method is called whilst the graph is being constructed. Even if you wish to do this, often results will be correct, except where pooling occurs upstream of the queried node from a node that has not yet been read.

Parameters:

currentNode - the current node - this method will locate all nodes upstream of this node

upstreamNodeType - the type of nodes you are interested in locating

Returns:

the collection of nodes, of the "upstreamNodeType" type, upstream of "currentNode"

findDownstreamNodes

public static <T extends Node> Collection<T> findDownstreamNodes(Node currentNode,
                                                 Class<T> downstreamNodeType)

Finds nodes downstream of the given node in the graph, searching for nodes of a particular type.

Note that if the graph is being actively constructed, there are no guarantees that this method will return the exhaustive set, but will rather return all nodes known to be downstream of the given node at the time of the query.

You should only use this method on completely constructed graphs, not during parsing. By the contract of the parser, the graph is built by reading from the leftmost column first, ending with the rightmost columns. Therefore, if you query for downstream nodes of a node currently being parsed, you are likely to get NullPointerExceptions or unexpected results.

Parameters:

currentNode - the current node - this method will locate all nodes downstream of this node

downstreamNodeType - the type of nodes you are interested in locating

Returns:

the collection of nodes, of the "downstreamNodeType" type, downstream of "currentNode"

findDownstreamNodes

public static Collection<? extends Node> findDownstreamNodes(Node currentNode,
                                             String downstreamNodeType)

Finds nodes downstream of the given node in the graph, searching for nodes of a particular type.

Note that if the graph is being actively constructed, there are no guarantees that this method will return the exhaustive set, but will rather return all nodes known to be downstream of the given node at the time of the query.

You should only use this method on completely constructed graphs, not during parsing. By the contract of the parser, the graph is built by reading from the leftmost column first, ending with the rightmost columns. Therefore, if you query for downstream nodes of a node currently being parsed, you are likely to get NullPointerExceptions or unexpected results.

Parameters:

currentNode - the current node - this method will locate all nodes downstream of this node

downstreamNodeType - the type of nodes you are interested in locating

Returns:

the collection of nodes, of the "downstreamNodeType" type, downstream of "currentNode"

isDirectlyUpstream

public static boolean isDirectlyUpstream(Node currentNode,
                         Node maybeUpstreamNode)

Determine whether the query node, "maybeUpstreamNode", is upstream of the current node in the given graph. This only takes into account nodes that are DIRECTLY upstream - if there is a node of the same type as the maybeUpstreamNode between it and the currentNode, this method returns false.

Parameters:

currentNode - the target node: determine whether the query node is upstream of this

maybeUpstreamNode - the node to assess

Returns:

true if "maybeUpstreamNode" is upstream of currentNode, false otherwise

isDirectlyDownstream

public static boolean isDirectlyDownstream(Node currentNode,
                           Node maybeDownstreamNode)

Determine whether the query node, "maybeDownstreamNode", is downstream of the current node in the given SDRF graph. This only takes into account nodes that are DIRECTLY downstream - if there is a node of the same type as the maybeDownstreamNode between it and the currentNode, this method returns false.

You should bear in mind when using this method DURING PARSING, that if you attempt to check nodes downstream of one that has just been parsed you may get null or erroneous results, as nodes are parsed from root to leaf of the tree. As such, just parsed nodes may have at most one level of children and not the complete branch as children.

Parameters:

currentNode - the target node: determine whether the query node is downstream of this

maybeDownstreamNode - the node to assess

Returns:

true if "maybeDownstreamNode" is downstream of currentNode, false otherwise