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