View Javadoc
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   */
25  package com.sun.tools.javac.api;
26  
27  import java.util.Locale;
28  import java.util.Set;
29  import javax.tools.Diagnostic;
30  import 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   */
41  public 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 }