8300543: Compiler Implementation for Pattern Matching for switch

8300545: Compiler Implementation for Record Patterns

Co-authored-by: Aggelos Biboudis <abimpoudis@openjdk.org>
Reviewed-by: vromero, mcimadamore

src/java.base/share/classes/java/lang/MatchException.java

@@ -25,48 +25,57 @@
 
 package java.lang;
 
-import jdk.internal.javac.PreviewFeature;
-
 /**
  * Thrown to indicate an unexpected failure in pattern matching.
  *
- * <p>{@code MatchException} may be thrown when an exhaustive pattern matching language construct
- * (such as a switch expression) encounters a value that does not match any of the provided
- * patterns at runtime. This can arise from a number of cases:
+ * <p>{@code MatchException} may be thrown when an exhaustive pattern matching
+ * language construct (such as a {@code switch} expression) encounters a value
+ * that does not match any of the specified patterns at run time, even though
+ * the construct has been deemed exhaustive. This is intentional and can arise
+ * from a number of cases:
+ *
  * <ul>
- *    <li>Separate compilation anomalies, where a sealed interface has a different set of permitted
- *        subtypes at runtime than it had at compilation time, an enum has a different set of
- *        constants at runtime than it had at compilation time, or the type hierarchy has changed
- *        in incompatible ways between compile time and run time.</li>
- *    <li>{@code null} values and nested patterns using sealed types. If an interface or abstract
- *        class {@code C} is sealed to permit {@code A} and {@code B}, then the set of record
- *        patterns {@code R(A a)} and {@code R(B b)} are exhaustive on a record {@code R} whose
- *        sole component is of type {@code C}, but neither of these patterns will match
- *        {@code new R(null)}.</li>
- *    <li>Null targets and nested record patterns. Given a record type {@code R} whose sole
- *        component is {@code S}, which in turn is a record whose sole component is {@code String},
- *        then the nested record pattern {@code R(S(String s))} will not match {@code new R(null)}.</li>
+ *     <li>Separate compilation anomalies, where parts of the type hierarchy that
+ *         the patterns reference have been changed, but the pattern matching
+ *         construct has not been recompiled. For example, if a sealed interface
+ *         has a different set of permitted subtypes at run time than it had at
+ *         compile time, or if an enum class has a different set of enum constants
+ *         at runtime than it had at compile time, or if the type hierarchy has
+ *         been changed in some incompatible way between compile time and run time.</li>
+ *
+ *     <li>{@code null} values and nested patterns involving sealed classes. If,
+ *         for example, an interface {@code I} is {@code sealed} with two permitted
+ *         subclasses {@code A} and {@code B}, and a record class {@code R} has a
+ *         single component of type {@code I}, then the two record patterns {@code
+ *         R(A a)} and {@code R(B b)} together are considered to be exhaustive for
+ *         the type {@code R}, but neither of these patterns will match against the
+ *         result of {@code new R(null)}.</li>
+ *
+ *     <li>{@code null} values and nested record patterns. Given a record class
+ *         {@code S} with a single component of type {@code T}, where {@code T} is
+ *         another record class with a single component of type {@code String},
+ *         then the nested record pattern {@code R(S(var s))} is considered
+ *         exhaustive for the type {@code R} but it does not match against the
+ *         result of {@code new R(null)} (whereas it does match against the result
+ *         of {@code new R(new S(null))} does).</li>
  * </ul>
  *
- * <p>Match failures arising from unexpected inputs will generally throw {@code MatchException} only
- * after all patterns have been tried; even if {@code R(S(String s))} does not match
- * {@code new R(null)}, a later pattern (such as {@code R r}) may still match the target.
+ * <p>{@code MatchException} may also be thrown by the process of pattern matching
+ * a value against a pattern. For example, pattern matching involving a record
+ * pattern may require accessor methods to be implicitly invoked in order to
+ * extract the component values. If any of these accessor methods throws an
+ * exception, pattern matching completes abruptly and throws {@code
+ * MatchException}. The original exception will be set as a {@link
+ * Throwable#getCause() cause} of the {@code MatchException}. No {@link
+ * Throwable#addSuppressed(java.lang.Throwable) suppressed} exceptions will be
+ * recorded.
  *
- * <p>MatchException may also be thrown when operations performed as part of pattern matching throw
- * an unexpected exception. For example, pattern matching may cause methods such as record component
- * accessors to be implicitly invoked in order to extract pattern bindings. If these methods throw
- * an exception, execution of the pattern matching construct may fail with {@code MatchException}.
- * The original exception will be set as a {@link Throwable#getCause() cause} of
- * the {@code MatchException}. No {@link Throwable#addSuppressed(java.lang.Throwable) suppressed}
- * exceptions will be recorded.
- *
- * @jls 14.11.3 Execution of a switch Statement
+ * @jls 14.11.3 Execution of a {@code switch} Statement
  * @jls 14.30.2 Pattern Matching
- * @jls 15.28.2 Run-Time Evaluation of switch Expressions
+ * @jls 15.28.2 Run-Time Evaluation of {@code switch} Expressions
  *
- * @since 19
+ * @since 21
  */
-@PreviewFeature(feature=PreviewFeature.Feature.SWITCH_PATTERN_MATCHING)
 public final class MatchException extends RuntimeException {
     @java.io.Serial
     private static final long serialVersionUID = 0L;