Package org.jenkinsci.plugins.workflow.graphanalysis

Class LinearScanner

java.lang.Object

org.jenkinsci.plugins.workflow.graphanalysis.AbstractFlowScanner

org.jenkinsci.plugins.workflow.graphanalysis.LinearScanner

All Implemented Interfaces:

Iterable<FlowNode>, Iterator<FlowNode>, Filterator<FlowNode>

Direct Known Subclasses:

LinearBlockHoppingScanner

@NotThreadSafe
public class LinearScanner
extends AbstractFlowScanner

Scans through the flow graph in strictly linear fashion, visiting only the first branch in parallel blocks.

Iteration order: depth-ONLY, meaning we walk through parents and only follow the first parent of each FlowNode This means that where are parallel branches, we will only visit a partial set of FlowNodes in the directed acyclic graph.

Use case: we don't care about parallel branches or know they don't exist, we just want to walk through the top-level blocks.

This is the fastest and simplest way to walk a flow, because you only care about a single node at a time. Nuance: where there are multiple parent nodes (in a parallel block), and one is denylisted, we'll find the first non-denylisted one.

Author:

Sam Van Oort

Field Summary

Fields inherited from class org.jenkinsci.plugins.workflow.graphanalysis.AbstractFlowScanner

MAX_LIST_CHECK_SIZE, myBlackList, myCurrent, myNext

Constructor Summary

Constructors

Constructor	Description
LinearScanner()

Method Summary

Modifier and Type	Method	Description
List<FlowNode>	filteredNodes(Collection<FlowNode> heads, com.google.common.base.Predicate<FlowNode> matchPredicate)	Deprecated. prefer AbstractFlowScanner.filteredNodes(FlowNode, Predicate)
List<FlowNode>	filteredNodes(Collection<FlowNode> heads, Collection<FlowNode> blackList, com.google.common.base.Predicate<FlowNode> matchCondition)	Return a filtered list of FlowNodes matching a condition, in the order encountered.
FlowNode	findFirstMatch(Collection<FlowNode> heads, com.google.common.base.Predicate<FlowNode> matchPredicate)	Deprecated. prefer AbstractFlowScanner.findFirstMatch(FlowNode, Predicate)
FlowNode	findFirstMatch(Collection<FlowNode> heads, Collection<FlowNode> blackListNodes, com.google.common.base.Predicate<FlowNode> matchCondition)	Find the first FlowNode within the iteration order matching a given condition Includes null-checking on arguments to allow directly calling with unchecked inputs (simplifies use).
FlowNode	findFirstMatch(FlowExecution exec, com.google.common.base.Predicate<FlowNode> matchPredicate)	Deprecated. unsafe to call
protected FlowNode	next(FlowNode current, Collection<FlowNode> blackList)	Actual meat of the iteration, get the next node to visit, using and updating state as needed
protected void	reset()	Reset internal state so that we can begin walking a new flow graph Public APIs need to invoke this before searches
protected void	setHeads(Collection<FlowNode> heads)	Set up to begin flow scanning using the filteredHeads as starting points This method makes several assumptions: - AbstractFlowScanner.reset() has already been invoked to reset state - filteredHeads has already had any points in AbstractFlowScanner.myBlackList removed - none of the filteredHeads are null
boolean	setup(Collection<FlowNode> heads)	Deprecated. prefer AbstractFlowScanner.setup(FlowNode)
boolean	setup(Collection<FlowNode> heads, Collection<FlowNode> blackList)	Deprecated. prefer AbstractFlowScanner.setup(FlowNode, Collection)
void	visitAll(Collection<FlowNode> heads, Collection<FlowNode> blackList, FlowNodeVisitor visitor)	Given a FlowNodeVisitor, invoke FlowNodeVisitor.visit(FlowNode) on each node and halt early if it returns false.
void	visitAll(Collection<FlowNode> heads, FlowNodeVisitor visitor)	Syntactic sugar for AbstractFlowScanner.visitAll(Collection, Collection, FlowNodeVisitor) where we don't denylist any nodes

Methods inherited from class org.jenkinsci.plugins.workflow.graphanalysis.AbstractFlowScanner

allNodes, allNodes, convertToFastCheckable, filter, filteredNodes, filteredNodes, findFirstMatch, hasNext, iterator, next, remove, setup, setup

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.util.Iterator

forEachRemaining

Constructor Details

LinearScanner

public LinearScanner()

Method Details

reset

protected void reset()

Description copied from class: AbstractFlowScanner

Reset internal state so that we can begin walking a new flow graph Public APIs need to invoke this before searches

Specified by:

reset in class AbstractFlowScanner

setHeads

protected void setHeads(@NonNull
 Collection<FlowNode> heads)

Set up to begin flow scanning using the filteredHeads as starting points This method makes several assumptions: - AbstractFlowScanner.reset() has already been invoked to reset state - filteredHeads has already had any points in AbstractFlowScanner.myBlackList removed - none of the filteredHeads are null

Specified by:

setHeads in class AbstractFlowScanner

Parameters:

heads - Head nodes that have been filtered against denyList. Do not pass multiple heads.

next

protected FlowNode next(@CheckForNull
 FlowNode current,
 @NonNull
 Collection<FlowNode> blackList)

Description copied from class: AbstractFlowScanner

Actual meat of the iteration, get the next node to visit, using and updating state as needed

Specified by:

next in class AbstractFlowScanner

Parameters:

current - Current node to use in generating next value

blackList - Nodes that are not eligible for visiting

Returns:

Next node to visit, or null if we've exhausted the node list

filteredNodes

@Deprecated
@NonNull
public List<FlowNode> filteredNodes(Collection<FlowNode> heads,
 @NonNull
 com.google.common.base.Predicate<FlowNode> matchPredicate)

Deprecated.

prefer AbstractFlowScanner.filteredNodes(FlowNode, Predicate)

Syntactic sugar for AbstractFlowScanner.filteredNodes(Collection, Collection, Predicate) with no denyList nodes

Overrides:

filteredNodes in class AbstractFlowScanner

filteredNodes

@NonNull
public List<FlowNode> filteredNodes(Collection<FlowNode> heads,
 Collection<FlowNode> blackList,
 com.google.common.base.Predicate<FlowNode> matchCondition)

Return a filtered list of FlowNodes matching a condition, in the order encountered. Includes null-checking on arguments to allow directly calling with unchecked inputs (simplifies use).

Overrides:

filteredNodes in class AbstractFlowScanner

Parameters:

heads - Nodes to start iterating backward from by visiting their parents. Do not pass multiple heads.

blackList - Nodes we may not visit or walk beyond.

matchCondition - Predicate that must be met for nodes to be included in output. Input is always non-null.

Returns:

List of flownodes matching the predicate.

findFirstMatch

@Deprecated
public FlowNode findFirstMatch(Collection<FlowNode> heads,
 @NonNull
 com.google.common.base.Predicate<FlowNode> matchPredicate)

Deprecated.

prefer AbstractFlowScanner.findFirstMatch(FlowNode, Predicate)

Syntactic sugar for AbstractFlowScanner.findFirstMatch(Collection, Collection, Predicate) where there is no denyList

Overrides:

findFirstMatch in class AbstractFlowScanner

findFirstMatch

public FlowNode findFirstMatch(Collection<FlowNode> heads,
 Collection<FlowNode> blackListNodes,
 com.google.common.base.Predicate<FlowNode> matchCondition)

Find the first FlowNode within the iteration order matching a given condition Includes null-checking on arguments to allow directly calling with unchecked inputs (simplifies use).

Overrides:

findFirstMatch in class AbstractFlowScanner

Parameters:

heads - Head nodes to start walking from. Do not pass multiple heads.

blackListNodes - Nodes that are never visited, search stops here (bound is exclusive). If you want to create an inclusive bound, just use a node's parents.

matchCondition - Predicate to match when we've successfully found a given node type

Returns:

First matching node, or null if no matches found

visitAll

public void visitAll(Collection<FlowNode> heads,
 @NonNull
 FlowNodeVisitor visitor)

Syntactic sugar for AbstractFlowScanner.visitAll(Collection, Collection, FlowNodeVisitor) where we don't denylist any nodes

Overrides:

visitAll in class AbstractFlowScanner

Parameters:

heads - Do not pass multiple heads.

visitAll

public void visitAll(Collection<FlowNode> heads,
 Collection<FlowNode> blackList,
 @NonNull
 FlowNodeVisitor visitor)

Given a FlowNodeVisitor, invoke FlowNodeVisitor.visit(FlowNode) on each node and halt early if it returns false. Includes null-checking on all but the visitor, to allow directly calling with unchecked inputs (simplifies use). Useful if you wish to collect some information from every node in the FlowGraph. To do that, accumulate internal state in the visitor, and invoke a getter when complete.

Overrides:

visitAll in class AbstractFlowScanner

Parameters:

heads - Nodes to start walking the DAG backwards from. Do not pass multiple heads.

blackList - Nodes we can't visit or pass beyond.

visitor - Visitor that will see each FlowNode encountered.

findFirstMatch

@Deprecated
public FlowNode findFirstMatch(FlowExecution exec,
 @NonNull
 com.google.common.base.Predicate<FlowNode> matchPredicate)

Deprecated.

unsafe to call

Syntactic sugar for AbstractFlowScanner.findFirstMatch(Collection, Collection, Predicate) using FlowExecution.getCurrentHeads() to get heads and no denyList

Overrides:

findFirstMatch in class AbstractFlowScanner

setup

@Deprecated
public boolean setup(Collection<FlowNode> heads)

Deprecated.

prefer AbstractFlowScanner.setup(FlowNode)

Helper: version of AbstractFlowScanner.setup(Collection, Collection) where we don't have any nodes to denylist

Overrides:

setup in class AbstractFlowScanner

setup

@Deprecated
public boolean setup(Collection<FlowNode> heads,
 Collection<FlowNode> blackList)

Deprecated.

prefer AbstractFlowScanner.setup(FlowNode, Collection)

Set up for iteration/analysis on a graph of nodes, initializing the internal state Includes null-checking on arguments to allow directly calling with unchecked inputs (simplifies use).

Overrides:

setup in class AbstractFlowScanner

Parameters:

heads - The head nodes we start walking from (the most recently executed nodes, i.e. FlowExecution.getCurrentHeads()

blackList - Nodes that we cannot visit or walk past (useful to limit scanning to only nodes after a specific point)

Returns:

True if we can have nodes to work with, otherwise false