Skip to content
Permalink
Browse files
8267204: Expose access to underlying streams in Reporter
Reviewed-by: prappo
  • Loading branch information
jonathan-gibbons committed Jun 5, 2021
1 parent 76b54a1 commit 6ff978ac16e631ebded7964d89ac42fd0452b1d3
Showing 10 changed files with 508 additions and 118 deletions.
@@ -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;
}

}
@@ -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);
}
}

0 comments on commit 6ff978a

Please sign in to comment.