Package hudson.console

Class ConsoleAnnotator<T>

java.lang.Object
hudson.console.ConsoleAnnotator<T>
All Implemented Interfaces:
Serializable
public abstract class ConsoleAnnotator<T> extends Object implements Serializable
Annotates one line of console output.

In Jenkins, console output annotation is done line by line, and we model this as a state machine — the code encapsulates some state, and it uses that to annotate one line (and possibly update the state.)

A ConsoleAnnotator instance encapsulates this state, and the annotate(Object, MarkupText) method is used to annotate the next line based on the current state. The method returns another ConsoleAnnotator instance that represents the altered state for annotating the next line.

ConsoleAnnotators are run when a browser requests console output, and the above-mentioned chain invocation is done for each client request separately. Therefore, logically you can think of this process as: 

 ConsoleAnnotator ca = ...;
 ca.annotate(context,line1).annotate(context,line2)...

Because a browser can request console output incrementally, in addition to above a console annotator can be serialized at any point and deserialized back later to continue annotation where it left off.

ConsoleAnnotator instances can be created in a few different ways. See ConsoleNote and ConsoleAnnotatorFactory.

Since:
1.349
Author:
Kohsuke Kawaguchi
See Also:

  • Constructor Details

    • ConsoleAnnotator

      public ConsoleAnnotator()

  • Method Details

    • annotate

      @CheckForNull public abstract ConsoleAnnotator<T> annotate(@NonNull T context, @NonNull MarkupText text)
      Annotates one line.
      Parameters:
      context - The object that owns the console output. Never null.
      text - Contains a single line of console output, and defines convenient methods to add markup. The callee should put markup into this object. Never null.
      Returns:
      The ConsoleAnnotator object that will annotate the next line of the console output. To indicate that you are not interested in the following lines, return null.

    • cast

      public static <T> ConsoleAnnotator<T> cast(ConsoleAnnotator<? super T> a)
      Cast operation that restricts T.

    • combine

      public static <T> ConsoleAnnotator<T> combine(Collection<? extends ConsoleAnnotator<? super T>> all)
      Bundles all the given ConsoleAnnotator into a single annotator.

    • initial

      public static <T> ConsoleAnnotator<T> initial(T context)
      Returns the all ConsoleAnnotators for the given context type aggregated into a single annotator.

    • _for

      public static <T> List<ConsoleAnnotator<T>> _for(T context)
      List all the console annotators that can work for the specified context type.