CheckResourceKeys.java revision 3673:8bf23828bb2f 
1/*
2 * Copyright (c) 2010, 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.
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 * @modules jdk.javadoc/jdk.javadoc.internal.tool
29 *          jdk.jdeps/com.sun.tools.classfile
30 */
31
32import java.io.*;
33import java.lang.reflect.Layer;
34import java.lang.reflect.Module;
35import java.util.*;
36import javax.tools.*;
37import com.sun.tools.classfile.*;
38
39/**
40 * Compare string constants in javadoc classes against keys in javadoc resource bundles.
41 */
42public class CheckResourceKeys {
43    /**
44     * Main program.
45     * Options:
46     * -finddeadkeys
47     *      look for keys in resource bundles that are no longer required
48     * -findmissingkeys
49     *      look for keys in resource bundles that are missing
50     *
51     * @throws Exception if invoked by jtreg and errors occur
52     */
53    public static void main(String... args) throws Exception {
54        CheckResourceKeys c = new CheckResourceKeys();
55        if (c.run(args))
56            return;
57
58        if (is_jtreg())
59            throw new Exception(c.errors + " errors occurred");
60        else
61            System.exit(1);
62    }
63
64    static boolean is_jtreg() {
65        return (System.getProperty("test.src") != null);
66    }
67
68    /**
69     * Main entry point.
70     */
71    boolean run(String... args) throws Exception {
72        boolean findDeadKeys = false;
73        boolean findMissingKeys = false;
74
75        if (args.length == 0) {
76            if (is_jtreg()) {
77                findDeadKeys = true;
78                findMissingKeys = true;
79            } else {
80                System.err.println("Usage: java CheckResourceKeys <options>");
81                System.err.println("where options include");
82                System.err.println("  -finddeadkeys      find keys in resource bundles which are no longer required");
83                System.err.println("  -findmissingkeys   find keys in resource bundles that are required but missing");
84                return true;
85            }
86        } else {
87            for (String arg: args) {
88                if (arg.equalsIgnoreCase("-finddeadkeys"))
89                    findDeadKeys = true;
90                else if (arg.equalsIgnoreCase("-findmissingkeys"))
91                    findMissingKeys = true;
92                else
93                    error("bad option: " + arg);
94            }
95        }
96
97        if (errors > 0)
98            return false;
99
100        Set<String> codeKeys = getCodeKeys();
101        Set<String> resourceKeys = getResourceKeys();
102
103        System.err.println("found " + codeKeys.size() + " keys in code");
104        System.err.println("found " + resourceKeys.size() + " keys in resource bundles");
105
106        if (findDeadKeys)
107            findDeadKeys(codeKeys, resourceKeys);
108
109        if (findMissingKeys)
110            findMissingKeys(codeKeys, resourceKeys);
111
112        usageTests(false);
113        usageTests(true);
114
115        return (errors == 0);
116    }
117
118    void usageTests(boolean xflag) {
119        String[] argarray = { xflag ? "-X" : "-help" };
120        StringWriter sw = new StringWriter();
121        PrintWriter pw = new PrintWriter(sw);
122        if (jdk.javadoc.internal.tool.Main.execute(argarray, pw) == 0) {
123            pw.flush();
124            String s = sw.toString();
125            if (s.isEmpty()) {
126                error("no javadoc output ?");
127                return;
128            }
129            if (sw.toString().contains("<MISSING KEY>")) {
130                System.out.println(s);
131                error("missing resources in output ?");
132            }
133        } else {
134            error("failed to execute javadoc");
135        }
136    }
137
138    /**
139     * Find keys in resource bundles which are probably no longer required.
140     * A key is required if there is a string in the code that is a resource key,
141     * or if the key is well-known according to various pragmatic rules.
142     */
143    void findDeadKeys(Set<String> codeKeys, Set<String> resourceKeys) {
144        for (String rk: resourceKeys) {
145            // ignore these synthesized keys, tested by usageTests
146            if (rk.startsWith("doclet.usage.") || rk.startsWith("doclet.xusage"))
147                continue;
148            // ignore these synthesized keys, tested by usageTests
149            if (rk.matches("main\\.opt\\..*\\.(arg|desc)"))
150                continue;
151            if (codeKeys.contains(rk))
152                continue;
153
154            error("Resource key not found in code: '" + rk + '"');
155        }
156    }
157
158    /**
159     * For all strings in the code that look like they might be
160     * a resource key, verify that a key exists.
161     */
162    void findMissingKeys(Set<String> codeKeys, Set<String> resourceKeys) {
163        for (String ck: codeKeys) {
164            // ignore these synthesized keys, tested by usageTests
165            if (ck.startsWith("doclet.usage.") || ck.startsWith("doclet.xusage."))
166                continue;
167            // ignore this partial key, tested by usageTests
168            if (ck.equals("main.opt."))
169                continue;
170            if (resourceKeys.contains(ck))
171                continue;
172            error("No resource for \"" + ck + "\"");
173        }
174    }
175
176    /**
177     * Get the set of strings from (most of) the javadoc classfiles.
178     */
179    Set<String> getCodeKeys() throws IOException {
180        Set<String> results = new TreeSet<String>();
181        JavaCompiler c = ToolProvider.getSystemJavaCompiler();
182        try (JavaFileManager fm = c.getStandardFileManager(null, null, null)) {
183            JavaFileManager.Location javadocLoc = findJavadocLocation(fm);
184            String[] pkgs = {
185                "jdk.javadoc.internal.doclets",
186                "jdk.javadoc.internal.tool"
187            };
188            for (String pkg: pkgs) {
189                for (JavaFileObject fo: fm.list(javadocLoc,
190                        pkg, EnumSet.of(JavaFileObject.Kind.CLASS), true)) {
191                    String name = fo.getName();
192                    // ignore resource files
193                    if (name.matches(".*resources.[A-Za-z_0-9]+\\.class.*"))
194                        continue;
195                    scan(fo, results);
196                }
197            }
198
199            // special handling for code strings synthesized in
200            // com.sun.tools.doclets.internal.toolkit.util.Util.getTypeName
201            String[] extras = {
202                "AnnotationType", "Class", "Enum", "Error", "Exception", "Interface"
203            };
204            for (String s: extras) {
205                if (results.contains("doclet." + s))
206                    results.add("doclet." + s.toLowerCase());
207            }
208
209            // special handling for code strings synthesized in
210            // com.sun.tools.javadoc.Messager
211            results.add("javadoc.error.msg");
212            results.add("javadoc.note.msg");
213            results.add("javadoc.note.pos.msg");
214            results.add("javadoc.warning.msg");
215
216            return results;
217        }
218    }
219
220    // depending on how the test is run, javadoc may be on bootclasspath or classpath
221    JavaFileManager.Location findJavadocLocation(JavaFileManager fm) {
222        JavaFileManager.Location[] locns =
223            { StandardLocation.PLATFORM_CLASS_PATH, StandardLocation.CLASS_PATH };
224        try {
225            for (JavaFileManager.Location l: locns) {
226                JavaFileObject fo = fm.getJavaFileForInput(l,
227                    "jdk.javadoc.internal.tool.Main", JavaFileObject.Kind.CLASS);
228                if (fo != null) {
229                    System.err.println("found javadoc in " + l);
230                    return l;
231                }
232            }
233        } catch (IOException e) {
234            throw new Error(e);
235        }
236        throw new IllegalStateException("Cannot find javadoc");
237    }
238
239    /**
240     * Get the set of strings from a class file.
241     * Only strings that look like they might be a resource key are returned.
242     */
243    void scan(JavaFileObject fo, Set<String> results) throws IOException {
244        //System.err.println("scan " + fo.getName());
245        InputStream in = fo.openInputStream();
246        try {
247            ClassFile cf = ClassFile.read(in);
248            for (ConstantPool.CPInfo cpinfo: cf.constant_pool.entries()) {
249                if (cpinfo.getTag() == ConstantPool.CONSTANT_Utf8) {
250                    String v = ((ConstantPool.CONSTANT_Utf8_info) cpinfo).value;
251                    if (v.matches("(doclet|main|javadoc|tag)\\.[A-Za-z0-9-_.]+"))
252                        results.add(v);
253                }
254            }
255        } catch (ConstantPoolException ignore) {
256        } finally {
257            in.close();
258        }
259    }
260
261    /**
262     * Get the set of keys from the javadoc resource bundles.
263     */
264    Set<String> getResourceKeys() {
265        Module jdk_javadoc = Layer.boot().findModule("jdk.javadoc").get();
266        String[] names = {
267                "jdk.javadoc.internal.doclets.formats.html.resources.standard",
268                "jdk.javadoc.internal.doclets.toolkit.resources.doclets",
269                "jdk.javadoc.internal.tool.resources.javadoc",
270        };
271        Set<String> results = new TreeSet<String>();
272        for (String name : names) {
273            ResourceBundle b = ResourceBundle.getBundle(name, jdk_javadoc);
274            results.addAll(b.keySet());
275        }
276        return results;
277    }
278
279    /**
280     * Report an error.
281     */
282    void error(String msg) {
283        System.err.println("Error: " + msg);
284        errors++;
285    }
286
287    int errors;
288}
289