DiagnosticFormatter.java revision 2571:10fc81ac75b4 
1/*
2 * Copyright (c) 2008, 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.  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 */
25package com.sun.tools.javac.api;
26
27import java.util.Locale;
28import java.util.Set;
29import javax.tools.Diagnostic;
30import com.sun.tools.javac.api.DiagnosticFormatter.*;
31
32/**
33 * Provides simple functionalities for javac diagnostic formatting.
34 * @param <D> type of diagnostic handled by this formatter
35 *
36 * <p><b>This is NOT part of any supported API.
37 * If you write code that depends on this, you do so at your own risk.
38 * This code and its internal interfaces are subject to change or
39 * deletion without notice.</b>
40 */
41public interface DiagnosticFormatter<D extends Diagnostic<?>> {
42
43    /**
44     * Whether the source code output for this diagnostic is to be displayed.
45     *
46     * @param diag diagnostic to be formatted
47     * @return true if the source line this diagnostic refers to is to be displayed
48     */
49    boolean displaySource(D diag);
50
51    /**
52     * Format the contents of a diagnostics.
53     *
54     * @param diag the diagnostic to be formatted
55     * @param l locale object to be used for i18n
56     * @return a string representing the diagnostic
57     */
58    public String format(D diag, Locale l);
59
60    /**
61     * Controls the way in which a diagnostic message is displayed.
62     *
63     * @param diag diagnostic to be formatted
64     * @param l locale object to be used for i18n
65     * @return string representation of the diagnostic message
66     */
67    public String formatMessage(D diag,Locale l);
68
69    /**
70     * Controls the way in which a diagnostic kind is displayed.
71     *
72     * @param diag diagnostic to be formatted
73     * @param l locale object to be used for i18n
74     * @return string representation of the diagnostic prefix
75     */
76    public String formatKind(D diag, Locale l);
77
78    /**
79     * Controls the way in which a diagnostic source is displayed.
80     *
81     * @param diag diagnostic to be formatted
82     * @param l locale object to be used for i18n
83     * @param fullname whether the source fullname should be printed
84     * @return string representation of the diagnostic source
85     */
86    public String formatSource(D diag, boolean fullname, Locale l);
87
88    /**
89     * Controls the way in which a diagnostic position is displayed.
90     *
91     * @param diag diagnostic to be formatted
92     * @param pk enum constant representing the position kind
93     * @param l locale object to be used for i18n
94     * @return string representation of the diagnostic position
95     */
96    public String formatPosition(D diag, PositionKind pk, Locale l);
97    //where
98    /**
99     * This enum defines a set of constants for all the kinds of position
100     * that a diagnostic can be asked for. All positions are intended to be
101     * relative to a given diagnostic source.
102     */
103    public enum PositionKind {
104        /**
105         * Start position
106         */
107        START,
108        /**
109         * End position
110         */
111        END,
112        /**
113         * Line number
114         */
115        LINE,
116        /**
117         * Column number
118         */
119        COLUMN,
120        /**
121         * Offset position
122         */
123        OFFSET
124    }
125
126    /**
127     * Get a list of all the enabled verbosity options.
128     * @return verbosity options
129     */
130    public Configuration getConfiguration();
131    //where
132
133    /**
134     * This interface provides functionalities for tuning the output of a
135     * diagnostic formatter in multiple ways.
136     */
137    interface Configuration {
138        /**
139         * Configure the set of diagnostic parts that should be displayed
140         * by the formatter.
141         * @param visibleParts the parts to be set
142         */
143        public void setVisible(Set<DiagnosticPart> visibleParts);
144
145        /**
146         * Retrieve the set of diagnostic parts that should be displayed
147         * by the formatter.
148         * @return verbosity options
149         */
150        public Set<DiagnosticPart> getVisible();
151
152        //where
153        /**
154         * A given diagnostic message can be divided into sub-parts each of which
155         * might/might not be displayed by the formatter, according to the
156         * current configuration settings.
157         */
158        public enum DiagnosticPart {
159            /**
160             * Short description of the diagnostic - usually one line long.
161             */
162            SUMMARY,
163            /**
164             * Longer description that provides additional details w.r.t. the ones
165             * in the diagnostic's description.
166             */
167            DETAILS,
168            /**
169             * Source line the diagnostic refers to (if applicable).
170             */
171            SOURCE,
172            /**
173             * Subdiagnostics attached to a given multiline diagnostic.
174             */
175            SUBDIAGNOSTICS,
176            /**
177             * JLS paragraph this diagnostic might refer to (if applicable).
178             */
179            JLS
180        }
181
182        /**
183         * Set a limit for multiline diagnostics.
184         * Note: Setting a limit has no effect if multiline diagnostics are either
185         * fully enabled or disabled.
186         *
187         * @param limit the kind of limit to be set
188         * @param value the limit value
189         */
190        public void setMultilineLimit(MultilineLimit limit, int value);
191
192        /**
193         * Get a multiline diagnostic limit.
194         *
195         * @param limit the kind of limit to be retrieved
196         * @return limit value or -1 if no limit is set
197         */
198        public int getMultilineLimit(MultilineLimit limit);
199        //where
200        /**
201         * A multiline limit control the verbosity of multiline diagnostics
202         * either by setting a maximum depth of nested multidiagnostics,
203         * or by limiting the amount of subdiagnostics attached to a given
204         * diagnostic (or both).
205         */
206        public enum MultilineLimit {
207            /**
208             * Controls the maximum depth of nested multiline diagnostics.
209             */
210            DEPTH,
211            /**
212             * Controls the maximum amount of subdiagnostics that are part of a
213             * given multiline diagnostic.
214             */
215            LENGTH
216        }
217    }
218}
219