1/* 2 * Copyright (c) 2012, 2013, 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 26package com.sun.tools.doclint; 27 28import java.io.PrintWriter; 29import java.text.MessageFormat; 30import java.util.Comparator; 31import java.util.HashMap; 32import java.util.Locale; 33import java.util.Map; 34import java.util.MissingResourceException; 35import java.util.ResourceBundle; 36import java.util.Set; 37import java.util.TreeMap; 38import java.util.TreeSet; 39 40import javax.tools.Diagnostic; 41 42import com.sun.source.doctree.DocTree; 43import com.sun.source.tree.Tree; 44import com.sun.tools.doclint.Env.AccessKind; 45import com.sun.tools.javac.util.StringUtils; 46 47/** 48 * Message reporting for DocLint. 49 * 50 * Options are used to filter out messages based on group and access level. 51 * Support can be enabled for accumulating statistics of different kinds of 52 * messages. 53 * 54 * <p><b>This is NOT part of any supported API. 55 * If you write code that depends on this, you do so at your own 56 * risk. This code and its internal interfaces are subject to change 57 * or deletion without notice.</b></p> 58 */ 59public class Messages { 60 /** 61 * Groups used to categorize messages, so that messages in each group 62 * can be enabled or disabled via options. 63 */ 64 public enum Group { 65 ACCESSIBILITY, 66 HTML, 67 MISSING, 68 SYNTAX, 69 REFERENCE; 70 71 String optName() { return StringUtils.toLowerCase(name()); } 72 String notOptName() { return "-" + optName(); } 73 74 static boolean accepts(String opt) { 75 for (Group g: values()) 76 if (opt.equals(g.optName())) return true; 77 return false; 78 } 79 } 80 81 private final Options options; 82 private final Stats stats; 83 84 ResourceBundle bundle; 85 Env env; 86 87 Messages(Env env) { 88 this.env = env; 89 String name = getClass().getPackage().getName() + ".resources.doclint"; 90 bundle = ResourceBundle.getBundle(name, Locale.ENGLISH); 91 92 stats = new Stats(bundle); 93 options = new Options(stats); 94 } 95 96 void error(Group group, DocTree tree, String code, Object... args) { 97 report(group, Diagnostic.Kind.ERROR, tree, code, args); 98 } 99 100 void warning(Group group, DocTree tree, String code, Object... args) { 101 report(group, Diagnostic.Kind.WARNING, tree, code, args); 102 } 103 104 void setOptions(String opts) { 105 options.setOptions(opts); 106 } 107 108 void setStatsEnabled(boolean b) { 109 stats.setEnabled(b); 110 } 111 112 void reportStats(PrintWriter out) { 113 stats.report(out); 114 } 115 116 protected void report(Group group, Diagnostic.Kind dkind, DocTree tree, String code, Object... args) { 117 if (options.isEnabled(group, env.currAccess)) { 118 String msg = (code == null) ? (String) args[0] : localize(code, args); 119 env.trees.printMessage(dkind, msg, tree, 120 env.currDocComment, env.currPath.getCompilationUnit()); 121 122 stats.record(group, dkind, code); 123 } 124 } 125 126 protected void report(Group group, Diagnostic.Kind dkind, Tree tree, String code, Object... args) { 127 if (options.isEnabled(group, env.currAccess)) { 128 String msg = localize(code, args); 129 env.trees.printMessage(dkind, msg, tree, env.currPath.getCompilationUnit()); 130 131 stats.record(group, dkind, code); 132 } 133 } 134 135 String localize(String code, Object... args) { 136 String msg = bundle.getString(code); 137 if (msg == null) { 138 StringBuilder sb = new StringBuilder(); 139 sb.append("message file broken: code=").append(code); 140 if (args.length > 0) { 141 sb.append(" arguments={0}"); 142 for (int i = 1; i < args.length; i++) { 143 sb.append(", {").append(i).append("}"); 144 } 145 } 146 msg = sb.toString(); 147 } 148 return MessageFormat.format(msg, args); 149 } 150 151 // <editor-fold defaultstate="collapsed" desc="Options"> 152 153 /** 154 * Handler for (sub)options specific to message handling. 155 */ 156 static class Options { 157 Map<String, Env.AccessKind> map = new HashMap<>(); 158 private final Stats stats; 159 160 static boolean isValidOptions(String opts) { 161 for (String opt: opts.split(",")) { 162 if (!isValidOption(StringUtils.toLowerCase(opt.trim()))) 163 return false; 164 } 165 return true; 166 } 167 168 private static boolean isValidOption(String opt) { 169 if (opt.equals("none") || opt.equals(Stats.OPT)) 170 return true; 171 172 int begin = opt.startsWith("-") ? 1 : 0; 173 int sep = opt.indexOf("/"); 174 String grp = opt.substring(begin, (sep != -1) ? sep : opt.length()); 175 return ((begin == 0 && grp.equals("all")) || Group.accepts(grp)) 176 && ((sep == -1) || AccessKind.accepts(opt.substring(sep + 1))); 177 } 178 179 Options(Stats stats) { 180 this.stats = stats; 181 } 182 183 /** Determine if a message group is enabled for a particular access level. */ 184 boolean isEnabled(Group g, Env.AccessKind access) { 185 if (map.isEmpty()) 186 map.put("all", Env.AccessKind.PROTECTED); 187 188 Env.AccessKind ak = map.get(g.optName()); 189 if (ak != null && access.compareTo(ak) >= 0) 190 return true; 191 192 ak = map.get(ALL); 193 if (ak != null && access.compareTo(ak) >= 0) { 194 ak = map.get(g.notOptName()); 195 if (ak == null || access.compareTo(ak) > 0) // note >, not >= 196 return true; 197 } 198 199 return false; 200 } 201 202 void setOptions(String opts) { 203 if (opts == null) 204 setOption(ALL, Env.AccessKind.PRIVATE); 205 else { 206 for (String opt: opts.split(",")) 207 setOption(StringUtils.toLowerCase(opt.trim())); 208 } 209 } 210 211 private void setOption(String arg) throws IllegalArgumentException { 212 if (arg.equals(Stats.OPT)) { 213 stats.setEnabled(true); 214 return; 215 } 216 217 int sep = arg.indexOf("/"); 218 if (sep > 0) { 219 Env.AccessKind ak = Env.AccessKind.valueOf(StringUtils.toUpperCase(arg.substring(sep + 1))); 220 setOption(arg.substring(0, sep), ak); 221 } else { 222 setOption(arg, null); 223 } 224 } 225 226 private void setOption(String opt, Env.AccessKind ak) { 227 map.put(opt, (ak != null) ? ak 228 : opt.startsWith("-") ? Env.AccessKind.PUBLIC : Env.AccessKind.PRIVATE); 229 } 230 231 private static final String ALL = "all"; 232 } 233 234 // </editor-fold> 235 236 // <editor-fold defaultstate="collapsed" desc="Statistics"> 237 238 /** 239 * Optionally record statistics of different kinds of message. 240 */ 241 static class Stats { 242 public static final String OPT = "stats"; 243 public static final String NO_CODE = ""; 244 final ResourceBundle bundle; 245 246 // tables only initialized if enabled 247 int[] groupCounts; 248 int[] dkindCounts; 249 Map<String, Integer> codeCounts; 250 251 Stats(ResourceBundle bundle) { 252 this.bundle = bundle; 253 } 254 255 void setEnabled(boolean b) { 256 if (b) { 257 groupCounts = new int[Messages.Group.values().length]; 258 dkindCounts = new int[Diagnostic.Kind.values().length]; 259 codeCounts = new HashMap<>(); 260 } else { 261 groupCounts = null; 262 dkindCounts = null; 263 codeCounts = null; 264 } 265 } 266 267 void record(Messages.Group g, Diagnostic.Kind dkind, String code) { 268 if (codeCounts == null) { 269 return; 270 } 271 groupCounts[g.ordinal()]++; 272 dkindCounts[dkind.ordinal()]++; 273 if (code == null) { 274 code = NO_CODE; 275 } 276 Integer i = codeCounts.get(code); 277 codeCounts.put(code, (i == null) ? 1 : i + 1); 278 } 279 280 void report(PrintWriter out) { 281 if (codeCounts == null) { 282 return; 283 } 284 out.println("By group..."); 285 Table groupTable = new Table(); 286 for (Messages.Group g : Messages.Group.values()) { 287 groupTable.put(g.optName(), groupCounts[g.ordinal()]); 288 } 289 groupTable.print(out); 290 out.println(); 291 out.println("By diagnostic kind..."); 292 Table dkindTable = new Table(); 293 for (Diagnostic.Kind k : Diagnostic.Kind.values()) { 294 dkindTable.put(StringUtils.toLowerCase(k.toString()), dkindCounts[k.ordinal()]); 295 } 296 dkindTable.print(out); 297 out.println(); 298 out.println("By message kind..."); 299 Table codeTable = new Table(); 300 for (Map.Entry<String, Integer> e : codeCounts.entrySet()) { 301 String code = e.getKey(); 302 String msg; 303 try { 304 msg = code.equals(NO_CODE) ? "OTHER" : bundle.getString(code); 305 } catch (MissingResourceException ex) { 306 msg = code; 307 } 308 codeTable.put(msg, e.getValue()); 309 } 310 codeTable.print(out); 311 } 312 313 /** 314 * A table of (int, String) sorted by decreasing int. 315 */ 316 private static class Table { 317 318 private static final Comparator<Integer> DECREASING = (o1, o2) -> o2.compareTo(o1); 319 private final TreeMap<Integer, Set<String>> map = new TreeMap<>(DECREASING); 320 321 void put(String label, int n) { 322 if (n == 0) { 323 return; 324 } 325 Set<String> labels = map.get(n); 326 if (labels == null) { 327 map.put(n, labels = new TreeSet<>()); 328 } 329 labels.add(label); 330 } 331 332 void print(PrintWriter out) { 333 for (Map.Entry<Integer, Set<String>> e : map.entrySet()) { 334 int count = e.getKey(); 335 Set<String> labels = e.getValue(); 336 for (String label : labels) { 337 out.println(String.format("%6d: %s", count, label)); 338 } 339 } 340 } 341 } 342 } 343 // </editor-fold> 344} 345