corda / net.corda.core.utilities / ProgressTracker

ProgressTracker

class ProgressTracker

A progress tracker helps surface information about the progress of an operation to a user interface or API of some kind. It lets you define a set of steps that represent an operation. A step is represented by an object (typically a singleton).

Steps may logically be children of other steps, which models the case where a large top level operation involves sub-operations which may also have a notion of progress. If a step has children, then the tracker will report the steps children as the "next step" after the parent. In other words, a parent step is considered to involve actual reportable work and is a thing. If the parent step simply groups other steps, then you'll have to step over it manually.

Each step has a label. It is assumed by default that the label does not change. If you want a label to change, then you can emit a ProgressTracker.Change.Rendering object on the ProgressTracker.Step.changes observable stream after it changes. That object will propagate through to the top level trackers changes stream, which renderers can subscribe to in order to learn about progress.

An operation can move both forwards and backwards through steps, thus, a ProgressTracker can represent operations that include loops.

A progress tracker is not thread safe. You may move events from the thread making progress to another thread by using the Observable subscribeOn call.

Types

Change

sealed class Change

DONE

object DONE : Step

Step

class Step

The superclass of all step objects.

UNSTARTED

object UNSTARTED : Step

Constructors

<init>

ProgressTracker(vararg steps: Step)

A progress tracker helps surface information about the progress of an operation to a user interface or API of some kind. It lets you define a set of steps that represent an operation. A step is represented by an object (typically a singleton).

Properties

allSteps

val allSteps: List<Pair<Int, Step>>

A list of all steps in this ProgressTracker and the children, with the indent level provided starting at zero. Note that UNSTARTED is never counted, and DONE is only counted at the calling level.

allStepsLabels

val allStepsLabels: List<Pair<Int, String>>

A list of all steps label in this ProgressTracker and the children, with the indent level provided starting at zero. Note that UNSTARTED is never counted, and DONE is only counted at the calling level.

changes

val changes: Observable<Change>

An observable stream of changes: includes child steps, resets and any changes emitted by individual steps (e.g. if a step changed its label or rendering).

currentStep

var currentStep: Step

Reading returns the value of stepsstepIndex, writing moves the position of the current tracker. Once moved to the DONE state, this tracker is finished and the current step cannot be moved again.

currentStepRecursive

val currentStepRecursive: Step

Returns the current step, descending into children to find the deepest step we are up to.

hasEnded

val hasEnded: Boolean

Returns true if the progress tracker has ended, either by reaching the DONE step or prematurely with an error

parent

var parent: ProgressTracker?

The parent of this tracker: set automatically by the parent when a tracker is added as a child

stepIndex

var stepIndex: Int

The zero-based index of the current step in the steps array (i.e. with UNSTARTED and DONE)

steps

val steps: Array<Step>

The steps in this tracker, same as the steps passed to the constructor but with UNSTARTED and DONE inserted.

stepsTreeChanges

val stepsTreeChanges: Observable<List<Pair<Int, String>>>

An observable stream of changes to the allStepsLabels

stepsTreeIndex

var stepsTreeIndex: Int

The zero-bases index of the current step in a allStepsLabels list

stepsTreeIndexChanges

val stepsTreeIndexChanges: Observable<Int>

An observable stream of changes to the stepsTreeIndex

topLevelTracker

val topLevelTracker: ProgressTracker

Walks up the tree to find the top level tracker. If this is the top level tracker, returns 'this'

Functions

endWithError

fun endWithError(error: Throwable): Unit

Ends the progress tracker with the given error, bypassing any remaining steps. changes will emit the exception as an error.

getChildProgressTracker

fun getChildProgressTracker(step: Step): ProgressTracker?

nextStep

fun nextStep(): Step

Iterates the progress tracker. If the current step has a child, the child is iterated instead (recursively). Returns the latest step at the bottom of the step tree.

setChildProgressTracker

fun setChildProgressTracker(step: Step, childProgressTracker: ProgressTracker): Unit

Extension Functions

contextLogger

fun Any.contextLogger(): Logger

When called from a companion object, returns the logger for the enclosing class.