Class 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:
    ConsoleAnnotatorFactory, ConsoleNote, Serialized Form
    • Constructor Detail

      • ConsoleAnnotator

        public ConsoleAnnotator()
    • Method Detail

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