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:

ConsoleAnnotatorFactory, ConsoleNote, Serialized Form

Constructor Summary

Constructors

Constructor	Description
ConsoleAnnotator()

Method Summary

Modifier and Type	Method	Description
static <T> List<ConsoleAnnotator<T>>	_for(T context)	List all the console annotators that can work for the specified context type.
abstract ConsoleAnnotator<T>	annotate(T context, MarkupText text)	Annotates one line.
static <T> ConsoleAnnotator<T>	cast(ConsoleAnnotator<? super T> a)	Cast operation that restricts T.
static <T> ConsoleAnnotator<T>	combine(Collection<? extends ConsoleAnnotator<? super T>> all)	Bundles all the given ConsoleAnnotator into a single annotator.
static <T> ConsoleAnnotator<T>	initial(T context)	Returns the all ConsoleAnnotators for the given context type aggregated into a single annotator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

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.