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  * @since 9
  44  */
  45 @jdk.Exported
  46 public interface Diagnostic {
  47 
  48     /**
  49      * Kinds of diagnostics, for example, error or warning.
  50      *
  51      * The kind of a diagnostic can be used to determine how the
  52      * diagnostic should be presented to the user. For example,
  53      * errors might be colored red or prefixed with the word "Error",
  54      * while warnings might be colored yellow or prefixed with the
  55      * word "Warning". There is no requirement that the Kind
  56      * should imply any inherent semantic meaning to the message
  57      * of the diagnostic: for example, a tool might provide an
  58      * option to report all warnings as errors.
  59      */
  60     enum Kind {
  61         /**
  62          * Problem which prevents the tool's normal completion.
  63          */
  64         ERROR,
  65         /**
  66          * Problem which does not usually prevent the tool from
  67          * completing normally.
  68          */
  69         WARNING,
  70         /**
  71          * Problem similar to a warning, but is mandated by the tool's
  72          * specification.  For example, the Java&trade; Language
  73          * Specification mandates warnings on certain
  74          * unchecked operations and the use of deprecated methods.
  75          */
  76         MANDATORY_WARNING,
  77         /**
  78          * Informative message from the tool.
  79          */
  80         NOTE,
  81         /**
  82          * Diagnostic which does not fit within the other kinds.
  83          */
  84         OTHER,
  85     }
  86 
  87     /**
  88      * Used to signal that no position is available.
  89      */
  90     public final static long NOPOS = -1;
  91 
  92     /**
  93      * Gets the kind of this diagnostic, for example, error or
  94      * warning.
  95      * @return the kind of this diagnostic
  96      */
  97     Kind getKind();
  98 
  99     /**
 100      * Gets a character offset from the beginning of the source object
 101      * associated with this diagnostic that indicates the location of
 102      * the problem.  In addition, the following must be true:
 103      *
 104      * <p>{@code getStartPostion() <= getPosition()}
 105      * <p>{@code getPosition() <= getEndPosition()}
 106      *
 107      * @return character offset from beginning of source; {@link
 108      * #NOPOS} if no location is suitable
 109      */
 110     long getPosition();
 111 
 112     /**
 113      * Gets the source file name.
 114      *
 115      * @return the file name or null if not available
 116      */
 117     String getFileName();
 118 
 119     /**
 120      * Gets the line number of the character offset returned by
 121      * {@linkplain #getPosition()}.
 122      *
 123      * @return a line number or {@link #NOPOS} if and only if {@link
 124      * #getPosition()} returns {@link #NOPOS}
 125      */
 126     long getLineNumber();
 127 
 128     /**
 129      * Gets the column number of the character offset returned by
 130      * {@linkplain #getPosition()}.
 131      *
 132      * @return a column number or {@link #NOPOS} if and only if {@link
 133      * #getPosition()} returns {@link #NOPOS}
 134      */
 135     long getColumnNumber();
 136 
 137     /**
 138      * Gets a diagnostic code indicating the type of diagnostic.  The
 139      * code is implementation-dependent and might be {@code null}.
 140      *
 141      * @return a diagnostic code
 142      */
 143     String getCode();
 144 
 145     /**
 146      * Gets a message for this diagnostic.
 147      *
 148      * @return a message
 149      */
 150     String getMessage();
 151 }
--- EOF ---