1 /* 2 * Copyright (c) 2016, 2017, 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 package jdk.javadoc.internal.doclets.toolkit; 26 27 import javax.lang.model.element.Element; 28 import javax.tools.Diagnostic; 29 30 import com.sun.source.util.DocTreePath; 31 import jdk.javadoc.doclet.Reporter; 32 33 import static javax.tools.Diagnostic.Kind.*; 34 35 /** 36 * Provides standardized access to the diagnostic reporting facilities 37 * for a doclet. 38 * 39 * Messages are specified by resource keys to be found in the doclet's 40 * {@link Resources resources}. Values can be substituted into the 41 * strings obtained from the resource files. 42 * 43 * Messages are reported to the doclet's {@link Reporter reporter}. 44 */ 45 public class Messages { 46 private final BaseConfiguration configuration; 47 private final Resources resources; 48 private Reporter reporter; 49 50 /** 51 * Creates a {@code Messages} object to provide standardized access to 52 * the doclet's diagnostic reporting mechanisms. 53 * 54 * @param configuration the doclet's configuration, used to access 55 * the doclet's resources, reporter, and additional methods and state 56 * used to filter out messages, if any, which should be suppressed. 57 */ 58 public Messages(BaseConfiguration configuration) { 59 this.configuration = configuration; 60 resources = configuration.getResources(); 61 } 62 63 // ***** Errors ***** 64 65 /** 66 * Reports an error message to the doclet's reporter. 67 * 68 * @param key the name of a resource containing the message to be printed 69 * @param args optional arguments to be replaced in the message. 70 */ 71 public void error(String key, Object... args) { 72 report(ERROR, resources.getText(key, args)); 73 } 74 75 /** 76 * Reports an error message to the doclet's reporter. 77 * 78 * @param path a path identifying the position to be included with 79 * the message 80 * @param key the name of a resource containing the message to be printed 81 * @param args optional arguments to be replaced in the message. 82 */ 83 public void error(DocTreePath path, String key, Object... args) { 84 report(ERROR, path, resources.getText(key, args)); 85 } 86 87 // ***** Warnings ***** 88 89 /** 90 * Reports a warning message to the doclet's reporter. 91 * 92 * @param key the name of a resource containing the message to be printed 93 * @param args optional arguments to be replaced in the message. 94 */ 95 public void warning(String key, Object... args) { 96 report(WARNING, resources.getText(key, args)); 97 } 98 99 /** 100 * Reports a warning message to the doclet's reporter. 101 * 102 * @param path a path identifying the position to be included with 103 * the message 104 * @param key the name of a resource containing the message to be printed 105 * @param args optional arguments to be replaced in the message. 106 */ 107 public void warning(DocTreePath path, String key, Object... args) { 108 if (configuration.showMessage(path, key)) 109 report(WARNING, path, resources.getText(key, args)); 110 } 111 112 /** 113 * Reports a warning message to the doclet's reporter. 114 * 115 * @param e an element identifying the declaration whose position should 116 * to be included with the message 117 * @param key the name of a resource containing the message to be printed 118 * @param args optional arguments to be replaced in the message. 119 */ 120 public void warning(Element e, String key, Object... args) { 121 if (configuration.showMessage(e, key)) { 122 report(WARNING, e, resources.getText(key, args)); 123 } 124 } 125 126 // ***** Notices ***** 127 128 /** 129 * Reports an informational notice to the doclet's reporter. 130 * 131 * @param key the name of a resource containing the message to be printed 132 * @param args optional arguments to be replaced in the message. 133 */ 134 public void notice(String key, Object... args) { 135 if (!configuration.getOptions().quiet) { 136 report(NOTE, resources.getText(key, args)); 137 } 138 } 139 140 // ***** Internal support ***** 141 142 private void report(Diagnostic.Kind k, String msg) { 143 initReporter(); 144 reporter.print(k, msg); 145 } 146 147 private void report(Diagnostic.Kind k, DocTreePath p, String msg) { 148 initReporter(); 149 reporter.print(k, p, msg); 150 } 151 152 private void report(Diagnostic.Kind k, Element e, String msg) { 153 initReporter(); 154 reporter.print(k, e, msg); 155 } 156 157 // Lazy init the reporter for now, until we can fix/improve 158 // the init of HtmlConfiguration in HtmlDoclet (and similar.) 159 private void initReporter() { 160 if (reporter == null) { 161 reporter = configuration.reporter; 162 } 163 } 164 }