       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(since="11", forRemoval=true)
      64     enum Kind {
      65         /**
      66          * Problem which prevents the tool's normal completion.
      67          */
      68         ERROR,
      69         /**
      70          * Problem which does not usually prevent the tool from
      71          * completing normally.
      72          */
      73         WARNING,
      74         /**
      75          * Problem similar to a warning, but is mandated by the tool's
      76          * specification.  For example, the Java&trade; Language
      77          * Specification mandates warnings on certain
      78          * unchecked operations and the use of deprecated methods.
      79          */
      80         MANDATORY_WARNING,
      81         /**
      82          * Informative message from the tool.
      83          */
      84         NOTE,
      85         /**
      86          * Diagnostic which does not fit within the other kinds.
      87          */
      88         OTHER,
      89     }
      90
      91     /**
      92      * Used to signal that no position is available.
      93      */
      94     public final static long NOPOS = -1;
      95
      96     /**
      97      * Gets the kind of this diagnostic, for example, error or
      98      * warning.
      99      * @return the kind of this diagnostic
     100      */
     101     Kind getKind();
     102
     103     /**
     104      * Gets a character offset from the beginning of the source object
     105      * associated with this diagnostic that indicates the location of
     106      * the problem.  In addition, the following must be true:
     107      *
     108      * <p>{@code getStartPostion() <= getPosition()}
     109      * <p>{@code getPosition() <= getEndPosition()}
     110      *
     111      * @return character offset from beginning of source; {@link
     112      * #NOPOS} if no location is suitable
     113      */
     114     long getPosition();
     115
     116     /**
     117      * Gets the source file name.
     118      *
     119      * @return the file name or null if not available
     120      */
     121     String getFileName();
     122
     123     /**
     124      * Gets the line number of the character offset returned by
     125      * {@linkplain #getPosition()}.
     126      *
     127      * @return a line number or {@link #NOPOS} if and only if {@link
     128      * #getPosition()} returns {@link #NOPOS}
     129      */
     130     long getLineNumber();
     131
     132     /**
     133      * Gets the column number of the character offset returned by
     134      * {@linkplain #getPosition()}.
     135      *
     136      * @return a column number or {@link #NOPOS} if and only if {@link
     137      * #getPosition()} returns {@link #NOPOS}
     138      */
     139     long getColumnNumber();
     140
     141     /**
     142      * Gets a diagnostic code indicating the type of diagnostic.  The
     143      * code is implementation-dependent and might be {@code null}.
     144      *
     145      * @return a diagnostic code
     146      */
     147     String getCode();
     148
     149     /**
     150      * Gets a message for this diagnostic.
     151      *
     152      * @return a message
     153      */
     154     String getMessage();
     155 }
    --- EOF ---