8267204: Expose access to underlying streams in Reporter

Reviewed-by: prappo

Author: jonathan-gibbons

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,41 +25,124 @@
 
 package jdk.javadoc.doclet;
 
+import java.io.PrintWriter;
+import java.util.Locale;
 import javax.lang.model.element.Element;
 import javax.tools.Diagnostic;
+import javax.tools.FileObject;
 
 import com.sun.source.util.DocTreePath;
 
 /**
- * This interface provides error, warning and notice reporting.
+ * Interface for reporting diagnostics and other messages.
+ *
+ * <p>Diagnostics consist of a {@link Diagnostic.Kind diagnostic kind} and a message,
+ * and may additionally be associated with an {@link Element element},
+ * a {@link DocTreePath tree node} in a documentation comment,
+ * or an arbitrary position in a given {@link FileObject file}.
+ * Other messages may be written directly to one of two streams that are informally
+ * for use by "standard output" and "diagnostic output", where "standard output"
+ * means the output that is the expected result of executing some operation,
+ * such as the command-line help that is generated when using a {@code --help} option,
+ * and "diagnostic output" refers to any errors, warnings and other output that is
+ * a side-effect of executing the operation.
+ *
+ * <p>The exact manner in which diagnostics are output is unspecified and depends
+ * on the enclosing context. For example:
+ * <ul>
+ * <li>The {@link javax.tools.DocumentationTool} API allows a client to specify a
+ * {@link javax.tools.DiagnosticListener} to which diagnostics will be
+ * {@link javax.tools.DiagnosticListener#report reported}. If no listener is specified,
+ * diagnostics will be written to a given stream, or to {@code System.err} if no such
+ * stream is provided.
+ * <li>The {@link java.util.spi.ToolProvider} API allows a client to specify
+ * the streams to be used for reporting standard and diagnostic output.
+ * </ul>
  *
  * @since 9
  */
 public interface Reporter {
 
     /**
-     * Print error message and increment error count.
+     * Prints a diagnostic message.
+     *
+     * @param kind    the kind of diagnostic
+     * @param message the message to be printed
+     */
+    void print(Diagnostic.Kind kind, String message);
+
+    /**
+     * Prints a diagnostic message related to a tree node in a documentation comment.
+     *
+     * @param kind    the kind of diagnostic
+     * @param path    the path for the tree node
+     * @param message the message to be printed
+     */
+    void print(Diagnostic.Kind kind, DocTreePath path, String message);
+
+    /**
+     * Prints a diagnostic message related to an element.
      *
-     * @param kind specify the diagnostic kind
-     * @param msg message to print
+     * @param kind    the kind of diagnostic
+     * @param element the element
+     * @param message the message to be printed
      */
-    void print(Diagnostic.Kind kind, String msg);
+    void print(Diagnostic.Kind kind, Element element, String message);
 
     /**
-     * Print an error message and increment error count.
+     * Prints a diagnostic message related to a position within a range of characters in a file.
+     * The positions are all 0-based character offsets from the beginning of content of the file.
+     * The positions should satisfy the relation {@code start <= pos <= end}.
      *
-     * @param kind specify the diagnostic kind
-     * @param path the DocTreePath of item where the error occurs
-     * @param msg message to print
+     * @param kind    the kind of diagnostic
+     * @param file    the file
+     * @param start   the beginning of the enclosing range
+     * @param pos     the position
+     * @param end     the end of the enclosing range
+     * @param message the message to be printed
+     *
+     * @since 17
+     */
+    void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message);
+
+    /**
+     * Returns a writer that can be used to write non-diagnostic output,
+     * or {@code null} if no such writer is available.
+     *
+     * @apiNote
+     * The value may or may not be the same as that returned by {@link #getDiagnosticWriter()}.
+     *
+     * @implSpec
+     * This implementation returns {@code null}.
+     * The implementation provided by the {@code javadoc} tool to
+     * {@link Doclet#init(Locale, Reporter) initialize} a doclet
+     * always returns a non-{@code null} value.
+     *
+     * @return the writer
+     * @since 17
      */
-    void print(Diagnostic.Kind kind, DocTreePath path, String msg);
+    default PrintWriter getStandardWriter() {
+        return null;
+    }
 
     /**
-     * Print an error message and increment error count.
+     * Returns a writer that can be used to write diagnostic output,
+     * or {@code null} if no such writer is available.
+     *
+     * @apiNote
+     * The value may or may not be the same as that returned by {@link #getStandardWriter()}.
      *
-     * @param kind specify the diagnostic kind
-     * @param e the Element for which  the error occurs
-     * @param msg message to print
+     * @implSpec
+     * This implementation returns {@code null}.
+     * The implementation provided by the {@code javadoc} tool to
+     * {@link Doclet#init(Locale, Reporter) initialize} a doclet
+     * always returns a non-{@code null} value.
+     *
+     * @return the writer
+     * @since 17
      */
-    void print(Diagnostic.Kind kind, Element e, String msg);
+    default PrintWriter getDiagnosticWriter() {
+        return null;
+    }
+
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 
 import javax.lang.model.element.Element;
 import javax.tools.Diagnostic;
+import javax.tools.FileObject;
 
 import com.sun.source.util.DocTreePath;
 import jdk.javadoc.doclet.Reporter;
@@ -76,8 +77,8 @@ public Resources getResources() {
     /**
      * Reports an error message to the doclet's reporter.
      *
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void error(String key, Object... args) {
         report(ERROR, resources.getText(key, args));
@@ -86,22 +87,35 @@ public void error(String key, Object... args) {
     /**
      * Reports an error message to the doclet's reporter.
      *
-     * @param path a path identifying the position to be included with
-     *  the message
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param path a path identifying the position to be included with the message
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void error(DocTreePath path, String key, Object... args) {
         report(ERROR, path, resources.getText(key, args));
     }
 
+    /**
+     * Reports an error message to the doclet's reporter.
+     *
+     * @param fo    the file object to be associated with the message
+     * @param start the start of a range of characters to be associated with the message
+     * @param pos   the position to be associated with the message
+     * @param end   the end of a range of characters to be associated with the message
+     * @param key   the name of a resource containing the message to be printed
+     * @param args  optional arguments to be replaced in the message
+     */
+    public void error(FileObject fo, int start, int pos, int end, String key, Object... args) {
+        report(ERROR, fo, start, pos, end, resources.getText(key, args));
+    }
+
     // ***** Warnings *****
 
     /**
      * Reports a warning message to the doclet's reporter.
      *
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void warning(String key, Object... args) {
         report(WARNING, resources.getText(key, args));
@@ -110,10 +124,9 @@ public void warning(String key, Object... args) {
     /**
      * Reports a warning message to the doclet's reporter.
      *
-     * @param path a path identifying the position to be included with
-     *  the message
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param path a path identifying the position to be included with the message
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void warning(DocTreePath path, String key, Object... args) {
         if (configuration.showMessage(path, key)) {
@@ -124,28 +137,43 @@ public void warning(DocTreePath path, String key, Object... args) {
     /**
      * Reports a warning message to the doclet's reporter.
      *
-     * @param e an element identifying the declaration whose position should
-     *  to be included with the message
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param e    an element identifying the position to be included with the message
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void warning(Element e, String key, Object... args) {
         if (configuration.showMessage(e, key)) {
             report(WARNING, e, resources.getText(key, args));
         }
     }
 
+    /**
+     * Reports a warning message to the doclet's reporter.
+     *
+     * @param fo    the file object to be associated with the message
+     * @param start the start of a range of characters to be associated with the message
+     * @param pos   the position to be associated with the message
+     * @param end   the end of a range of characters to be associated with the message
+     * @param key   the name of a resource containing the message to be printed
+     * @param args  optional arguments to be replaced in the message
+     */
+    public void warning(FileObject fo, int start, int pos, int end, String key, Object... args) {
+        report(WARNING, fo, start, pos, end, resources.getText(key, args));
+    }
+
     // ***** Notices *****
 
     /**
      * Reports an informational notice to the doclet's reporter.
+     * The message is written directly to the reporter's diagnostic stream.
      *
-     * @param key the name of a resource containing the message to be printed
-     * @param args optional arguments to be replaced in the message.
+     * @param key  the name of a resource containing the message to be printed
+     * @param args optional arguments to be replaced in the message
      */
     public void notice(String key, Object... args) {
         if (!configuration.getOptions().quiet()) {
-            report(NOTE, resources.getText(key, args));
+            // Note: we do not use report(NOTE, ...) which would prefix the output with "Note:"
+            reporter.getDiagnosticWriter().println(resources.getText(key, args));
         }
     }
 
@@ -162,4 +190,8 @@ private void report(Diagnostic.Kind k, DocTreePath p, String msg) {
     private void report(Diagnostic.Kind k, Element e, String msg) {
         reporter.print(k, e, msg);
     }
+
+    private void report(Diagnostic.Kind k, FileObject fo, int start, int pos, int end, String msg) {
+        reporter.print(k, fo, start, pos, end, msg);
+    }
 }