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