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 aDiagnosticListener
to which diagnostics will bereported
. If no listener is specified, diagnostics will be written to a given stream, or toSystem.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 TypeMethodDescriptiondefault PrintWriter
Returns a writer that can be used to write diagnostic output, ornull
if no such writer is available.default PrintWriter
Returns a writer that can be used to write non-diagnostic output, ornull
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
Prints a diagnostic message.- Parameters:
kind
- the kind of diagnosticmessage
- the message to be printed
-
print
Prints a diagnostic message related to a tree node in a documentation comment.- Parameters:
kind
- the kind of diagnosticpath
- the path for the tree nodemessage
- 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 ofDocTree
that wrap a simple string value are supported as leaf nodes of the given path. This currently includesCommentTree
,DocTypeTree
,ReferenceTree
, andTextTree
. The positions are all 0-based character offsets from the beginning of string. The positions should satisfy the relationstart <= pos <= end
.- Implementation Requirements:
- This implementation ignores the
(start, pos, end)
values and simply callsprint(kind, path, message)
. - Parameters:
kind
- the kind of diagnosticpath
- the path for the tree nodestart
- the beginning of the enclosing rangepos
- the positionend
- the end of the enclosing rangemessage
- the message to be printed- Throws:
IllegalArgumentException
- ifstart
,pos
andend
do not form a valid range.- Since:
- 18
-
print
Prints a diagnostic message related to an element.- Parameters:
kind
- the kind of diagnosticelement
- the elementmessage
- 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 relationstart <= pos <= end
.- Implementation Requirements:
- This implementation always throws
UnsupportedOperationException
. The implementation provided by thejavadoc
tool toinitialize
a doclet overrides this implementation. - Parameters:
kind
- the kind of diagnosticfile
- the filestart
- the beginning of the enclosing rangepos
- the positionend
- the end of the enclosing rangemessage
- the message to be printed- Since:
- 17
-
getStandardWriter
Returns a writer that can be used to write non-diagnostic output, ornull
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 thejavadoc
tool toinitialize
a doclet always returns a non-null
value. - Returns:
- the writer
- Since:
- 17
-
getDiagnosticWriter
Returns a writer that can be used to write diagnostic output, ornull
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 thejavadoc
tool toinitialize
a doclet always returns a non-null
value. - Returns:
- the writer
- Since:
- 17
-