001: /*
002: * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package javax.tools;
027:
028: import java.util.Locale;
029:
030: /**
031: * Interface for diagnostics from tools. A diagnostic usually reports
032: * a problem at a specific position in a source file. However, not
033: * all diagnostics are associated with a position or a file.
034: *
035: * <p>A position is a zero-based character offset from the beginning of
036: * a file. Negative values (except {@link #NOPOS}) are not valid
037: * positions.
038: *
039: * <p>Line and column numbers begin at 1. Negative values (except
040: * {@link #NOPOS}) and 0 are not valid line or column numbers.
041: *
042: * @param <S> the type of source object used by this diagnostic
043: *
044: * @author Peter von der Ahé
045: * @author Jonathan Gibbons
046: * @since 1.6
047: */
048: public interface Diagnostic<S> {
049:
050: /**
051: * Kinds of diagnostics, for example, error or warning.
052: */
053: enum Kind {
054: /**
055: * Problem which prevents the tool's normal completion.
056: */
057: ERROR,
058: /**
059: * Problem which does not usually prevent the tool from
060: * completing normally.
061: */
062: WARNING,
063: /**
064: * Problem similar to a warning, but is mandated by the tool's
065: * specification. For example, the Java™ Language
066: * Specification, 3rd Ed. mandates warnings on certain
067: * unchecked operations and the use of deprecated methods.
068: */
069: MANDATORY_WARNING,
070: /**
071: * Informative message from the tool.
072: */
073: NOTE,
074: /**
075: * Diagnostic which does not fit within the other kinds.
076: */
077: OTHER,
078: }
079:
080: /**
081: * Used to signal that no position is available.
082: */
083: public final static long NOPOS = -1;
084:
085: /**
086: * Gets the kind of this diagnostic, for example, error or
087: * warning.
088: * @return the kind of this diagnostic
089: */
090: Kind getKind();
091:
092: /**
093: * Gets the source object associated with this diagnostic.
094: *
095: * @return the source object associated with this diagnostic.
096: * {@code null} if no source object is associated with the
097: * diagnostic.
098: */
099: S getSource();
100:
101: /**
102: * Gets a character offset from the beginning of the source object
103: * associated with this diagnostic that indicates the location of
104: * the problem. In addition, the following must be true:
105: *
106: * <p>{@code getStartPostion() <= getPosition()}
107: * <p>{@code getPosition() <= getEndPosition()}
108: *
109: * @return character offset from beginning of source; {@link
110: * #NOPOS} if {@link #getSource()} would return {@code null} or if
111: * no location is suitable
112: */
113: long getPosition();
114:
115: /**
116: * Gets the character offset from the beginning of the file
117: * associated with this diagnostic that indicates the start of the
118: * problem.
119: *
120: * @return offset from beginning of file; {@link #NOPOS} if and
121: * only if {@link #getPosition()} returns {@link #NOPOS}
122: */
123: long getStartPosition();
124:
125: /**
126: * Gets the character offset from the beginning of the file
127: * associated with this diagnostic that indicates the end of the
128: * problem.
129: *
130: * @return offset from beginning of file; {@link #NOPOS} if and
131: * only if {@link #getPosition()} returns {@link #NOPOS}
132: */
133: long getEndPosition();
134:
135: /**
136: * Gets the line number of the character offset returned by
137: * {@linkplain #getPosition()}.
138: *
139: * @return a line number or {@link #NOPOS} if and only if {@link
140: * #getPosition()} returns {@link #NOPOS}
141: */
142: long getLineNumber();
143:
144: /**
145: * Gets the column number of the character offset returned by
146: * {@linkplain #getPosition()}.
147: *
148: * @return a column number or {@link #NOPOS} if and only if {@link
149: * #getPosition()} returns {@link #NOPOS}
150: */
151: long getColumnNumber();
152:
153: /**
154: * Gets a diagnostic code indicating the type of diagnostic. The
155: * code is implementation-dependent and might be {@code null}.
156: *
157: * @return a diagnostic code
158: */
159: String getCode();
160:
161: /**
162: * Gets a localized message for the given locale. The actual
163: * message is implementation-dependent. If the locale is {@code
164: * null} use the default locale.
165: *
166: * @param locale a locale; might be {@code null}
167: * @return a localized message
168: */
169: String getMessage(Locale locale);
170: }
|