1 /* 2 * Copyright (c) 2022, 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 java.lang; 27 28 /** 29 * Thrown to indicate an unexpected failure in pattern matching. 30 * 31 * <p>{@code MatchException} may be thrown when an exhaustive pattern matching 32 * language construct (such as a {@code switch} expression) encounters a value 33 * that does not match any of the specified patterns at run time, even though 34 * the construct has been deemed exhaustive. This is intentional and can arise 35 * from a number of cases: 36 * 37 * <ul> 38 * <li>Separate compilation anomalies, where parts of the type hierarchy that 39 * the patterns reference have been changed, but the pattern matching 40 * construct has not been recompiled. For example, if a sealed interface 41 * has a different set of permitted subtypes at run time than it had at 42 * compile time, or if an enum class has a different set of enum constants 43 * at runtime than it had at compile time, or if the type hierarchy has 44 * been changed in some incompatible way between compile time and run time.</li> 45 * 46 * <li>{@code null} values and nested patterns involving sealed classes. If, 47 * for example, an interface {@code I} is {@code sealed} with two permitted 48 * subclasses {@code A} and {@code B}, and a record class {@code R} has a 49 * single component of type {@code I}, then the two record patterns {@code 50 * R(A a)} and {@code R(B b)} together are considered to be exhaustive for 51 * the type {@code R}, but neither of these patterns will match against the 52 * result of {@code new R(null)}.</li> 53 * 54 * <li>{@code null} values and nested record patterns. Given a record class 55 * {@code S} with a single component of type {@code T}, where {@code T} is 56 * another record class with a single component of type {@code String}, 57 * then the nested record pattern {@code R(S(var s))} is considered 58 * exhaustive for the type {@code R} but it does not match against the 59 * result of {@code new R(null)} (whereas it does match against the result 60 * of {@code new R(new S(null))} does).</li> 61 * </ul> 62 * 63 * <p>{@code MatchException} may also be thrown by the process of pattern matching 64 * a value against a pattern. For example, pattern matching involving a record 65 * pattern may require accessor methods to be implicitly invoked in order to 66 * extract the component values. If any of these accessor methods throws an 67 * exception, pattern matching completes abruptly and throws {@code 68 * MatchException}. The original exception will be set as a {@link 69 * Throwable#getCause() cause} of the {@code MatchException}. No {@link 70 * Throwable#addSuppressed(java.lang.Throwable) suppressed} exceptions will be 71 * recorded. 72 * 73 * @jls 14.11.3 Execution of a {@code switch} Statement 74 * @jls 14.30.2 Pattern Matching 75 * @jls 15.28.2 Run-Time Evaluation of {@code switch} Expressions 76 * 77 * @since 21 78 */ 79 public final class MatchException extends RuntimeException { 80 @java.io.Serial 81 private static final long serialVersionUID = 0L; 82 83 /** 84 * Constructs an {@code MatchException} with the specified detail message and 85 * cause. 86 * 87 * @param message the detail message (which is saved for later retrieval 88 * by the {@link #getMessage()} method). 89 * @param cause the cause (which is saved for later retrieval by the 90 * {@link #getCause()} method). (A {@code null} value is 91 * permitted, and indicates that the cause is nonexistent or 92 * unknown.) 93 */ MatchException(String message, Throwable cause)94 public MatchException(String message, Throwable cause) { 95 super(message, cause); 96 } 97 } 98