W3cubDocs

/OpenJDK 21

Interface Reporter

public interface Reporter
Interface for reporting diagnostics and other messages.

Diagnostics consist of a diagnostic kind and a message, and may additionally be associated with an element, a tree node in a documentation comment, or an arbitrary position in a given 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 --help option, and "diagnostic output" refers to any errors, warnings and other output that is a side effect of executing the operation.

The exact manner in which diagnostics are output is unspecified and depends on the enclosing context. For example:

  • The DocumentationTool API allows a client to specify a DiagnosticListener to which diagnostics will be reported. If no listener is specified, diagnostics will be written to a given stream, or to System.err if no such stream is provided.
  • The ToolProvider API allows a client to specify the streams to be used for reporting standard and diagnostic output.
Since:
9

Method Summary

Modifier and Type Method Description
default PrintWriter getDiagnosticWriter()
Returns a writer that can be used to write diagnostic output, or null if no such writer is available.
default PrintWriter getStandardWriter()
Returns a writer that can be used to write non-diagnostic output, or null if no such writer is available.
default void print(Diagnostic.Kind kind, DocTreePath path, int start, int pos, int end, String message)
Prints a diagnostic message related to a position within a range of characters in a tree node.
void print(Diagnostic.Kind kind, DocTreePath path, String message)
Prints a diagnostic message related to a tree node in a documentation comment.
void print(Diagnostic.Kind kind, String message)
Prints a diagnostic message.
void print(Diagnostic.Kind kind, Element element, String message)
Prints a diagnostic message related to an element.
default void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message)
Prints a diagnostic message related to a position within a range of characters in a file.

Method Details

print

void print(Diagnostic.Kind kind, String message)
Prints a diagnostic message.
Parameters:
kind - the kind of diagnostic
message - the message to be printed

print

void print(Diagnostic.Kind kind, DocTreePath path, String message)
Prints a diagnostic message related to a tree node in a documentation comment.
Parameters:
kind - the kind of diagnostic
path - the path for the tree node
message - the message to be printed

print

default void print(Diagnostic.Kind kind, DocTreePath path, int start, int pos, int end, String message)
Prints a diagnostic message related to a position within a range of characters in a tree node. Only kinds of DocTree that wrap a simple string value are supported as leaf nodes of the given path. This currently includes CommentTree, DocTypeTree, ReferenceTree, and TextTree. The positions are all 0-based character offsets from the beginning of string. The positions should satisfy the relation start <= pos <= end.
Implementation Requirements:
This implementation ignores the (start, pos, end) values and simply calls print(kind, path, message).
Parameters:
kind - the kind of diagnostic
path - the path for the tree node
start - the beginning of the enclosing range
pos - the position
end - the end of the enclosing range
message - the message to be printed
Throws:
IllegalArgumentException - if start, pos and end do not form a valid range.
Since:
18

print

void print(Diagnostic.Kind kind, Element element, String message)
Prints a diagnostic message related to an element.
Parameters:
kind - the kind of diagnostic
element - the element
message - the message to be printed

print

default void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message)
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 start <= pos <= end.
Implementation Requirements:
This implementation always throws UnsupportedOperationException. The implementation provided by the javadoc tool to initialize a doclet overrides this implementation.
Parameters:
kind - the kind of diagnostic
file - the file
start - the beginning of the enclosing range
pos - the position
end - the end of the enclosing range
message - the message to be printed
Since:
17

getStandardWriter

default PrintWriter getStandardWriter()
Returns a writer that can be used to write non-diagnostic output, or null if no such writer is available.
API Note:
The value may or may not be the same as that returned by getDiagnosticWriter().
Implementation Requirements:
This implementation returns null. The implementation provided by the javadoc tool to initialize a doclet always returns a non-null value.
Returns:
the writer
Since:
17

getDiagnosticWriter

default PrintWriter getDiagnosticWriter()
Returns a writer that can be used to write diagnostic output, or null if no such writer is available.
API Note:
The value may or may not be the same as that returned by getStandardWriter().
Implementation Requirements:
This implementation returns null. The implementation provided by the javadoc tool to initialize a doclet always returns a non-null value.
Returns:
the writer
Since:
17

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.javadoc/jdk/javadoc/doclet/Reporter.html