Package 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:

ExtensionPoint, Describable<ConsoleNote<?>>, Serializable

Direct Known Subclasses:

ExpandableDetailsNote, HyperlinkNote, Maven3MojoNote, MavenErrorNote, MavenMojoNote, MavenWarningNote

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

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.

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.

Note that encode(), encodeTo(OutputStream), and encodeTo(Writer) should be called on the Jenkins master. If called from an agent JVM, a signature will be missing and so as per SECURITY-382 the console note will be ignored. This may happen, in particular, if the note was generated by a ConsoleLogFilter sent to the agent. Alternative solutions include using a ConsoleAnnotatorFactory where practical; or generating the encoded form of the note on the master side and sending it to the agent, for example by saving that form as instance fields in a ConsoleLogFilter implementation.

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

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	INSECURE	Allows historical build records with unsigned console notes to be displayed, at the expense of any security.
static final byte[]	POSTAMBLE	Post amble is the ANSI escape sequence that brings back the echo.
static final String	POSTAMBLE_STR
static final byte[]	PREAMBLE	Preamble of the encoded form.
static final String	PREAMBLE_STR

Constructor Summary

Constructors

Constructor	Description
ConsoleNote()

Method Summary

Modifier and Type	Method	Description
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 String	removeNotes(String line)	Removes the embedded console notes in the given log line.
static List<String>	removeNotes(Collection<String> logLines)	Removes the embedded console notes in the given log lines.
static void	skip(DataInputStream in)	Skips the encoded console note.

Methods inherited from class java.lang.Object

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

Field Details

INSECURE

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean INSECURE

Allows historical build records with unsigned console notes to be displayed, at the expense of any security. Disables checking of MAC so do not set this flag unless you completely trust all users capable of affecting build output, which in practice means that all SCM committers as well as all Jenkins users with any non-read-only access are consider administrators.

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 Details

ConsoleNote

public ConsoleNote()

Method Details

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 by default a.getDescriptor() == b.getDescriptor() as well. (In rare cases a single implementation class may be used for instances with distinct descriptors.)

Specified by:

getDescriptor in interface Describable<T>

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