ProgressTracker
Keywords: net.corda.core.utilities.ProgressTracker class
Date: 2023-09-18

net.corda.core.utilities

## Class ProgressTracker

- net.corda.core.utilities.ProgressTracker

-     public 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 `class 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 `class 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.

  See Also:
    `class Change.Rendering`, `ProgressTracker.Step.changes`, `changes`, `class ProgressTracker`

- - ### Field Detail

    - #### Companion

          public static net.corda.core.utilities.ProgressTracker.Companion Companion

      Deprecated.

  - ### Constructor Detail

    - #### ProgressTracker

          public ProgressTracker(@NotNull
                                 net.corda.core.utilities.ProgressTracker.Step... inputSteps)

      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 `class 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 `class 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.

      See Also:
        `class Change.Rendering`, `ProgressTracker.Step.changes`, `changes`, `class ProgressTracker`

  - ### Method Detail

    - #### getSteps

          @NotNull
          public net.corda.core.utilities.ProgressTracker.Step[] getSteps()

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

    - #### getCurrentStep

          @NotNull
          public net.corda.core.utilities.ProgressTracker.Step getCurrentStep()

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

      See Also:
        `stepIndex`, `class ProgressTracker.DONE`

    - #### setCurrentStep

          public void setCurrentStep(@NotNull
                                     net.corda.core.utilities.ProgressTracker.Step value)

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

      See Also:
        `stepIndex`, `class ProgressTracker.DONE`

    - #### getStepIndex

          public int getStepIndex()

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

      See Also:
        `steps`

    - #### getStepsTreeIndex

          public int getStepsTreeIndex()

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

      See Also:
        `allStepsLabels`

    - #### getCurrentStepRecursive

          @NotNull
          public net.corda.core.utilities.ProgressTracker.Step getCurrentStepRecursive()

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

    - #### getChildProgressTracker

          @Nullable
          public ProgressTracker getChildProgressTracker(@NotNull
                                                                   net.corda.core.utilities.ProgressTracker.Step step)

    - #### setChildProgressTracker

          public void setChildProgressTracker(@NotNull
                                              net.corda.core.utilities.ProgressTracker.Step step,
                                              @NotNull
                                              ProgressTracker childProgressTracker)

    - #### endWithError

          public void endWithError(@NotNull
                                   java.lang.Throwable error)

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

      See Also:
        `changes`

    - #### getParent

          @Nullable
          public ProgressTracker getParent()

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

    - #### getTopLevelTracker

          @NotNull
          public ProgressTracker getTopLevelTracker()

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

    - #### getAllSteps

          @NotNull
          public java.util.List<kotlin.Pair> getAllSteps()

      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.

    - #### getAllStepsLabels

          @NotNull
          public java.util.List<kotlin.Pair> getAllStepsLabels()

      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.

    - #### nextStep

          @NotNull
          public net.corda.core.utilities.ProgressTracker.Step nextStep()

      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.

    - #### getChanges

          @NotNull
          public rx.Observable<net.corda.core.utilities.ProgressTracker.Change> getChanges()

      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).

    - #### getStepsTreeChanges

          @NotNull
          public rx.Observable<java.util.List> getStepsTreeChanges()

      An observable stream of changes to the `allStepsLabels`

      See Also:
        `allStepsLabels`

    - #### getStepsTreeIndexChanges

          @NotNull
          public rx.Observable<java.lang.Integer> getStepsTreeIndexChanges()

      An observable stream of changes to the `stepsTreeIndex`

      See Also:
        `stepsTreeIndex`

    - #### getHasEnded

          public boolean getHasEnded()

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

      See Also:
        `class ProgressTracker.DONE`