duke@1: /* duke@1: * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as duke@1: * published by the Free Software Foundation. Sun designates this duke@1: * particular file as subject to the "Classpath" exception as provided duke@1: * by Sun in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * duke@1: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, duke@1: * CA 95054 USA or visit www.sun.com if you need additional information or duke@1: * have any questions. duke@1: */ duke@1: duke@1: package javax.tools; duke@1: duke@1: import java.util.Locale; duke@1: duke@1: /** duke@1: * Interface for diagnostics from tools. A diagnostic usually reports duke@1: * a problem at a specific position in a source file. However, not duke@1: * all diagnostics are associated with a position or a file. duke@1: * duke@1: *
A position is a zero-based character offset from the beginning of duke@1: * a file. Negative values (except {@link #NOPOS}) are not valid duke@1: * positions. duke@1: * duke@1: *
Line and column numbers begin at 1. Negative values (except
duke@1: * {@link #NOPOS}) and 0 are not valid line or column numbers.
duke@1: *
duke@1: * @param the type of source object used by this diagnostic
duke@1: *
duke@1: * @author Peter von der Ahé
duke@1: * @author Jonathan Gibbons
duke@1: * @since 1.6
duke@1: */
duke@1: public interface Diagnostic {
duke@1:
duke@1: /**
duke@1: * Kinds of diagnostics, for example, error or warning.
duke@1: */
duke@1: enum Kind {
duke@1: /**
duke@1: * Problem which prevents the tool's normal completion.
duke@1: */
duke@1: ERROR,
duke@1: /**
duke@1: * Problem which does not usually prevent the tool from
duke@1: * completing normally.
duke@1: */
duke@1: WARNING,
duke@1: /**
duke@1: * Problem similar to a warning, but is mandated by the tool's
duke@1: * specification. For example, the Java™ Language
duke@1: * Specification, 3rd Ed. mandates warnings on certain
duke@1: * unchecked operations and the use of deprecated methods.
duke@1: */
duke@1: MANDATORY_WARNING,
duke@1: /**
duke@1: * Informative message from the tool.
duke@1: */
duke@1: NOTE,
duke@1: /**
duke@1: * Diagnostic which does not fit within the other kinds.
duke@1: */
duke@1: OTHER,
duke@1: }
duke@1:
duke@1: /**
duke@1: * Used to signal that no position is available.
duke@1: */
duke@1: public final static long NOPOS = -1;
duke@1:
duke@1: /**
duke@1: * Gets the kind of this diagnostic, for example, error or
duke@1: * warning.
duke@1: * @return the kind of this diagnostic
duke@1: */
duke@1: Kind getKind();
duke@1:
duke@1: /**
duke@1: * Gets the source object associated with this diagnostic.
duke@1: *
duke@1: * @return the source object associated with this diagnostic.
duke@1: * {@code null} if no source object is associated with the
duke@1: * diagnostic.
duke@1: */
duke@1: S getSource();
duke@1:
duke@1: /**
duke@1: * Gets a character offset from the beginning of the source object
duke@1: * associated with this diagnostic that indicates the location of
duke@1: * the problem. In addition, the following must be true:
duke@1: *
duke@1: *
{@code getStartPostion() <= getPosition()} duke@1: *
{@code getPosition() <= getEndPosition()} duke@1: * duke@1: * @return character offset from beginning of source; {@link duke@1: * #NOPOS} if {@link #getSource()} would return {@code null} or if duke@1: * no location is suitable duke@1: */ duke@1: long getPosition(); duke@1: duke@1: /** duke@1: * Gets the character offset from the beginning of the file duke@1: * associated with this diagnostic that indicates the start of the duke@1: * problem. duke@1: * duke@1: * @return offset from beginning of file; {@link #NOPOS} if and duke@1: * only if {@link #getPosition()} returns {@link #NOPOS} duke@1: */ duke@1: long getStartPosition(); duke@1: duke@1: /** duke@1: * Gets the character offset from the beginning of the file duke@1: * associated with this diagnostic that indicates the end of the duke@1: * problem. duke@1: * duke@1: * @return offset from beginning of file; {@link #NOPOS} if and duke@1: * only if {@link #getPosition()} returns {@link #NOPOS} duke@1: */ duke@1: long getEndPosition(); duke@1: duke@1: /** duke@1: * Gets the line number of the character offset returned by duke@1: * {@linkplain #getPosition()}. duke@1: * duke@1: * @return a line number or {@link #NOPOS} if and only if {@link duke@1: * #getPosition()} returns {@link #NOPOS} duke@1: */ duke@1: long getLineNumber(); duke@1: duke@1: /** duke@1: * Gets the column number of the character offset returned by duke@1: * {@linkplain #getPosition()}. duke@1: * duke@1: * @return a column number or {@link #NOPOS} if and only if {@link duke@1: * #getPosition()} returns {@link #NOPOS} duke@1: */ duke@1: long getColumnNumber(); duke@1: duke@1: /** duke@1: * Gets a diagnostic code indicating the type of diagnostic. The duke@1: * code is implementation-dependent and might be {@code null}. duke@1: * duke@1: * @return a diagnostic code duke@1: */ duke@1: String getCode(); duke@1: duke@1: /** duke@1: * Gets a localized message for the given locale. The actual duke@1: * message is implementation-dependent. If the locale is {@code duke@1: * null} use the default locale. duke@1: * duke@1: * @param locale a locale; might be {@code null} duke@1: * @return a localized message duke@1: */ duke@1: String getMessage(Locale locale); duke@1: }