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