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 * @since 1.2
48 * @author Atul M Dambalkar
49 * @author Robert Field
50 */
51 public class MessageRetriever {
52 /**
53 * The global configuration information for this run.
54 */
55 private final Configuration configuration;
56
57 /**
58 * The location from which to lazily fetch the resource..
59 */
60 private final String resourcelocation;
61
62 /**
63 * The lazily fetched resource..
64 */
65 private ResourceBundle messageRB;
66
67 /**
68 * Initialize the ResourceBundle with the given resource.
69 *
70 * @param rb the resource bundle to read.
71 */
72 public MessageRetriever(ResourceBundle rb) {
73 this.configuration = null;
74 this.messageRB = rb;
75 this.resourcelocation = null;
76 }
77
78 /**
79 * Initialize the ResourceBundle with the given resource.
80 *
81 * @param configuration the configuration
82 * @param resourcelocation Resource.
83 */
84 public MessageRetriever(Configuration configuration,
85 String resourcelocation) {
86 this.configuration = configuration;
87 this.resourcelocation = resourcelocation;
88 }
89
90 private void initRB() {
91 if (messageRB == null) {
92 try {
93 messageRB = ResourceBundle.getBundle(resourcelocation, configuration.getLocale());
94 } catch (MissingResourceException e) {
95 throw new Error("Fatal: Resource (" + resourcelocation
96 + ") for javadoc doclets is missing.");
97 }
98 }
99 }
100
101 /**
102 * Returns a list of key in the ResourceBundle.
103 * @return list of keys.
104 */
105 public List<String> getKeys() {
106 initRB();
107 return Collections.list(messageRB.getKeys());
108 }
109
110 /**
111 * Get and format message string from resource
112 *
113 * @param key selects message from resource
114 * @param args arguments to be replaced in the message.
115 * @return the composed text
116 * @throws MissingResourceException when the key does not
117 * exist in the properties file.
118 */
119 public String getText(String key, Object... args) throws MissingResourceException {
120 initRB();
121 String message = messageRB.getString(key);
122 return MessageFormat.format(message, args);
123 }
124
125 /**
126 * Print error message, increment error count.
127 *
128 * @param pos the position of the source
129 * @param msg message to print
130 */
131 private void printError(DocTreePath path, String msg) {
132 configuration.reporter.print(ERROR, path, msg);
133 }
134
135 /**
136 * Print error message, increment error count.
137 *
138 * @param msg message to print
139 */
140 private void printError(String msg) {
141 configuration.reporter.print(ERROR, msg);
142 }
143
144 /**
145 * Print warning message, increment warning count.
146 *
147 * @param pos the position of the source
148 * @param msg message to print
149 */
150 private void printWarning(DocTreePath path, String msg) {
151 configuration.reporter.print(WARNING, path, msg);
152 }
153
154 private void printWarning(Element e, String msg) {
155 configuration.reporter.print(WARNING, e, msg);
156 }
157
158 /**
159 * Print warning message, increment warning count.
160 *
161 * @param msg message to print
162 */
163 private void printWarning(String msg) {
164 configuration.reporter.print(WARNING, msg);
165 }
166
167 // Note: the following do not appear to be needed any more, delete me.
168 // /**
169 // * Print a message.
170 // *
171 // * @param pos the position of the source
172 // * @param msg message to print
173 // */
174 // private void printNotice(DocTreePath path, String msg) {
175 // DocEnv env = ((RootDocImpl)configuration.root).env;
176 // if (env.isQuiet() || env.isSilent()) {
177 // return;
178 // }
179 // configuration.reporter.print(NOTE, path, msg);
180 // }
181
182 // Note: does not appear to be needed any more.
183 // /**
184 // * Print a message.
185 // *
186 // * @param pos the position of the source
187 // * @param key selects message from resource
188 // * @param args arguments to be replaced in the message.
189 // */
190 // public void notice(DocTreePath path, String key, Object... args) {
191 // printNotice(path, getText(key, args));
192 // }
193
194 // ERRORS
195 /**
196 * Print error message, increment error count.
197 *
198 * @param path the path to the source
199 * @param key selects message from resource
200 * @param args arguments to be replaced in the message.
201 */
202 public void error(DocTreePath path, String key, Object... args) {
203 printError(path, getText(key, args));
204 }
205
206 /**
207 * Print error message, increment error count.
208 *
209 * @param key selects message from resource
210 * @param args arguments to be replaced in the message.
211 */
212 public void error(String key, Object... args) {
213 printError(getText(key, args));
214 }
215
216 // WARNINGS
217 /**
218 * Print warning message, increment warning count.
219
220 * @param path the path to the source
221 * @param key selects message from resource
222 * @param args arguments to be replaced in the message.
223 */
224 public void warning(DocTreePath path, String key, Object... args) {
225 if (configuration.showMessage(path, key))
226 printWarning(path, getText(key, args));
227 }
228
229 /**
230 * Print warning message, increment warning count.
231 *
232 * @param e element target of the message
233 * @param key selects message from resource
234 * @param args arguments to be replaced in the message.
235 */
236 public void warning(Element e, String key, Object... args) {
237 if (configuration.showMessage(e, key))
238 printWarning(e, getText(key, args));
239 }
240
241 /**
242 * Print warning message, increment warning count.
243 *
244 * @param key selects message from resource
245 * @param args arguments to be replaced in the message.
246 */
247 public void warning(String key, Object... args) {
248 printWarning(getText(key, args));
249 }
250
251 // NOTICES
252 /**
253 * Print a message.
254 *
255 * @param msg message to print
256 */
257 private void printNotice(String msg) {
258 if (configuration.quiet) {
259 return;
260 }
261 configuration.reporter.print(NOTE, msg);
262 }
263
264 /**
265 * Print a message.
266 *
267 * @param key selects message from resource
268 * @param args arguments to be replaced in the message.
269 */
270 public void notice(String key, Object... args) {
271 printNotice(getText(key, args));
272 }
273 }