External Logging API: Align with new Core version, fix Findbugs

pom.xml

@@ -20,7 +20,9 @@
   <properties>
     <revision>1.0-alpha-1</revision>
     <changelist>-SNAPSHOT</changelist>
-    <jenkins.version>2.135-rc15088.42aa6febbbed</jenkins.version>
+    <!--TODO: replace by incrementals (JENKINS-52873) -->
+    <jenkins-core.version>2.137-20180806.095555-1</jenkins-core.version>
+    <jenkins-war.version>2.137-20180806.095623-1</jenkins-war.version>
     <java.level>8</java.level>
     <useBeta>true</useBeta>
   </properties>

src/main/java/io/jenkins/plugins/extlogging/api/Event.java

@@ -15,6 +15,7 @@ public class Event {
     final long timestamp;
     final long id;
 
+    //TODO:Consider <String,String> so that Key-Value storages could be quickly implemented
     Map<String, Serializable> data = new HashMap<>();
 
     public Event(long id, String message, long timestamp) {

src/main/java/io/jenkins/plugins/extlogging/api/ExternalLogBrowser.java

@@ -1,18 +1,121 @@
 package io.jenkins.plugins.extlogging.api;
 
-import jenkins.model.logging.LogBrowser;
+import hudson.console.AnnotatedLargeText;
+import hudson.console.ConsoleNote;
+import hudson.model.Run;
 import jenkins.model.logging.Loggable;
 
+import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Reader;
+import java.util.LinkedList;
+import java.util.List;
 
 /**
  * Base abstract class for External Log Browsers.
+ * This implementation also implements a convenience method for caching of files.
  * @author Oleg Nenashev
  * @since TODO
  */
-public abstract class ExternalLogBrowser extends LogBrowser {
+public abstract class ExternalLogBrowser<T extends Loggable> extends LoggableHandler {
 
     public ExternalLogBrowser(@Nonnull Loggable loggable) {
         super(loggable);
     }
+
+    //TODO: Push warnings to Telemetry API
+    //Pipeline: LOGGER.log(Level.WARNING, "Avoid calling getLogFile on " + this,
+    //        new UnsupportedOperationException());
+    /**
+     * Gets log as a file.
+     * This is a compatibility method, which is used in {@link Run#getLogFile()}.
+     * {@link ExternalLogBrowser} implementations may provide it, e.g. by creating temporary files if needed.
+     * @return Log file. If it does not exist, {@link IOException} should be thrown
+     * @throws IOException Log file cannot be retrieved
+     * @deprecated The method is available for compatibility purposes only
+     */
+    public File getLogFile() throws IOException {
+        File f = File.createTempFile("deprecated", ".log", getOwner().getTmpDir());
+        f.deleteOnExit();
+        try (OutputStream os = new FileOutputStream(f)) {
+            overallLog().writeRawLogTo(0, os);
+        }
+        return f;
+    }
+
+    /**
+     * Gets log for an object.
+     * @return Created log or {@link jenkins.model.logging.impl.BrokenAnnotatedLargeText} if it cannot be retrieved
+     */
+    @Nonnull
+    public abstract AnnotatedLargeText<T> overallLog();
+
+    //TODO: jglick requests justification of why it needs to be in the core
+    /**
+     * Gets log for a part of the object.
+     * @param stepId Identifier of the step to be displayed.
+     *               It may be Pipeline step or other similar abstraction
+     * @param completed indicates that the step is completed
+     * @return Created log or {@link jenkins.model.logging.impl.BrokenAnnotatedLargeText} if it cannot be retrieved
+     */
+    @Nonnull
+    public abstract AnnotatedLargeText<T> stepLog(@CheckForNull String stepId, boolean completed);
+
+    public InputStream getLogInputStream() throws IOException {
+        // Inefficient but probably rarely used anyway.
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        overallLog().writeRawLogTo(0, baos);
+        return new ByteArrayInputStream(baos.toByteArray());
+    }
+
+    public Reader getLogReader() throws IOException {
+        // As above.
+        return overallLog().readAll();
+    }
+
+    @SuppressWarnings("deprecation")
+    public String getLog() throws IOException {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        overallLog().writeRawLogTo(0, baos);
+        return baos.toString(loggable.getCharset().name());
+    }
+
+    public List<String> getLog(int maxLines) throws IOException {
+        int lineCount = 0;
+        List<String> logLines = new LinkedList<>();
+        if (maxLines == 0) {
+            return logLines;
+        }
+        try (BufferedReader reader = new BufferedReader(getLogReader())) {
+            for (String line = reader.readLine(); line != null; line = reader.readLine()) {
+                logLines.add(line);
+                ++lineCount;
+                if (lineCount > maxLines) {
+                    logLines.remove(0);
+                }
+            }
+        }
+        if (lineCount > maxLines) {
+            logLines.set(0, "[...truncated " + (lineCount - (maxLines - 1)) + " lines...]");
+        }
+        return ConsoleNote.removeNotes(logLines);
+    }
+
+    /**
+     * Deletes the log in the storage.
+     * @return {@code true} if the log was deleted.
+     *         {@code false} if Log deletion is not supported.
+     * @throws IOException Failed to delete the log.
+     */
+    public abstract boolean deleteLog() throws IOException;
+
+
 }

src/main/java/io/jenkins/plugins/extlogging/api/ExternalLogBrowserFactory.java

@@ -4,20 +4,20 @@
 import hudson.model.Describable;
 import hudson.model.Descriptor;
 import jenkins.model.Jenkins;
-import jenkins.model.logging.LogBrowser;
 import jenkins.model.logging.Loggable;
 
 import javax.annotation.CheckForNull;
 
 /**
+ * Produces {@link ExternalLogBrowser}s.
  * @author Oleg Nenashev
  * @since TODO
  */
 public abstract class ExternalLogBrowserFactory
         implements Describable<ExternalLogBrowserFactory>, ExtensionPoint {
 
     @CheckForNull
-    public abstract LogBrowser create(Loggable loggable);
+    public abstract ExternalLogBrowser create(Loggable loggable);
 
     @Override
     public Descriptor<ExternalLogBrowserFactory> getDescriptor() {

src/main/java/io/jenkins/plugins/extlogging/api/ExternalLoggingEventWriter.java

@@ -1,22 +1,39 @@
 package io.jenkins.plugins.extlogging.api;
 
+import io.jenkins.plugins.extlogging.api.impl.ExternalLoggingOutputStream;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 import java.io.IOException;
+import java.io.PrintStream;
 import java.io.Serializable;
+import java.io.UnsupportedEncodingException;
 import java.io.Writer;
+import java.nio.charset.Charset;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicLong;
 
+//TODO: jglick is concerned about the event-based logic, maybe we should add a lower-level implementation
+//TODO: jglick: "Why do we need events?" in JEP
 /**
  * Implements logging of events
  * @author Oleg Nenashev
  * @since TODO
  */
 public abstract class ExternalLoggingEventWriter extends Writer implements Serializable {
 
+    String charset;
     Map<String, Serializable> metadata = new HashMap<>();
     AtomicLong messageCounter = new AtomicLong();
 
+    @CheckForNull
+    private transient PrintStream printStream;
+
+    public ExternalLoggingEventWriter(@Nonnull Charset charset) {
+        this.charset = charset.name();
+    }
+
     public abstract void writeEvent(Event event) throws IOException;
 
     public void writeMessage(String message) throws IOException {
@@ -25,6 +42,7 @@ public void writeMessage(String message) throws IOException {
         writeEvent(event);
     }
 
+    //TODO(oleg-nenashev): jglick requests example of complex event
     public void addMetadataEntry(String key, Serializable value) {
         metadata.put(key, value);
     }
@@ -37,11 +55,24 @@ public void write(char[] cbuf, int off, int len) throws IOException {
 
     @Override
     public void close() throws IOException {
-        // noop
+        // noop by default
     }
 
     @Override
     public void flush() throws IOException {
-        // noop
+        if (printStream != null) {
+            printStream.flush();
+        }
+    }
+
+    public Charset getCharset() {
+        return Charset.forName(charset);
+    }
+
+    public PrintStream getLogger() throws UnsupportedEncodingException {
+        if (printStream == null) {
+            printStream = new PrintStream(new ExternalLoggingOutputStream(this), true, charset);
+        }
+        return printStream;
     }
 }

src/main/java/io/jenkins/plugins/extlogging/api/ExternalLoggingMethod.java

@@ -18,7 +18,6 @@
 import io.jenkins.plugins.extlogging.api.util.UniqueIdHelper;
 import jenkins.model.Jenkins;
 import jenkins.model.logging.Loggable;
-import jenkins.model.logging.LoggingMethod;
 
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
@@ -28,21 +27,29 @@
  * @author Oleg Nenashev
  * @since TODO
  */
-public abstract class ExternalLoggingMethod extends LoggingMethod {
+public abstract class ExternalLoggingMethod<TLoggable extends Loggable> extends LoggableHandler {
 
     public ExternalLoggingMethod(@Nonnull Loggable loggable) {
         super(loggable);
     }
 
+    /**
+     * Gets default Log browser which should be used with this Logging method.
+     * It allows setting a custom default LogBrowser if needed.
+     * @return Log browser or {@code null} if not defined.
+     */
+    @CheckForNull
+    public ExternalLogBrowser<TLoggable> getDefaultLogBrowser() {
+        return null;
+    }
+
     //TODO: implement
     @CheckForNull
-    @Override
     public TaskListener createTaskListener() {
         return null;
     }
 
     // TODO: Implement event-based logic instead of the
-    @Override
     public BuildListener createBuildListener() throws IOException, InterruptedException {
         return new ExternalLoggingBuildListener(createWriter());
     }
@@ -98,7 +105,6 @@ public final ExternalLoggingEventWriter createWriter() throws IOException, Inter
     protected abstract ExternalLoggingEventWriter _createWriter() throws IOException, InterruptedException;
 
     @Nonnull
-    @Override
     public Launcher decorateLauncher(@Nonnull Launcher original,
                                      @Nonnull Run<?,?> run, @Nonnull Node node) {
         if (node instanceof Jenkins) {

src/main/java/io/jenkins/plugins/extlogging/api/LoggableHandler.java

@@ -0,0 +1,79 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2018 CloudBees, 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 io.jenkins.plugins.extlogging.api;
+
+import jenkins.model.logging.Loggable;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.Beta;
+import org.kohsuke.stapler.export.Exported;
+import org.kohsuke.stapler.export.ExportedBean;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+/**
+ * Object which operates with {@link Loggable} items.
+ * @param <TLoggable> Loggable type
+ * @author Oleg Nenashev
+ * @since TODO
+ */
+@ExportedBean
+@Restricted(Beta.class)
+public abstract class LoggableHandler <TLoggable extends Loggable> {
+
+    protected transient TLoggable loggable;
+
+    public LoggableHandler(@Nonnull TLoggable loggable) {
+        this.loggable = loggable;
+    }
+
+    @Exported
+    public String getId() {
+        return getClass().getName();
+    }
+
+    /**
+     * Called when the owner is loaded from disk.
+     * The owner may be persisted on the disk, so the build reference should be {@code transient} (quasi-{@code final}) and restored here.
+     * @param loggable an owner to which this component is associated.
+     */
+    public void onLoad(@Nonnull TLoggable loggable) {
+        this.loggable = loggable;
+    }
+
+    public static <T extends Loggable> void onLoad(@Nonnull T loggable, @CheckForNull LoggableHandler<T> logHandler) {
+        if (logHandler != null) {
+            logHandler.onLoad(loggable);
+        }
+    }
+
+    @Nonnull
+    protected TLoggable getOwner() {
+        if (loggable == null) {
+            throw new IllegalStateException("Owner has not been assigned to the object yet");
+        }
+        return loggable;
+
+    }
+}

src/main/java/io/jenkins/plugins/extlogging/api/impl/DisabledExternalLogBrowserFactory.java

@@ -1,9 +1,9 @@
 package io.jenkins.plugins.extlogging.api.impl;
 
 import hudson.Extension;
+import io.jenkins.plugins.extlogging.api.ExternalLogBrowser;
 import io.jenkins.plugins.extlogging.api.ExternalLogBrowserFactory;
 import io.jenkins.plugins.extlogging.api.ExternalLogBrowserFactoryDescriptor;
-import jenkins.model.logging.LogBrowser;
 import jenkins.model.logging.Loggable;
 import org.jenkinsci.Symbol;
 import org.kohsuke.stapler.DataBoundConstructor;
@@ -21,7 +21,7 @@ public DisabledExternalLogBrowserFactory() {
     }
 
     @Override
-    public LogBrowser create(Loggable loggable) {
+    public ExternalLogBrowser create(Loggable loggable) {
         return null;
     }