Package hudson.console

Class 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

    • Field Detail

      • 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

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

      • 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