Java tutorial
/* * The MIT License * * Copyright (c) 2004-2010, Sun Microsystems, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */ package hudson.console; import hudson.ExtensionPoint; import hudson.Functions; import hudson.MarkupText; import hudson.model.Describable; import jenkins.model.Jenkins; import hudson.model.Run; import hudson.remoting.ObjectInputStreamEx; import hudson.util.IOUtils; import hudson.util.UnbufferedBase64InputStream; import org.apache.commons.codec.binary.Base64OutputStream; import org.apache.commons.io.output.ByteArrayOutputStream; import org.apache.tools.ant.BuildListener; import java.io.ByteArrayInputStream; import java.io.DataInputStream; import java.io.DataOutputStream; import java.io.IOException; import java.io.ObjectInputStream; import java.io.ObjectOutputStream; import java.io.OutputStream; import java.io.Serializable; import java.io.Writer; import java.util.ArrayList; import java.util.Arrays; import java.util.Collection; import java.util.List; import com.jcraft.jzlib.GZIPInputStream; import com.jcraft.jzlib.GZIPOutputStream; /** * Data that hangs off from a console output. * * <p> * A {@link 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. * * <p> * When Hudson is reading back a console output for display, a {@link ConsoleNote} is used * to trigger {@link 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. * * <h2>Comparison with {@link ConsoleAnnotatorFactory}</h2> * <p> * Compared to {@link ConsoleAnnotatorFactory}, the main advantage of {@link 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. * * <ol> * <li> * For example, when your plugin is about to report an error message, you can emit a {@link ConsoleNote} * that indicates an error, instead of printing an error message as plain text. The {@link #annotate(Object, MarkupText, int)} * method will then generate the proper error message, with all the HTML markup that makes error message * more user friendly. * * <li> * Or consider annotating output from Ant. A modified {@link BuildListener} can place a {@link 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. * </ol> * * <p> * Doing these things by {@link ConsoleAnnotatorFactory} would be a lot harder, as they can only rely * on the pattern matching of the output. * * <h2>Persistence</h2> * <p> * {@link ConsoleNote}s 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 * {@link ConsoleNote} always sticks to a particular point in the console output. * * <p> * This design allows descendant processes of Hudson to emit {@link ConsoleNote}s. 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. * * <p> * Because of this persistence mechanism, {@link ConsoleNote}s 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 {@link ConsoleNote}s that failed to deserialize will be simply ignored, so the * worst thing that can happen is that you just lose some notes. * * <h2>Behaviour, JavaScript, and CSS</h2> * <p> * {@link ConsoleNote} can have associated <tt>script.js</tt> and <tt>style.css</tt> (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. * * @param <T> * Contextual model object that this console is associated with, such as {@link Run}. * * @author Kohsuke Kawaguchi * @see ConsoleAnnotationDescriptor * @see Functions#generateConsoleAnnotationScriptAndStylesheet() * @since 1.349 */ public abstract class ConsoleNote<T> implements Serializable, Describable<ConsoleNote<?>>, ExtensionPoint { /** * When the line of a console output that this annotation is attached is read by someone, * a new {@link ConsoleNote} is de-serialized and this method is invoked to annotate that line. * * @param context * The object that owns the console output in question. * @param text * Represents a line of the console output being annotated. * @param charPos * The character position in 'text' where this annotation is attached. * * @return * 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. */ public abstract ConsoleAnnotator annotate(T context, MarkupText text, int charPos); public ConsoleAnnotationDescriptor getDescriptor() { return (ConsoleAnnotationDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass()); } /** * Prints this note into a stream. * * <p> * The most typical use of this is {@code 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 {@link ConsoleAnnotator}. */ public void encodeTo(OutputStream out) throws IOException { // atomically write to the final output, to minimize the chance of something else getting in between the output. // even with this, it is still technically possible to get such a mix-up to occur (for example, // if Java program is reading stdout/stderr separately and copying them into the same final stream.) out.write(encodeToBytes().toByteArray()); } /** * Prints this note into a writer. * * <p> * Technically, this method only works if the {@link Writer} to {@link OutputStream} * encoding is ASCII compatible. */ public void encodeTo(Writer out) throws IOException { out.write(encodeToBytes().toString()); } private ByteArrayOutputStream encodeToBytes() throws IOException { ByteArrayOutputStream buf = new ByteArrayOutputStream(); ObjectOutputStream oos = new ObjectOutputStream(new GZIPOutputStream(buf)); try { oos.writeObject(this); } finally { oos.close(); } ByteArrayOutputStream buf2 = new ByteArrayOutputStream(); DataOutputStream dos = new DataOutputStream(new Base64OutputStream(buf2, true, -1, null)); try { buf2.write(PREAMBLE); dos.writeInt(buf.size()); buf.writeTo(dos); } finally { dos.close(); } buf2.write(POSTAMBLE); return buf2; } /** * Works like {@link #encodeTo(Writer)} but obtain the result as a string. */ public String encode() throws IOException { return encodeToBytes().toString(); } /** * Reads a note back from {@linkplain #encodeTo(OutputStream) its encoded form}. * * @param in * Must point to the beginning of a preamble. * * @return null if the encoded form is malformed. */ public static ConsoleNote readFrom(DataInputStream in) throws IOException, ClassNotFoundException { try { byte[] preamble = new byte[PREAMBLE.length]; in.readFully(preamble); if (!Arrays.equals(preamble, PREAMBLE)) return null; // not a valid preamble DataInputStream decoded = new DataInputStream(new UnbufferedBase64InputStream(in)); int sz = decoded.readInt(); byte[] buf = new byte[sz]; decoded.readFully(buf); byte[] postamble = new byte[POSTAMBLE.length]; in.readFully(postamble); if (!Arrays.equals(postamble, POSTAMBLE)) return null; // not a valid postamble ObjectInputStream ois = new ObjectInputStreamEx(new GZIPInputStream(new ByteArrayInputStream(buf)), Jenkins.getInstance().pluginManager.uberClassLoader); try { return (ConsoleNote) ois.readObject(); } finally { ois.close(); } } catch (Error e) { // for example, bogus 'sz' can result in OutOfMemoryError. // package that up as IOException so that the caller won't fatally die. throw new IOException(e); } } /** * Skips the encoded console note. */ public static void skip(DataInputStream in) throws IOException { byte[] preamble = new byte[PREAMBLE.length]; in.readFully(preamble); if (!Arrays.equals(preamble, PREAMBLE)) return; // not a valid preamble DataInputStream decoded = new DataInputStream(new UnbufferedBase64InputStream(in)); int sz = decoded.readInt(); IOUtils.skip(decoded, sz); byte[] postamble = new byte[POSTAMBLE.length]; in.readFully(postamble); } private static final long serialVersionUID = 1L; public static final String PREAMBLE_STR = "\u001B[8mha:"; public static final String POSTAMBLE_STR = "\u001B[0m"; /** * Preamble of the encoded form. ANSI escape sequence to stop echo back * plus a few magic characters. */ public static final byte[] PREAMBLE = PREAMBLE_STR.getBytes(); /** * Post amble is the ANSI escape sequence that brings back the echo. */ public static final byte[] POSTAMBLE = POSTAMBLE_STR.getBytes(); /** * Locates the preamble in the given buffer. */ public static int findPreamble(byte[] buf, int start, int len) { int e = start + len - PREAMBLE.length + 1; OUTER: for (int i = start; i < e; i++) { if (buf[i] == PREAMBLE[0]) { // check for the rest of the match for (int j = 1; j < PREAMBLE.length; j++) { if (buf[i + j] != PREAMBLE[j]) continue OUTER; } return i; // found it } } return -1; // not found } /** * Removes the embedded console notes in the given log lines. * * @since 1.350 */ public static List<String> removeNotes(Collection<String> logLines) { List<String> r = new ArrayList<String>(logLines.size()); for (String l : logLines) r.add(removeNotes(l)); return r; } /** * Removes the embedded console notes in the given log line. * * @since 1.350 */ public static String removeNotes(String line) { while (true) { int idx = line.indexOf(PREAMBLE_STR); if (idx < 0) return line; int e = line.indexOf(POSTAMBLE_STR, idx); if (e < 0) return line; line = line.substring(0, idx) + line.substring(e + POSTAMBLE_STR.length()); } } }