Class for reporting diagnostics and other messages. The class leverages the javac support for reporting diagnostics, for stylistic consistency of diagnostic messages and to avoid code duplication. The class is a subtype of javac's Log, and is primarily an adapter between javadoc method signatures and the underlying javac methods. Within this class, the methods call down to a core report method which hands off to a similar method in the superclass (Log.report, which takes care of reporting the diagnostic (unless it has been suppressed), displaying the source line and a caret to indicate the position of the issue (if appropriate), counting errors and warnings, and so on. In general, the underlying javac layer is more powerful, whereas the javadoc methods are constrained by the public jdk.javadoc.doclet.Doclet API. In the underlying javac layer, the following abstractions are used:

DiagnosticType -- error, warning, note, etc.
DiagnosticSource -- a file object and a cache of its content
DiagnosticPosition -- a tuple of values (start, pos, end) for the position of a diagnostic
DiagnosticFlag -- additional flags related to the diagnostic

The javadoc layer is defined by the methods on Doclet.Reporter, and by assorted methods defined in this class for use by the javadoc tool. The primary data types are:

Diagnostic.Kind -- maps to DiagnosticType and Set<DiagnosticFlag>
Element -- maps to DiagnosticSource and DiagnosticPosition
DocTreePath -- maps to DiagnosticSource and DiagnosticPosition

The reporting methods in the javac layer primarily take pre-localized (key, args) pairs, while the methods in the javadoc layer, especially the Reporter interface, take localized strings. To accommodate this, "wrapper" resources are used, whose value is {0}, to pass the localized string down to javac. A side-effect is that clients using a DiagnosticListener with a DocumentationTask cannot access the original resource key for the localized message. Given the limitations of the API, it is not possible to do any better. The javac Annotation Processing API has the same problem. There is a slight disparity between javac's use of streams and javadoc's use of streams. javac reports all diagnostics to the "error" stream, and provides a separate "output" stream for expected output, such as command-line help or the output from options like -Xprint. javadoc API, and Reporter in particular, does not specify the use of streams, and provides no support for identifying or specifying streams. JDK-8267204. The current implementation/workaround is to write errors and warnings to the "error" stream and notes to the "output" stream.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private class	JavadocLog.WrappingJavaFileObject

Field Summary

Modifier and Type	Field and Description
private final Context	context Hides com.sun.tools.javac.util.Log.context. The overall context for the documentation run.
private final LinkedHashMap<JavaFileObject, SoftReference<DiagnosticSource>>	diagSourceCache A memory-sensitive cache of recently used `DiagnosticSource` objects.
private final JCDiagnostic.Factory	javadocDiags
private Locale	locale
private final JavacMessages	messages Hides com.sun.tools.javac.util.Log.messages.
pack-priv final String	programName
private DocSourcePositions	sourcePositions The utility class to access the positions of items in doc comments.
private ToolEnvironment	toolEnv The tool environment, providing access to the tool's utility classes and tables.

Constructor Summary

Access	Constructor and Description
public	JavadocLog(Context context, String Name of the program (for error messages). programName) Constructor
public	JavadocLog(Context context, String Name of the program (for error messages). programName, PrintWriter Stream for notices etc. outWriter, PrintWriter Stream for errors and warnings errWriter) Constructor

Method Summary

Modifier and Type	Method and Description
private JCDiagnostic.DiagnosticPosition	Returns: the diagnostic position createDiagnosticPosition(JCTree the tree node, or null if no tree is applicable tree, int the start position start, int the "preferred" position: this is used to position the caret in messages pos, int the end position end) Creates a diagnostic position.
private static PrintWriter	createPrintWriter(PrintStream ps, boolean autoflush)
private Set<JCDiagnostic.DiagnosticFlag>	Returns: the flags getDiagnosticFlags(Diagnostic.Kind the diagnostic kind kind) Returns the diagnostic flags for a diagnostic kind.
private JCDiagnostic.DiagnosticPosition	Returns: the diagnostic position getDiagnosticPosition(DocTreePath the path for the documentation tree node path) Returns a diagnostic position for a documentation tree node.
private JCDiagnostic.DiagnosticPosition	Returns: the diagnostic position getDiagnosticPosition(Element the element element) Returns a diagnostic position for an element, or `null` if the source file is not available.
private DiagnosticSource	Returns: the diagnostic source getDiagnosticSource(DocTreePath the path for the documentation tree node path) Returns the diagnostic source for a documentation tree node.
private DiagnosticSource	Returns: the diagnostic source getDiagnosticSource(Element the element element) Returns the diagnostic source for an element, or `NO_SOURCE` if the source file is not known (for example, if the element was read from a class file).
private DiagnosticSource	Returns: the diagnostic source getDiagnosticSource(JavaFileObject the file object fo) Returns the diagnostic source for a file object.
private JCDiagnostic.DiagnosticType	Returns: the diagnostic type getDiagnosticType(Diagnostic.Kind the diagnostic kind kind) Returns the diagnostic type for a diagnostic kind.
public PrintWriter	getDiagnosticWriter() Overrides default jdk.javadoc.doclet.Reporter.getDiagnosticWriter. Returns a writer that can be used to write diagnostic output, or `null` if no such writer is available.
private DocSourcePositions	Returns: the object for computing source positions getSourcePositions() Returns the object for computing source positions.
public PrintWriter	getStandardWriter() Overrides default jdk.javadoc.doclet.Reporter.getStandardWriter. Returns a writer that can be used to write non-diagnostic output, or `null` if no such writer is available.
pack-priv String	getText(String the resource key key, Object... arguments for the resource args) Returns the localized string from the tool's resource bundles.
private ToolEnvironment	Returns: the tool environment getToolEnv() Returns the tool environment.
public boolean	hasErrors() Returns true if errors have been recorded.
public boolean	hasWarnings() Returns true if warnings have been recorded.
public static JavadocLog	instance0(Context context) Get the current javadoc log, which is also the compiler log.
public static void	preRegister(Context context, final String programName)
public static void	preRegister(Context context, final String programName, final PrintWriter outWriter, final PrintWriter errWriter)
public void	print(Diagnostic.Kind kind, String message) Implements jdk.javadoc.doclet.Reporter.print. Prints a diagnostic message.
public void	print(Diagnostic.Kind kind, DocTreePath path, String message) Implements jdk.javadoc.doclet.Reporter.print. Prints a diagnostic message related to a tree node in a documentation comment.
public void	print(Diagnostic.Kind kind, DocTreePath path, int start, int pos, int end, String message) Overrides default jdk.javadoc.doclet.Reporter.print. Prints a diagnostic message related to a position within a range of characters in a tree node.
public void	print(Diagnostic.Kind kind, Element element, String message) Implements jdk.javadoc.doclet.Reporter.print. Prints a diagnostic message related to an element.
public void	print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message) Overrides default jdk.javadoc.doclet.Reporter.print. Prints a diagnostic message related to a position within a range of characters in a file.
private void	printCount(int count, String singleKey, String pluralKey)
public void	printError(String the message message) Prints an error message.
public void	printError(DocTreePath the path for the documentation tree node path, String the message message) Prints an error message for a given documentation tree node.
public void	printError(Element the element element, String the message message) Prints an error message for a given element.
public void	printErrorUsingKey(String the resource key for the message key, Object... the arguments for the message args) Prints an error message.
public void	printErrorWarningCounts() Prints the error and warning counts, if any, to the diagnostic writer.
public void	printNote(String the message message) Prints a "notice" message.
public void	printNoteUsingKey(String the resource key for the message key, Object... the arguments for the message args) Prints a "notice" message.
public void	printWarning(String the message message) Prints a warning message.
public void	printWarning(DocTreePath the path for the documentation tree node path, String the message message) Prints a warning message for a given documentation tree node.
public void	printWarning(Element the element element, String the message message) Prints a warning message for a given element.
public void	printWarningUsingKey(String the resource key for the message key, Object... the arguments for the message args) Prints a warning message.
public void	printWarningUsingKey(Element the element element, String the resource key for the message key, Object... the arguments for the message args) Prints a warning message for an element.
private void	report(Diagnostic.Kind the kind of diagnostic kind, DiagnosticSource the diagnostic source ds, JCDiagnostic.DiagnosticPosition the diagnostic position dp, String the message message) Reports a diagnostic message.
private void	report(JCDiagnostic.DiagnosticType the diagnostic type dt, DiagnosticSource the diagnostic source ds, JCDiagnostic.DiagnosticPosition the diagnostic position dp, String the message message) Reports a diagnostic message.
private void	report(JCDiagnostic.DiagnosticType the diagnostic type dt, Set<JCDiagnostic.DiagnosticFlag> flags, DiagnosticSource the diagnostic source ds, JCDiagnostic.DiagnosticPosition the diagnostic position dp, String the message message) Reports a diagnostic message, with diagnostic flags.
public void	setLocale(Locale locale)

Field Detail

context	back to summary
private final Context context Hides com.sun.tools.javac.util.Log.context. The overall context for the documentation run.

context

Modifier and Type	Method and Description
public Modifier	getAccessLevel() Implements javax.tools.JavaFileObject.getAccessLevel. Provides a hint about the access level of the class represented by this file object.
public JavaFileObject.Kind	getKind() Implements javax.tools.JavaFileObject.getKind. Returns the kind of this file object.
public NestingKind	getNestingKind() Implements javax.tools.JavaFileObject.getNestingKind. Provides a hint about the nesting level of the class represented by this file object.
public boolean	isNameCompatible(String simpleName, JavaFileObject.Kind kind) Implements javax.tools.JavaFileObject.isNameCompatible. Checks if this file object is compatible with the specified simple name and kind.

public Class JavadocLog

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class JavadocLog.WrappingJavaFileObject

Field Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail