OpenJDK 1.22 · jdk.javadoc.doclet.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 javax.tools.DocumentationTool API allows a client to specify a javax.tools.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 java.util.spi.ToolProvider API allows a client to specify the streams to be used for reporting standard and diagnostic output.

Method Summary

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

Method Detail

getDiagnosticWriter back to summary

getDiagnosticWriter	back to summary
public 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 Specification This implementation returns `null`. The implementation provided by the `javadoc` tool to `initialize` a doclet always returns a non-`null` value. Returns:PrintWriter the writer Since 17

public 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 Specification

This implementation returns null. The implementation provided by the javadoc tool to initialize a doclet always returns a non-null value.

Returns:PrintWriter: the writer
Since: 17

getStandardWriter back to summary

getStandardWriter	back to summary
public 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 Specification This implementation returns `null`. The implementation provided by the `javadoc` tool to `initialize` a doclet always returns a non-`null` value. Returns:PrintWriter the writer Since 17

public 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 Specification

This implementation returns null. The implementation provided by the javadoc tool to initialize a doclet always returns a non-null value.

Returns:PrintWriter: the writer
Since: 17

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

back to summary

public void print(Diagnostic.Kind kind, String message)

Prints a diagnostic message.

Parameters

kind:Diagnostic.Kind: the kind of diagnostic
message:String: the message to be printed

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

back to summary

public void print(Diagnostic.Kind kind, DocTreePath path, String message)

Prints a diagnostic message related to a tree node in a documentation comment.

Parameters

kind:Diagnostic.Kind: the kind of diagnostic
path:DocTreePath: the path for the tree node
message:String: the message to be printed

print back to summary

print	back to summary
public 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 Specification This implementation ignores the `(start, pos, end)` values and simply calls `print(kind, path, message)`. Parameters kind:Diagnostic.Kind the kind of diagnostic path:DocTreePath the path for the tree node start:int the beginning of the enclosing range pos:int the position end:int the end of the enclosing range message:String the message to be printed Exceptions IllegalArgumentException: if `start`, `pos` and `end` do not form a valid range. Since 18

public 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 Specification

This implementation ignores the (start, pos, end) values and simply calls print(kind, path, message).

Parameters

kind:Diagnostic.Kind: the kind of diagnostic
path:DocTreePath: the path for the tree node
start:int: the beginning of the enclosing range
pos:int: the position
end:int: the end of the enclosing range
message:String: the message to be printed

Exceptions

IllegalArgumentException:: if start, pos and end do not form a valid range.

Since

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

back to summary

public void print(Diagnostic.Kind kind, Element element, String message)

Prints a diagnostic message related to an element.

Parameters

kind:Diagnostic.Kind: the kind of diagnostic
element:Element: the element
message:String: the message to be printed

print back to summary

print	back to summary
public 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 Specification This implementation always throws `UnsupportedOperationException`. The implementation provided by the `javadoc` tool to `initialize` a doclet overrides this implementation. Parameters kind:Diagnostic.Kind the kind of diagnostic file:FileObject the file start:int the beginning of the enclosing range pos:int the position end:int the end of the enclosing range message:String the message to be printed Since 17

public 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 Specification

This implementation always throws UnsupportedOperationException. The implementation provided by the javadoc tool to initialize a doclet overrides this implementation.

Parameters

kind:Diagnostic.Kind: the kind of diagnostic
file:FileObject: the file
start:int: the beginning of the enclosing range
pos:int: the position
end:int: the end of the enclosing range
message:String: the message to be printed

Since

public Interface Reporter

Method Summary

Method Detail