hudson.console
Class ConsoleNote<T>

java.lang.Object
  hudson.console.ConsoleNote<T>

Type Parameters:

T - Contextual model object that this console is associated with, such as Run.

All Implemented Interfaces:

Describable<ConsoleNote<?>>, Serializable

Direct Known Subclasses:

AntOutcomeNote, AntTargetNote, ExpandableDetailsNote, HudsonExceptionNote, HyperlinkNote, MavenErrorNote, MavenMojoNote, MavenWarningNote

public abstract class ConsoleNote<T>
extends Object
implements Serializable, Describable<ConsoleNote<?>>

Data that hangs off from a console output.

A ConsoleNote can be put into a console output while it's being written, and it represents a machine readable information about a particular position of the console output.

When Hudson is reading back a console output for display, a ConsoleNote is used to trigger ConsoleAnnotator, which in turn uses the information in the note to generate markup. In this way, we can overlay richer information on top of the console output.

Comparison with ConsoleAnnotatorFactory

Compared to ConsoleAnnotatorFactory, the main advantage of ConsoleNote is that it can be emitted into the output by the producer of the output (or by a filter), which can have a much better knowledge about the context of what's being executed.

1. For example, when your plugin is about to report an error message, you can emit a ConsoleNote that indicates an error, instead of printing an error message as plain text. The annotate(Object, MarkupText, int) method will then generate the proper error message, with all the HTML markup that makes error message more user friendly.
2. Or consider annotating output from Ant. A modified BuildListener can place a ConsoleNote every time a new target execution starts. These notes can be then later used to build the outline that shows what targets are executed, hyperlinked to their corresponding locations in the build output.

Doing these things by ConsoleAnnotatorFactory would be a lot harder, as they can only rely on the pattern matching of the output.

Persistence

ConsoleNotes are serialized and gzip compressed into a byte sequence and then embedded into the console output text file, with a bit of preamble/postamble to allow tools to ignore them. In this way ConsoleNote always sticks to a particular point in the console output.

This design allows descendant processes of Hudson to emit ConsoleNotes. For example, Ant forked by a shell forked by Hudson can put an encoded note in its stdout, and Hudson will correctly understands that. The preamble and postamble includes a certain ANSI escape sequence designed in such a way to minimize garbage if this output is observed by a human being directly.

Because of this persistence mechanism, ConsoleNotes need to be serializable, and care should be taken to reduce footprint of the notes, if you are putting a lot of notes. Serialization format compatibility is also important, although ConsoleNotes that failed to deserialize will be simply ignored, so the worst thing that can happen is that you just lose some notes.

Behaviour, JavaScript, and CSS

ConsoleNote can have associated script.js and style.css (put them in the same resource directory that you normally put Jelly scripts), which will be loaded into the HTML page whenever the console notes are used. This allows you to use minimal markup in code generation, and do the styling in CSS and perform the rest of the interesting work as a CSS behaviour/JavaScript.

Since:

1.349

Author:

Kohsuke Kawaguchi

See Also:

ConsoleAnnotationDescriptor, Functions.generateConsoleAnnotationScriptAndStylesheet(), Serialized Form

Field Summary

static byte[]	POSTAMBLE Post amble is the ANSI escape sequence that brings back the echo.
static String	POSTAMBLE_STR
static byte[]	PREAMBLE Preamble of the encoded form.
static String	PREAMBLE_STR

Constructor Summary

ConsoleNote()

Method Summary

abstract ConsoleAnnotator	annotate(T context, MarkupText text, int charPos) When the line of a console output that this annotation is attached is read by someone, a new ConsoleNote is de-serialized and this method is invoked to annotate that line.
String	encode() Works like encodeTo(Writer) but obtain the result as a string.
void	encodeTo(OutputStream out) Prints this note into a stream.
void	encodeTo(Writer out) Prints this note into a writer.
static int	findPreamble(byte[] buf, int start, int len) Locates the preamble in the given buffer.
ConsoleAnnotationDescriptor	getDescriptor() Gets the descriptor for this instance.
static ConsoleNote	readFrom(DataInputStream in) Reads a note back from its encoded form.
static List<String>	removeNotes(Collection<String> logLines) Removes the embedded console notes in the given log lines.
static String	removeNotes(String line) Removes the embedded console notes in the given log line.
static void	skip(DataInputStream in) Skips the encoded console note.

Methods inherited from class java.lang.Object

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

Field Detail

PREAMBLE_STR

public static final String PREAMBLE_STR

See Also:

Constant Field Values

POSTAMBLE_STR

public static final String POSTAMBLE_STR

See Also:

Constant Field Values

PREAMBLE

public static final byte[] PREAMBLE

Preamble of the encoded form. ANSI escape sequence to stop echo back plus a few magic characters.

POSTAMBLE

public static final byte[] POSTAMBLE

Post amble is the ANSI escape sequence that brings back the echo.

Constructor Detail

ConsoleNote

public ConsoleNote()

Method Detail

annotate

public abstract ConsoleAnnotator annotate(T context,
                                          MarkupText text,
                                          int charPos)

When the line of a console output that this annotation is attached is read by someone, a new ConsoleNote is de-serialized and this method is invoked to annotate that line.

Parameters:

context - The object that owns the console output in question.

text - Represents a line of the console output being annotated.

charPos - The character position in 'text' where this annotation is attached.

Returns:

if non-null value is returned, this annotator will handle the next line. this mechanism can be used to annotate multiple lines starting at the annotated position.

getDescriptor

public ConsoleAnnotationDescriptor getDescriptor()

Description copied from interface: Describable

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass()==b.getClass() then a.getDescriptor()==b.getDescriptor() must hold.

Specified by:

getDescriptor in interface Describable<ConsoleNote<?>>

encodeTo

public void encodeTo(OutputStream out)
              throws IOException

Prints this note into a stream.

The most typical use of this is n.encodedTo(System.out) where stdout is connected to Hudson. The encoded form doesn't include any new line character to work better in the line-oriented nature of ConsoleAnnotator.

Throws:

IOException

encodeTo

public void encodeTo(Writer out)
              throws IOException

Prints this note into a writer.

Technically, this method only works if the Writer to OutputStream encoding is ASCII compatible.

Throws:

IOException

encode

public String encode()
              throws IOException

Works like encodeTo(Writer) but obtain the result as a string.

Throws:

IOException

readFrom

public static ConsoleNote readFrom(DataInputStream in)
                            throws IOException,
                                   ClassNotFoundException

Reads a note back from its encoded form.

Parameters:

in - Must point to the beginning of a preamble.

Returns:

null if the encoded form is malformed.

Throws:

IOException

ClassNotFoundException

skip

public static void skip(DataInputStream in)
                 throws IOException

Skips the encoded console note.

Throws:

IOException

findPreamble

public static int findPreamble(byte[] buf,
                               int start,
                               int len)

Locates the preamble in the given buffer.

removeNotes

public static List<String> removeNotes(Collection<String> logLines)

Removes the embedded console notes in the given log lines.

Since:

1.350

removeNotes

public static String removeNotes(String line)

Removes the embedded console notes in the given log line.

Since:

1.350