1 /* 2 * Copyright (c) 1998, 2016, 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.internal.doclets.toolkit.util; 27 28 import java.text.MessageFormat; 29 import java.util.*; 30 31 import javax.lang.model.element.Element; 32 33 import com.sun.source.util.DocTreePath; 34 import jdk.javadoc.internal.doclets.toolkit.Configuration; 35 36 import static javax.tools.Diagnostic.Kind.*; 37 38 39 /** 40 * Retrieve and format messages stored in a resource. 41 * 42 * <p><b>This is NOT part of any supported API. 43 * If you write code that depends on this, you do so at your own risk. 44 * This code and its internal interfaces are subject to change or 45 * deletion without notice.</b> 46 * 47 * @author Atul M Dambalkar 48 * @author Robert Field 49 */ 50 public class MessageRetriever { 51 /** 52 * The global configuration information for this run. 53 */ 54 private final Configuration configuration; 55 56 /** 57 * The location from which to lazily fetch the resource.. 58 */ 59 private final String resourcelocation; 60 61 /** 62 * The lazily fetched resource.. 63 */ 64 private ResourceBundle messageRB; 65 66 /** 67 * Initialize the ResourceBundle with the given resource. 68 * 69 * @param rb the resource bundle to read. 70 */ 71 public MessageRetriever(ResourceBundle rb) { 72 this.configuration = null; 73 this.messageRB = rb; 74 this.resourcelocation = null; 75 } 76 77 /** 78 * Initialize the ResourceBundle with the given resource. 79 * 80 * @param configuration the configuration 81 * @param resourcelocation Resource. 82 */ 83 public MessageRetriever(Configuration configuration, 84 String resourcelocation) { 85 this.configuration = configuration; 86 this.resourcelocation = resourcelocation; 87 } 88 89 private ResourceBundle initRB() { 90 ResourceBundle bundle = messageRB; 91 if (bundle == null) { 92 try { 93 messageRB = bundle = 94 ResourceBundle.getBundle(resourcelocation, configuration.getLocale()); 95 } catch (MissingResourceException e) { 96 throw new Error("Fatal: Resource (" + resourcelocation 97 + ") for javadoc doclets is missing."); 98 } 99 } 100 return bundle; 101 } 102 103 /** 104 * Determines whether the given <code>key</code> can be retrieved 105 * from this <code>MessageRetriever</code> 106 * 107 * @param key 108 * the resource <code>key</code> 109 * @return <code>true</code> if the given <code>key</code> is 110 * contained in the underlying <code>ResourceBundle</code>. 111 */ 112 public boolean containsKey(String key) { 113 ResourceBundle bundle = initRB(); 114 return bundle.containsKey(key); 115 } 116 117 /** 118 * Get and format message string from resource 119 * 120 * @param key selects message from resource 121 * @param args arguments to be replaced in the message. 122 * @return the composed text 123 * @throws MissingResourceException when the key does not 124 * exist in the properties file. 125 */ 126 public String getText(String key, Object... args) throws MissingResourceException { 127 ResourceBundle bundle = initRB(); 128 String message = bundle.getString(key); 129 return MessageFormat.format(message, args); 130 } 131 132 /** 133 * Print error message, increment error count. 134 * 135 * @param pos the position of the source 136 * @param msg message to print 137 */ 138 private void printError(DocTreePath path, String msg) { 139 configuration.reporter.print(ERROR, path, msg); 140 } 141 142 /** 143 * Print error message, increment error count. 144 * 145 * @param msg message to print 146 */ 147 private void printError(String msg) { 148 configuration.reporter.print(ERROR, msg); 149 } 150 151 /** 152 * Print warning message, increment warning count. 153 * 154 * @param pos the position of the source 155 * @param msg message to print 156 */ 157 private void printWarning(DocTreePath path, String msg) { 158 configuration.reporter.print(WARNING, path, msg); 159 } 160 161 private void printWarning(Element e, String msg) { 162 configuration.reporter.print(WARNING, e, msg); 163 } 164 165 /** 166 * Print warning message, increment warning count. 167 * 168 * @param msg message to print 169 */ 170 private void printWarning(String msg) { 171 configuration.reporter.print(WARNING, msg); 172 } 173 174 // Note: the following do not appear to be needed any more, delete me. 175 // /** 176 // * Print a message. 177 // * 178 // * @param pos the position of the source 179 // * @param msg message to print 180 // */ 181 // private void printNotice(DocTreePath path, String msg) { 182 // DocEnv env = ((RootDocImpl)configuration.root).env; 183 // if (env.isQuiet() || env.isSilent()) { 184 // return; 185 // } 186 // configuration.reporter.print(NOTE, path, msg); 187 // } 188 189 // Note: does not appear to be needed any more. 190 // /** 191 // * Print a message. 192 // * 193 // * @param pos the position of the source 194 // * @param key selects message from resource 195 // * @param args arguments to be replaced in the message. 196 // */ 197 // public void notice(DocTreePath path, String key, Object... args) { 198 // printNotice(path, getText(key, args)); 199 // } 200 201 // ERRORS 202 /** 203 * Print error message, increment error count. 204 * 205 * @param path the path to the source 206 * @param key selects message from resource 207 * @param args arguments to be replaced in the message. 208 */ 209 public void error(DocTreePath path, String key, Object... args) { 210 printError(path, getText(key, args)); 211 } 212 213 /** 214 * Print error message, increment error count. 215 * 216 * @param key selects message from resource 217 * @param args arguments to be replaced in the message. 218 */ 219 public void error(String key, Object... args) { 220 printError(getText(key, args)); 221 } 222 223 // WARNINGS 224 /** 225 * Print warning message, increment warning count. 226 227 * @param path the path to the source 228 * @param key selects message from resource 229 * @param args arguments to be replaced in the message. 230 */ 231 public void warning(DocTreePath path, String key, Object... args) { 232 if (configuration.showMessage(path, key)) 233 printWarning(path, getText(key, args)); 234 } 235 236 /** 237 * Print warning message, increment warning count. 238 * 239 * @param e element target of the message 240 * @param key selects message from resource 241 * @param args arguments to be replaced in the message. 242 */ 243 public void warning(Element e, String key, Object... args) { 244 if (configuration.showMessage(e, key)) 245 printWarning(e, getText(key, args)); 246 } 247 248 /** 249 * Print warning message, increment warning count. 250 * 251 * @param key selects message from resource 252 * @param args arguments to be replaced in the message. 253 */ 254 public void warning(String key, Object... args) { 255 printWarning(getText(key, args)); 256 } 257 258 // NOTICES 259 /** 260 * Print a message. 261 * 262 * @param msg message to print 263 */ 264 private void printNotice(String msg) { 265 if (configuration.quiet) { 266 return; 267 } 268 configuration.reporter.print(NOTE, msg); 269 } 270 271 /** 272 * Print a message. 273 * 274 * @param key selects message from resource 275 * @param args arguments to be replaced in the message. 276 */ 277 public void notice(String key, Object... args) { 278 printNotice(getText(key, args)); 279 } 280 }