1 /* 2 * Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package jdk.javadoc.doclet; 27 28 import java.io.PrintWriter; 29 import java.util.Locale; 30 import javax.lang.model.element.Element; 31 import javax.tools.Diagnostic; 32 import javax.tools.FileObject; 33 34 import com.sun.source.util.DocTreePath; 35 36 /** 37 * Interface for reporting diagnostics and other messages. 38 * 39 * <p>Diagnostics consist of a {@link Diagnostic.Kind diagnostic kind} and a message, 40 * and may additionally be associated with an {@link Element element}, 41 * a {@link DocTreePath tree node} in a documentation comment, 42 * or an arbitrary position in a given {@link FileObject file}. 43 * Other messages may be written directly to one of two streams that are informally 44 * for use by "standard output" and "diagnostic output", where "standard output" 45 * means the output that is the expected result of executing some operation, 46 * such as the command-line help that is generated when using a {@code --help} option, 47 * and "diagnostic output" refers to any errors, warnings and other output that is 48 * a side-effect of executing the operation. 49 * 50 * <p>The exact manner in which diagnostics are output is unspecified and depends 51 * on the enclosing context. For example: 52 * <ul> 53 * <li>The {@link javax.tools.DocumentationTool} API allows a client to specify a 54 * {@link javax.tools.DiagnosticListener} to which diagnostics will be 55 * {@link javax.tools.DiagnosticListener#report reported}. If no listener is specified, 56 * diagnostics will be written to a given stream, or to {@code System.err} if no such 57 * stream is provided. 58 * <li>The {@link java.util.spi.ToolProvider} API allows a client to specify 59 * the streams to be used for reporting standard and diagnostic output. 60 * </ul> 61 * 62 * @since 9 63 */ 64 public interface Reporter { 65 66 /** 67 * Prints a diagnostic message. 68 * 69 * @param kind the kind of diagnostic 70 * @param message the message to be printed 71 */ print(Diagnostic.Kind kind, String message)72 void print(Diagnostic.Kind kind, String message); 73 74 /** 75 * Prints a diagnostic message related to a tree node in a documentation comment. 76 * 77 * @param kind the kind of diagnostic 78 * @param path the path for the tree node 79 * @param message the message to be printed 80 */ print(Diagnostic.Kind kind, DocTreePath path, String message)81 void print(Diagnostic.Kind kind, DocTreePath path, String message); 82 83 /** 84 * Prints a diagnostic message related to an element. 85 * 86 * @param kind the kind of diagnostic 87 * @param element the element 88 * @param message the message to be printed 89 */ print(Diagnostic.Kind kind, Element element, String message)90 void print(Diagnostic.Kind kind, Element element, String message); 91 92 /** 93 * Prints a diagnostic message related to a position within a range of characters in a file. 94 * The positions are all 0-based character offsets from the beginning of content of the file. 95 * The positions should satisfy the relation {@code start <= pos <= end}. 96 * 97 * @implSpec 98 * This implementation always throws {@code UnsupportedOperationException}. 99 * The implementation provided by the {@code javadoc} tool to 100 * {@link Doclet#init(Locale, Reporter) initialize} a doclet 101 * overrides this implementation. 102 * 103 * @param kind the kind of diagnostic 104 * @param file the file 105 * @param start the beginning of the enclosing range 106 * @param pos the position 107 * @param end the end of the enclosing range 108 * @param message the message to be printed 109 * 110 * @since 17 111 */ print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message)112 default void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message) { 113 throw new UnsupportedOperationException(); 114 } 115 116 /** 117 * Returns a writer that can be used to write non-diagnostic output, 118 * or {@code null} if no such writer is available. 119 * 120 * @apiNote 121 * The value may or may not be the same as that returned by {@link #getDiagnosticWriter()}. 122 * 123 * @implSpec 124 * This implementation returns {@code null}. 125 * The implementation provided by the {@code javadoc} tool to 126 * {@link Doclet#init(Locale, Reporter) initialize} a doclet 127 * always returns a non-{@code null} value. 128 * 129 * @return the writer 130 * @since 17 131 */ getStandardWriter()132 default PrintWriter getStandardWriter() { 133 return null; 134 } 135 136 /** 137 * Returns a writer that can be used to write diagnostic output, 138 * or {@code null} if no such writer is available. 139 * 140 * @apiNote 141 * The value may or may not be the same as that returned by {@link #getStandardWriter()}. 142 * 143 * @implSpec 144 * This implementation returns {@code null}. 145 * The implementation provided by the {@code javadoc} tool to 146 * {@link Doclet#init(Locale, Reporter) initialize} a doclet 147 * always returns a non-{@code null} value. 148 * 149 * @return the writer 150 * @since 17 151 */ getDiagnosticWriter()152 default PrintWriter getDiagnosticWriter() { 153 return null; 154 } 155 156 } 157