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