1 /*
2  * Copyright (c) 2010, 2012, 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.
8  *
9  * This code is distributed in the hope that it will be useful, but WITHOUT
10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12  * version 2 for more details (a copy is included in the LICENSE file that
13  * accompanied this code).
14  *
15  * You should have received a copy of the GNU General Public License version
16  * 2 along with this work; if not, write to the Free Software Foundation,
17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18  *
19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20  * or visit www.oracle.com if you need additional information or have any
21  * questions.
22  */
23 
24 /*
25  * @test
26  * @bug 8000612
27  * @summary need test program to validate javadoc resource bundles
28  */
29 
30 import java.io.*;
31 import java.util.*;
32 import javax.tools.*;
33 import com.sun.tools.classfile.*;
34 
35 /**
36  * Compare string constants in javadoc classes against keys in javadoc resource bundles.
37  */
38 public class CheckResourceKeys {
39     /**
40      * Main program.
41      * Options:
42      * -finddeadkeys
43      *      look for keys in resource bundles that are no longer required
44      * -findmissingkeys
45      *      look for keys in resource bundles that are missing
46      *
47      * @throws Exception if invoked by jtreg and errors occur
48      */
main(String... args)49     public static void main(String... args) throws Exception {
50         CheckResourceKeys c = new CheckResourceKeys();
51         if (c.run(args))
52             return;
53 
54         if (is_jtreg())
55             throw new Exception(c.errors + " errors occurred");
56         else
57             System.exit(1);
58     }
59 
is_jtreg()60     static boolean is_jtreg() {
61         return (System.getProperty("test.src") != null);
62     }
63 
64     /**
65      * Main entry point.
66      */
run(String... args)67     boolean run(String... args) throws Exception {
68         boolean findDeadKeys = false;
69         boolean findMissingKeys = false;
70 
71         if (args.length == 0) {
72             if (is_jtreg()) {
73                 findDeadKeys = true;
74                 findMissingKeys = true;
75             } else {
76                 System.err.println("Usage: java CheckResourceKeys <options>");
77                 System.err.println("where options include");
78                 System.err.println("  -finddeadkeys      find keys in resource bundles which are no longer required");
79                 System.err.println("  -findmissingkeys   find keys in resource bundles that are required but missing");
80                 return true;
81             }
82         } else {
83             for (String arg: args) {
84                 if (arg.equalsIgnoreCase("-finddeadkeys"))
85                     findDeadKeys = true;
86                 else if (arg.equalsIgnoreCase("-findmissingkeys"))
87                     findMissingKeys = true;
88                 else
89                     error("bad option: " + arg);
90             }
91         }
92 
93         if (errors > 0)
94             return false;
95 
96         Set<String> codeKeys = getCodeKeys();
97         Set<String> resourceKeys = getResourceKeys();
98 
99         System.err.println("found " + codeKeys.size() + " keys in code");
100         System.err.println("found " + resourceKeys.size() + " keys in resource bundles");
101 
102         if (findDeadKeys)
103             findDeadKeys(codeKeys, resourceKeys);
104 
105         if (findMissingKeys)
106             findMissingKeys(codeKeys, resourceKeys);
107 
108         return (errors == 0);
109     }
110 
111     /**
112      * Find keys in resource bundles which are probably no longer required.
113      * A key is required if there is a string in the code that is a resource key,
114      * or if the key is well-known according to various pragmatic rules.
115      */
findDeadKeys(Set<String> codeKeys, Set<String> resourceKeys)116     void findDeadKeys(Set<String> codeKeys, Set<String> resourceKeys) {
117         for (String rk: resourceKeys) {
118             if (codeKeys.contains(rk))
119                 continue;
120 
121             error("Resource key not found in code: " + rk);
122         }
123     }
124 
125     /**
126      * For all strings in the code that look like they might be
127      * a resource key, verify that a key exists.
128      */
findMissingKeys(Set<String> codeKeys, Set<String> resourceKeys)129     void findMissingKeys(Set<String> codeKeys, Set<String> resourceKeys) {
130         for (String ck: codeKeys) {
131             if (resourceKeys.contains(ck))
132                 continue;
133             error("No resource for \"" + ck + "\"");
134         }
135     }
136 
137     /**
138      * Get the set of strings from (most of) the javadoc classfiles.
139      */
getCodeKeys()140     Set<String> getCodeKeys() throws IOException {
141         Set<String> results = new TreeSet<String>();
142         JavaCompiler c = ToolProvider.getSystemJavaCompiler();
143         JavaFileManager fm = c.getStandardFileManager(null, null, null);
144         JavaFileManager.Location javadocLoc = findJavadocLocation(fm);
145         String[] pkgs = {
146             "com.sun.tools.doclets",
147             "com.sun.tools.javadoc"
148         };
149         for (String pkg: pkgs) {
150             for (JavaFileObject fo: fm.list(javadocLoc,
151                     pkg, EnumSet.of(JavaFileObject.Kind.CLASS), true)) {
152                 String name = fo.getName();
153                 // ignore resource files
154                 if (name.matches(".*resources.[A-Za-z_0-9]+\\.class.*"))
155                     continue;
156                 scan(fo, results);
157             }
158         }
159 
160         // special handling for code strings synthesized in
161         // com.sun.tools.doclets.internal.toolkit.util.Util.getTypeName
162         String[] extras = {
163             "AnnotationType", "Class", "Enum", "Error", "Exception", "Interface"
164         };
165         for (String s: extras) {
166             if (results.contains("doclet." + s))
167                 results.add("doclet." + s.toLowerCase());
168         }
169 
170         // special handling for code strings synthesized in
171         // com.sun.tools.javadoc.Messager
172         results.add("javadoc.error.msg");
173         results.add("javadoc.note.msg");
174         results.add("javadoc.note.pos.msg");
175         results.add("javadoc.warning.msg");
176 
177         return results;
178     }
179 
180     // depending on how the test is run, javadoc may be on bootclasspath or classpath
findJavadocLocation(JavaFileManager fm)181     JavaFileManager.Location findJavadocLocation(JavaFileManager fm) {
182         JavaFileManager.Location[] locns =
183             { StandardLocation.PLATFORM_CLASS_PATH, StandardLocation.CLASS_PATH };
184         try {
185             for (JavaFileManager.Location l: locns) {
186                 JavaFileObject fo = fm.getJavaFileForInput(l,
187                     "com.sun.tools.javadoc.Main", JavaFileObject.Kind.CLASS);
188                 if (fo != null) {
189                     System.err.println("found javadoc in " + l);
190                     return l;
191                 }
192             }
193         } catch (IOException e) {
194             throw new Error(e);
195         }
196         throw new IllegalStateException("Cannot find javadoc");
197     }
198 
199     /**
200      * Get the set of strings from a class file.
201      * Only strings that look like they might be a resource key are returned.
202      */
scan(JavaFileObject fo, Set<String> results)203     void scan(JavaFileObject fo, Set<String> results) throws IOException {
204         //System.err.println("scan " + fo.getName());
205         InputStream in = fo.openInputStream();
206         try {
207             ClassFile cf = ClassFile.read(in);
208             for (ConstantPool.CPInfo cpinfo: cf.constant_pool.entries()) {
209                 if (cpinfo.getTag() == ConstantPool.CONSTANT_Utf8) {
210                     String v = ((ConstantPool.CONSTANT_Utf8_info) cpinfo).value;
211                     if (v.matches("(doclet|main|javadoc|tag)\\.[A-Za-z0-9-_.]+"))
212                         results.add(v);
213                 }
214             }
215         } catch (ConstantPoolException ignore) {
216         } finally {
217             in.close();
218         }
219     }
220 
221     /**
222      * Get the set of keys from the javadoc resource bundles.
223      */
getResourceKeys()224     Set<String> getResourceKeys() {
225         String[] names = {
226                 "com.sun.tools.doclets.formats.html.resources.standard",
227                 "com.sun.tools.doclets.internal.toolkit.resources.doclets",
228                 "com.sun.tools.javadoc.resources.javadoc",
229         };
230         Set<String> results = new TreeSet<String>();
231         for (String name : names) {
232             ResourceBundle b = ResourceBundle.getBundle(name);
233             results.addAll(b.keySet());
234         }
235         return results;
236     }
237 
238     /**
239      * Report an error.
240      */
error(String msg)241     void error(String msg) {
242         System.err.println("Error: " + msg);
243         errors++;
244     }
245 
246     int errors;
247 }
248