Diagnostic


1   /*
2    * @(#)Diagnostic.java  1.5 06/09/25
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.tools;
9   
10  import java.util.Locale  ;
11  
12  /**
13   * Interface for diagnostics from tools.  A diagnostic usually reports
14   * a problem at a specific position in a source file.  However, not
15   * all diagnostics are associated with a position or a file.
16   *
17   * <p>A position is a zero-based character offset from the beginning of
18   * a file.  Negative values (except {@link #NOPOS}) are not valid
19   * positions.
20   *
21   * <p>Line and column numbers begin at 1.  Negative values (except
22   * {@link #NOPOS}) and 0 are not valid line or column numbers.
23   *
24   * @param <S> the type of source object used by this diagnostic
25   *
26   * @author Peter von der Ah&eacute;
27   * @author Jonathan Gibbons
28   * @since 1.6
29   */
30  public interface Diagnostic<S> {
31  
32      /**
33       * Kinds of diagnostics, for example, error or warning.
34       */
35      enum Kind {
36          /**
37           * Problem which prevents the tool's normal completion.
38           */
39          ERROR,
40          /**
41           * Problem which does not usually prevent the tool from
42           * completing normally.
43           */
44          WARNING,
45          /**
46           * Problem similar to a warning, but is mandated by the tool's
47           * specification.  For example, the Java&trade; Language
48           * Specification, 3rd Ed. mandates warnings on certain
49           * unchecked operations and the use of deprecated methods.
50           */
51          MANDATORY_WARNING,
52          /**
53           * Informative message from the tool.
54           */
55          NOTE,
56          /**
57           * Diagnostic which does not fit within the other kinds.
58           */
59          OTHER,
60      }
61  
62      /**
63       * Used to signal that no position is available.
64       */
65      public final static long NOPOS = -1;
66  
67      /**
68       * Gets the kind of this diagnostic, for example, error or
69       * warning.
70       * @return the kind of this diagnostic
71       */
72      Kind getKind();
73  
74      /**
75       * Gets the source object associated with this diagnostic.
76       *
77       * @return the source object associated with this diagnostic.
78       * {@code null} if no source object is associated with the
79       * diagnostic.
80       */
81      S getSource();
82  
83      /**
84       * Gets a character offset from the beginning of the source object
85       * associated with this diagnostic that indicates the location of
86       * the problem.  In addition, the following must be true:
87       *
88       * <p>{@code getStartPostion() <= getPosition()}
89       * <p>{@code getPosition() <= getEndPosition()}
90       *
91       * @return character offset from beginning of source; {@link
92       * #NOPOS} if {@link #getSource()} would return {@code null} or if
93       * no location is suitable
94       */
95      long getPosition();
96  
97      /**
98       * Gets the character offset from the beginning of the file
99       * associated with this diagnostic that indicates the start of the
100      * problem.
101      *
102      * @return offset from beginning of file; {@link #NOPOS} if and
103      * only if {@link #getPosition()} returns {@link #NOPOS}
104      */
105     long getStartPosition();
106 
107     /**
108      * Gets the character offset from the beginning of the file
109      * associated with this diagnostic that indicates the end of the
110      * problem.
111      *
112      * @return offset from beginning of file; {@link #NOPOS} if and
113      * only if {@link #getPosition()} returns {@link #NOPOS}
114      */
115     long getEndPosition();
116 
117     /**
118      * Gets the line number of the character offset returned by
119      * {@linkplain #getPosition()}.
120      *
121      * @return a line number or {@link #NOPOS} if and only if {@link
122      * #getPosition()} returns {@link #NOPOS}
123      */
124     long getLineNumber();
125 
126     /**
127      * Gets the column number of the character offset returned by
128      * {@linkplain #getPosition()}.
129      *
130      * @return a column number or {@link #NOPOS} if and only if {@link
131      * #getPosition()} returns {@link #NOPOS}
132      */
133     long getColumnNumber();
134 
135     /**
136      * Gets a diagnostic code indicating the type of diagnostic.  The
137      * code is implementation-dependent and might be {@code null}.
138      *
139      * @return a diagnostic code
140      */
141     String   getCode();
142 
143     /**
144      * Gets a localized message for the given locale.  The actual
145      * message is implementation-dependent.  If the locale is {@code
146      * null} use the default locale.
147      *
148      * @param locale a locale; might be {@code null}
149      * @return a localized message
150      */
151     String   getMessage(Locale   locale);
152 }
153
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags