1 /*
2 * Copyright (c) 2015, 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
26 package jdk.nashorn.api.tree;
27
28 /**
29 * Interface for diagnostics from tools. A diagnostic usually reports
30 * a problem at a specific position in a source file. However, not
31 * all diagnostics are associated with a position or a file.
32 *
33 * <p>A position is a zero-based character offset from the beginning of
34 * a file. Negative values (except {@link #NOPOS}) are not valid
35 * positions.
36 *
37 * <p>Line and column numbers begin at 1. Negative values (except
38 * {@link #NOPOS}) and 0 are not valid line or column numbers.
39 *
40 * <p>Line terminator is as defined in ECMAScript specification which is one
41 * of { \u000A, \u000B, \u2028, \u2029 }.
42 *
43 * @deprecated Nashorn JavaScript script engine and APIs, and the jjs tool
44 * are deprecated with the intent to remove them in a future release.
45 *
46 * @since 9
47 */
48 @Deprecated(since="11", forRemoval=true)
49 public interface Diagnostic {
50
51 /**
52 * Kinds of diagnostics, for example, error or warning.
53 *
54 * The kind of a diagnostic can be used to determine how the
55 * diagnostic should be presented to the user. For example,
56 * errors might be colored red or prefixed with the word "Error",
57 * while warnings might be colored yellow or prefixed with the
58 * word "Warning". There is no requirement that the Kind
59 * should imply any inherent semantic meaning to the message
60 * of the diagnostic: for example, a tool might provide an
61 * option to report all warnings as errors.
62 *
63 * @deprecated Nashorn JavaScript script engine and APIs, and the jjs tool
64 * are deprecated with the intent to remove them in a future release.
65 */
66 @Deprecated(since="11", forRemoval=true)
67 enum Kind {
68 /**
69 * Problem which prevents the tool's normal completion.
70 */
71 ERROR,
72 /**
73 * Problem which does not usually prevent the tool from
74 * completing normally.
75 */
76 WARNING,
77 /**
78 * Problem similar to a warning, but is mandated by the tool's
79 * specification. For example, the Java™ Language
80 * Specification mandates warnings on certain
81 * unchecked operations and the use of deprecated methods.
82 */
83 MANDATORY_WARNING,
84 /**
85 * Informative message from the tool.
86 */
87 NOTE,
88 /**
89 * Diagnostic which does not fit within the other kinds.
90 */
91 OTHER,
92 }
93
94 /**
95 * Used to signal that no position is available.
96 */
97 public final static long NOPOS = -1;
98
99 /**
100 * Gets the kind of this diagnostic, for example, error or
101 * warning.
102 * @return the kind of this diagnostic
103 */
104 Kind getKind();
105
106 /**
107 * Gets a character offset from the beginning of the source object
108 * associated with this diagnostic that indicates the location of
109 * the problem. In addition, the following must be true:
110 *
111 * <p>{@code getStartPostion() <= getPosition()}
112 * <p>{@code getPosition() <= getEndPosition()}
113 *
114 * @return character offset from beginning of source; {@link
115 * #NOPOS} if no location is suitable
116 */
117 long getPosition();
118
119 /**
120 * Gets the source file name.
121 *
122 * @return the file name or null if not available
123 */
124 String getFileName();
125
126 /**
127 * Gets the line number of the character offset returned by
128 * {@linkplain #getPosition()}.
129 *
130 * @return a line number or {@link #NOPOS} if and only if {@link
131 * #getPosition()} returns {@link #NOPOS}
132 */
133 long getLineNumber();
134
135 /**
136 * Gets the column number of the character offset returned by
137 * {@linkplain #getPosition()}.
138 *
139 * @return a column number or {@link #NOPOS} if and only if {@link
140 * #getPosition()} returns {@link #NOPOS}
141 */
142 long getColumnNumber();
143
144 /**
145 * Gets a diagnostic code indicating the type of diagnostic. The
146 * code is implementation-dependent and might be {@code null}.
147 *
148 * @return a diagnostic code
149 */
150 String getCode();
151
152 /**
153 * Gets a message for this diagnostic.
154 *
155 * @return a message
156 */
157 String getMessage();
158 }