Package org.jenkinsci.plugins.workflow.graphanalysis

Provides a library of methods to work with and analyze the graph of FlowNodes produced from a pipeline execution.

The core APIs are described in the javadocs for AbstractFlowScanner But in general it provides for iteration through the Directed Acyclic Graph (DAG) of a flow, filtering, search for matches, and visiting all nodes via internal iteration.

Static methods and a few implementations are also provided in FlowScanningUtils.

How To Pick A FlowScanner For Iteration

1. Want fast iteration, don't care about visiting every node or parallels? LinearScanner
2. Visit every node as fast as possible? DepthFirstScanner
3. Visit every block in a predictable order, from end to start? ForkScanner
4. Fastest way to find preceding sibling or enclosing nodes? LinearBlockHoppingScanner

Methods to iterate through flow graph and break it into chunks (regions) of interest, with nesting possible and reporting of branches:

Basic APIs

1. ChunkFinder - API to define conditions for starting/ending a chunk
2. SimpleChunkVisitor - Visitor API that accepts callbacks for chunk boundaries/contenst + parallel branching
3. FlowChunk - A region of interest, defined by its first and last nodes
4. FlowChunkWithContext - A FlowChunk that knows about the nodes before/after it, to give context for determining success/failure and the time taken to execute

Data structures and implementations:

• MemoryFlowChunk - A FlowChunkWithContext that just directly stores FlowNodes
• ParallelFlowChunk
• ParallelMemoryFlowChunk
• StandardChunkVisitor - a basic concrete implementation of SimpleChunkVisitor that tracks one chunk at a time (no nesting) and runs a callback when the chunk is done
• LabelledChunkFinder - ChunkFinder that matches against nodes with a label
• BlockChunkFinder - ChunkFinder that creates chunks from blocks

Interface Summary

Interface	Description
ChunkFinder	Think of this as setting conditions to mark a region of interest in the graph of FlowNode from a FlowExecution.
Filterator<T>	Iterator that may be navigated through a filtered wrapper.
FlowChunk	Common container interface for a series of FlowNodes with a logical start and end.
FlowChunkWithContext	FlowChunk with information about what comes before/after
FlowNodeVisitor	Interface used when examining a pipeline FlowNode graph node by node, and terminating when a condition is met
ParallelFlowChunk<ChunkType extends FlowChunk>	FlowChunk mapping to the block from a Parallel step (with parallel branches inside)
SimpleChunkVisitor	This visitor's callbacks are invoked as we walk through a pipeline flow graph, and it splits it into chunks.

Class Summary

Class	Description
AbstractFlowScanner	Core APIs and base logic for FlowScanners that extract information from a pipeline execution.
BlockChunkFinder	Matches start and end of a block.
DepthFirstScanner	Does a simple and somewhat efficient depth-first search of all FlowNodes in the DAG.
FlowScanningUtils	Library of common functionality when analyzing/walking flow graphs
ForkScanner	Scanner that will scan down all forks when we hit parallel blocks before continuing, but generally runs in linear order
LabelledChunkFinder	Splits a flow execution into FlowChunks whenever you have a label.
LinearBlockHoppingScanner	Extension of LinearScanner that skips nested blocks at the current level, useful for finding enclosing blocks.
LinearScanner	Scans through the flow graph in strictly linear fashion, visiting only the first branch in parallel blocks.
MemoryFlowChunk	FlowChunk that holds direct references to the FlowNode instances and context info This makes it easy to use in analysis and visualizations, but inappropriate to retain in caches, etc
NodeStepNamePredicate	Predicate that matches FlowNodes (specifically StepNodes) with a specific StepDescriptor name.
NodeStepTypePredicate	Predicate that matches FlowNodes (specifically StepNodes) with a specific StepDescriptor type.
ParallelMemoryFlowChunk	Corresponds to a parallel block, acts as an in-memory container that can plug into status/timing APIs
StandardChunkVisitor	Simple handler for linear FlowChunks (basic stages, etc), and designed to be extended.