1 /*
   2  * Copyright (c) 2005, 2019, 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 javax.lang.model;
  27 
  28 import java.util.Collections;
  29 import java.util.Set;
  30 import java.util.HashSet;
  31 
  32 /**
  33  * Source versions of the Java™ programming language.
  34  *
  35  * See the appropriate edition of
  36  * <cite>The Java&trade; Language Specification</cite>
  37  * for information about a particular source version.
  38  *
  39  * <p>Note that additional source version constants will be added to
  40  * model future releases of the language.
  41  *
  42  * @author Joseph D. Darcy
  43  * @author Scott Seligman
  44  * @author Peter von der Ah&eacute;
  45  * @since 1.6
  46  */
  47 public enum SourceVersion {
  48     /*
  49      * Summary of language evolution
  50      * 1.1: nested classes
  51      * 1.2: strictfp
  52      * 1.3: no changes
  53      * 1.4: assert
  54      * 1.5: annotations, generics, autoboxing, var-args...
  55      * 1.6: no changes
  56      * 1.7: diamond syntax, try-with-resources, etc.
  57      * 1.8: lambda expressions and default methods
  58      *   9: modules, small cleanups to 1.7 and 1.8 changes
  59      *  10: local-variable type inference (var)
  60      *  11: local-variable syntax for lambda parameters
  61      *  12: no changes (switch expressions were in preview)
  62      *  13: no changes (switch expressions and text blocks in preview)
  63      *  14: TBD
  64      */
  65 
  66     // TOOD: The textual specs of isIdentifier, isName, and isKeyword
  67     // may or may not need to be explicitly updated for "record" and
  68     // "sealed" depending on how those tokens are formally handled in
  69     // the JLS. If they are treated as restricted keywords, a spec
  70     // update may not be strictly needed.
  71 
  72     /**
  73      * The original version.
  74      *
  75      * The language described in
  76      * <cite>The Java&trade; Language Specification, First Edition</cite>.
  77      */
  78     RELEASE_0,
  79 
  80     /**
  81      * The version recognized by the Java Platform 1.1.
  82      *
  83      * The language is {@code RELEASE_0} augmented with nested classes as described in the 1.1 update to
  84      * <cite>The Java&trade; Language Specification, First Edition</cite>.
  85      */
  86     RELEASE_1,
  87 
  88     /**
  89      * The version recognized by the Java 2 Platform, Standard Edition,
  90      * v 1.2.
  91      *
  92      * The language described in
  93      * <cite>The Java&trade; Language Specification,
  94      * Second Edition</cite>, which includes the {@code
  95      * strictfp} modifier.
  96      */
  97     RELEASE_2,
  98 
  99     /**
 100      * The version recognized by the Java 2 Platform, Standard Edition,
 101      * v 1.3.
 102      *
 103      * No major changes from {@code RELEASE_2}.
 104      */
 105     RELEASE_3,
 106 
 107     /**
 108      * The version recognized by the Java 2 Platform, Standard Edition,
 109      * v 1.4.
 110      *
 111      * Added a simple assertion facility.
 112      */
 113     RELEASE_4,
 114 
 115     /**
 116      * The version recognized by the Java 2 Platform, Standard
 117      * Edition 5.0.
 118      *
 119      * The language described in
 120      * <cite>The Java&trade; Language Specification,
 121      * Third Edition</cite>.  First release to support
 122      * generics, annotations, autoboxing, var-args, enhanced {@code
 123      * for} loop, and hexadecimal floating-point literals.
 124      */
 125     RELEASE_5,
 126 
 127     /**
 128      * The version recognized by the Java Platform, Standard Edition
 129      * 6.
 130      *
 131      * No major changes from {@code RELEASE_5}.
 132      */
 133     RELEASE_6,
 134 
 135     /**
 136      * The version recognized by the Java Platform, Standard Edition
 137      * 7.
 138      *
 139      * Additions in this release include, diamond syntax for
 140      * constructors, {@code try}-with-resources, strings in switch,
 141      * binary literals, and multi-catch.
 142      * @since 1.7
 143      */
 144     RELEASE_7,
 145 
 146     /**
 147      * The version recognized by the Java Platform, Standard Edition
 148      * 8.
 149      *
 150      * Additions in this release include lambda expressions and default methods.
 151      * @since 1.8
 152      */
 153     RELEASE_8,
 154 
 155     /**
 156      * The version recognized by the Java Platform, Standard Edition
 157      * 9.
 158      *
 159      * Additions in this release include modules and removal of a
 160      * single underscore from the set of legal identifier names.
 161      *
 162      * @since 9
 163      */
 164      RELEASE_9,
 165 
 166     /**
 167      * The version recognized by the Java Platform, Standard Edition
 168      * 10.
 169      *
 170      * Additions in this release include local-variable type inference
 171      * ({@code var}).
 172      *
 173      * @since 10
 174      */
 175      RELEASE_10,
 176 
 177     /**
 178      * The version recognized by the Java Platform, Standard Edition
 179      * 11.
 180      *
 181      * Additions in this release include local-variable syntax for
 182      * lambda parameters.
 183      *
 184      * @since 11
 185      */
 186      RELEASE_11,
 187 
 188     /**
 189      * The version recognized by the Java Platform, Standard Edition
 190      * 12.
 191      *
 192      * @since 12
 193      */
 194      RELEASE_12,
 195 
 196     /**
 197      * The version recognized by the Java Platform, Standard Edition
 198      * 13.
 199      *
 200      * @since 13
 201      */
 202      RELEASE_13,
 203 
 204     /**
 205      * The version recognized by the Java Platform, Standard Edition
 206      * 14.
 207      *
 208      * @since 14
 209      */
 210      RELEASE_14;
 211 
 212     // Note that when adding constants for newer releases, the
 213     // behavior of latest() and latestSupported() must be updated too.
 214 
 215     /**
 216      * Returns the latest source version that can be modeled.
 217      *
 218      * @return the latest source version that can be modeled
 219      */
 220     public static SourceVersion latest() {
 221         return RELEASE_14;
 222     }
 223 
 224     private static final SourceVersion latestSupported = getLatestSupported();
 225 
 226     /*
 227      * The integer version to enum constant mapping implemented by
 228      * this method assumes the JEP 322: "Time-Based Release
 229      * Versioning" scheme is in effect. This scheme began in JDK
 230      * 10. If the JDK versioning scheme is revised, this method may
 231      * need to be updated accordingly.
 232      */
 233     private static SourceVersion getLatestSupported() {
 234         int intVersion = Runtime.version().feature();
 235         return (intVersion >= 11) ?
 236             valueOf("RELEASE_" + Math.min(14, intVersion)):
 237             RELEASE_10;
 238     }
 239 
 240     /**
 241      * Returns the latest source version fully supported by the
 242      * current execution environment.  {@code RELEASE_9} or later must
 243      * be returned.
 244      *
 245      * @apiNote This method is included alongside {@link latest} to
 246      * allow identification of situations where the language model API
 247      * is running on a platform version different than the latest
 248      * version modeled by the API. One way that sort of situation can
 249      * occur is if an IDE or similar tool is using the API to model
 250      * source version <i>N</i> while running on platform version
 251      * (<i>N</i>&nbsp;-&nbsp;1). Running in this configuration is
 252      * supported by the API. Running an API on platform versions
 253      * earlier than (<i>N</i>&nbsp;-&nbsp;1) or later than <i>N</i>
 254      * may or may not work as an implementation detail. If an
 255      * annotation processor was generating code to run under the
 256      * current execution environment, the processor should only use
 257      * platform features up to the {@code latestSupported} release,
 258      * which may be earlier than the {@code latest} release.
 259      *
 260      * @return the latest source version that is fully supported
 261      */
 262     public static SourceVersion latestSupported() {
 263         return latestSupported;
 264     }
 265 
 266     /**
 267      * Returns whether or not {@code name} is a syntactically valid
 268      * identifier (simple name) or keyword in the latest source
 269      * version.  The method returns {@code true} if the name consists
 270      * of an initial character for which {@link
 271      * Character#isJavaIdentifierStart(int)} returns {@code true},
 272      * followed only by characters for which {@link
 273      * Character#isJavaIdentifierPart(int)} returns {@code true}.
 274      * This pattern matches regular identifiers, keywords, restricted
 275      * keywords, restricted identifiers and the literals {@code "true"},
 276      * {@code "false"}, {@code "null"}.
 277      *
 278      * The method returns {@code false} for all other strings.
 279      *
 280      * @param name the string to check
 281      * @return {@code true} if this string is a
 282      * syntactically valid identifier or keyword, {@code false}
 283      * otherwise.
 284      */
 285     public static boolean isIdentifier(CharSequence name) {
 286         String id = name.toString();
 287 
 288         if (id.length() == 0) {
 289             return false;
 290         }
 291         int cp = id.codePointAt(0);
 292         if (!Character.isJavaIdentifierStart(cp)) {
 293             return false;
 294         }
 295         for (int i = Character.charCount(cp);
 296                 i < id.length();
 297                 i += Character.charCount(cp)) {
 298             cp = id.codePointAt(i);
 299             if (!Character.isJavaIdentifierPart(cp)) {
 300                 return false;
 301             }
 302         }
 303         return true;
 304     }
 305 
 306     /**
 307      * Returns whether or not {@code name} is a syntactically valid
 308      * qualified name in the latest source version.  Unlike {@link
 309      * #isIdentifier isIdentifier}, this method returns {@code false}
 310      * for keywords, boolean literals, and the null literal.
 311      *
 312      * This method returns {@code true} for <i>restricted
 313      * keywords</i> and <i>restricted identifiers</i>
 314      *
 315      * @param name the string to check
 316      * @return {@code true} if this string is a
 317      * syntactically valid name, {@code false} otherwise.
 318      * @jls 3.9 Keywords
 319      * @jls 6.2 Names and Identifiers
 320      */
 321     public static boolean isName(CharSequence name) {
 322         return isName(name, latest());
 323     }
 324 
 325     /**
 326      * Returns whether or not {@code name} is a syntactically valid
 327      * qualified name in the given source version.  Unlike {@link
 328      * #isIdentifier isIdentifier}, this method returns {@code false}
 329      * for keywords, boolean literals, and the null literal.
 330      *
 331      * This method returns {@code true} for <i>restricted
 332      * keywords</i> and <i>restricted identifiers</i>
 333      *
 334      * @param name the string to check
 335      * @param version the version to use
 336      * @return {@code true} if this string is a
 337      * syntactically valid name, {@code false} otherwise.
 338      * @jls 3.9 Keywords
 339      * @jls 6.2 Names and Identifiers
 340      * @since 9
 341      */
 342     public static boolean isName(CharSequence name, SourceVersion version) {
 343         String id = name.toString();
 344 
 345         for(String s : id.split("\\.", -1)) {
 346             if (!isIdentifier(s) || isKeyword(s, version))
 347                 return false;
 348         }
 349         return true;
 350     }
 351 
 352     /**
 353      * Returns whether or not {@code s} is a keyword, boolean literal,
 354      * or null literal in the latest source version.
 355      * This method returns {@code false} for <i>restricted
 356      * keywords</i> and <i>restricted identifiers</i>.
 357      *
 358      * @param s the string to check
 359      * @return {@code true} if {@code s} is a keyword, or boolean
 360      * literal, or null literal, {@code false} otherwise.
 361      * @jls 3.9 Keywords
 362      * @jls 3.10.3 Boolean Literals
 363      * @jls 3.10.7 The Null Literal
 364      */
 365     public static boolean isKeyword(CharSequence s) {
 366         return isKeyword(s, latest());
 367     }
 368 
 369     /**
 370      * Returns whether or not {@code s} is a keyword, boolean literal,
 371      * or null literal in the given source version.
 372      * This method returns {@code false} for <i>restricted
 373      * keywords</i> and <i>restricted identifiers</i>.
 374      *
 375      * @param s the string to check
 376      * @param version the version to use
 377      * @return {@code true} if {@code s} is a keyword, or boolean
 378      * literal, or null literal, {@code false} otherwise.
 379      * @jls 3.9 Keywords
 380      * @jls 3.10.3 Boolean Literals
 381      * @jls 3.10.7 The Null Literal
 382      * @since 9
 383      */
 384     public static boolean isKeyword(CharSequence s, SourceVersion version) {
 385         String id = s.toString();
 386         switch(id) {
 387             // A trip through history
 388         case "strictfp":
 389             return version.compareTo(RELEASE_2) >= 0;
 390 
 391         case "assert":
 392             return version.compareTo(RELEASE_4) >= 0;
 393 
 394         case "enum":
 395             return version.compareTo(RELEASE_5) >= 0;
 396 
 397         case "_":
 398             return version.compareTo(RELEASE_9) >= 0;
 399 
 400             // Keywords common across versions
 401 
 402             // Modifiers
 403         case "public":    case "protected": case "private":
 404         case "abstract":  case "static":    case "final":
 405         case "transient": case "volatile":  case "synchronized":
 406         case "native":
 407 
 408             // Declarations
 409         case "class":     case "interface": case "extends":
 410         case "package":   case "throws":    case "implements":
 411 
 412             // Primitive types and void
 413         case "boolean":   case "byte":      case "char":
 414         case "short":     case "int":       case "long":
 415         case "float":     case "double":
 416         case "void":
 417 
 418             // Control flow
 419         case "if":      case "else":
 420         case "try":     case "catch":    case "finally":
 421         case "do":      case "while":
 422         case "for":     case "continue":
 423         case "switch":  case "case":     case "default":
 424         case "break":   case "throw":    case "return":
 425 
 426             // Other keywords
 427         case  "this":   case "new":      case "super":
 428         case "import":  case "instanceof":
 429 
 430             // Forbidden!
 431         case "goto":        case "const":
 432 
 433             // literals
 434         case "null":         case "true":       case "false":
 435             return true;
 436 
 437         default:
 438             return false;
 439         }
 440     }
 441 }