Java SE >Java SE Specifications >Java Language Specification
Table of Contents
if Statementassert Statementswitch Statementwhile Statementdo Statementfor Statementbreak Statementcontinue Statementreturn Statementthrow Statementsynchronized Statementtry statementyield StatementThe sequence of execution of a program is controlled bystatements, which are executed for their effect and do not have values.
Some statementscontain other statements as part of their structure; such other statements aresubstatements of the statement. We say that statementSimmediately contains statementU if there is no statementT different fromS andU such thatS containsT andT containsU. In the same manner, some statements contain expressions (§15 (Expressions)) as part of their structure.
The first section of this chapter discusses the distinction between normal and abrupt completion of statements (§14.1). Most of the remaining sections explain the various kinds of statements, describing in detail both their normal behavior and any special treatment of abrupt completion.
Blocks are explained first (§14.2), both because they can appear in certain places where statements are not allowed and because one kind of statement, a local variable declaration statement (§14.4.2), must be immediately contained by a block. Local class and interface declarations (§14.3) are not statements, but must also be immediately contained by a block.
Next, a grammatical maneuver that sidesteps the familiar "dangling else" problem (§14.5) is explained.
Every statement must bereachable in a certain technical sense (§14.22).
Sections 14.23-14.29 are unused to allow for the introduction of new kinds of statements in future.
The last section of this chapter (§14.30) describespatterns, which are used within statements and expressions to conditionally declare and initialize local variables. A pattern gives a concise description of how one value, such as an object, could be composed from one or more other values, denoted by variable declarations.Pattern matching attempts to extract one or more values from a given value, as if to decompose it, and uses the extracted values to initialize the variables declared by the pattern.
Every statement has a normal mode of execution in which certain computational steps are carried out. The following sections describe the normal mode of execution for each kind of statement.
If all the steps are carried out as described, with no indication of abrupt completion, the statement is said tocomplete normally. However, certain events may prevent a statement from completing normally:
Thebreak,yield,continue, andreturn statements (§14.15,§14.21,§14.16,§14.17) cause a transfer of control that may prevent normal completion of expressions, statements, and blocks that contain them.
Evaluation of certain expressions may throw exceptions from the Java Virtual Machine (§15.6). An explicitthrow (§14.18) statement also results in an exception. An exception causes a transfer of control that may prevent normal completion of statements.
If such an event occurs, then execution of one or more statements may be terminated before all steps of their normal mode of execution have completed; such statements are said tocomplete abruptly.
An abrupt completion always has an associatedreason, which is one of the following:
The terms "complete normally" and "complete abruptly" also apply to the evaluation of expressions (§15.6). The only reason an expression can complete abruptly is that an exception is thrown, because of either athrow with a given value (§14.18) or a run-time exception or error (§11 (Exceptions),§15.6).
If a statement evaluates an expression, abrupt completion of the expression always causes the immediate abrupt completion of the statement, with the same reason. All succeeding steps in the normal mode of execution are not performed.
Unless otherwise specified in this chapter, abrupt completion of a substatement causes the immediate abrupt completion of the statement itself, with the same reason, and all succeeding steps in the normal mode of execution of the statement are not performed.
Unless otherwise specified, a statement completes normally if all expressions it evaluates and all substatements it executes complete normally.
Ablock is a sequence of statements, local variable declaration statements, and local class and interface declarations within braces.
A block is executed by executing each of the local variable declaration statements and other statements in order from first to last (left to right). If all of these block statements complete normally, then the block completes normally. If any of these block statements complete abruptly for any reason, then the block completes abruptly for the same reason.
Alocal class is a nested class (§8 (Classes)) whose declaration is immediately contained by a block (§14.2).
Alocal interface is a nested interface (§9 (Interfaces)) whose declaration is immediately contained by a block.
The following productions are shown here for convenience:
Local class and interface declarations may be intermixed freely with statements (including local variable declaration statements) in the containing block.
It is a compile-time error if a local class or interface declaration has any of the access modifierspublic,protected, orprivate (§6.6).
It is a compile-time error if a local class or interface declaration has the modifierstatic (§8.1.1.4),sealed, ornon-sealed (§8.1.1.2,§9.1.1.4).
It is a compile-time error if the direct superclass or a direct superinterface of a local class issealed.
It is a compile-time error if a direct superinterface of a local interface issealed.
A local class may be a normal class (§8.1), an enum class (§8.9), or a record class (§8.10). Every local normal class is an inner class (§8.1.3). Every local enum class and local record class is implicitlystatic (§8.1.1.4), and therefore not an inner class.
A local interface may be a normal interface (§9.1), but not an annotation interface (§9.6). Every local interface is implicitlystatic (§9.1.1.3).
Like an anonymous class (§15.9.5), a local class or interface is not a member of any package, class, or interface (§7.1,§8.5). Unlike an anonymous class, a local class or interface has a simple name (§6.2,§6.7).
The scope and shadowing of a local class or interface declaration is specified in§6.3 and§6.4.
Example 14.3-1. Local Class Declarations
Here is an example that illustrates several aspects of the rules given above:
class Global { class Cyclic {} void foo() { new Cyclic(); // create a Global.Cyclic class Cyclic extends Cyclic {} // circular definition { class Local {} { class Local {} // compile-time error } class Local {} // compile-time error class AnotherLocal { void bar() { class Local {} // ok } } } class Local {} // ok, not in scope of prior Local }}The first statement of methodfoo creates an instance of the member classGlobal.Cyclic rather than an instance of the local classCyclic, because the statement appears prior to the scope of the local class declaration.
The fact that the scope of a local class declaration encompasses its whole declaration (not only its body) means that the definition of the local classCyclic is indeed cyclic because it extends itself rather thanGlobal.Cyclic. Consequently, the declaration of the local classCyclic is rejected at compile time.
Since local class names cannot be redeclared within the same method (or constructor or initializer, as the case may be), the second and third declarations ofLocal result in compile-time errors. However,Local can be redeclared in the context of another, more deeply nested, class such asAnotherLocal.
The final declaration ofLocal is legal, since it occurs outside the scope of any prior declaration ofLocal.
Alocal variable declaration declares and optionally initializes one or more local variables (§4.12.3).
See§8.3 forUnannType. The following productions from§4.3,§8.3, and§8.4.1 are shown here for convenience:
A local variable declaration can appear in the following locations:
The rules concerning annotation modifiers for a local variable declaration are specified in§9.7.4 and§9.7.5.
If the keywordfinal appears as a modifier for a local variable declaration, then the local variable is afinal variable (§4.12.4).
It is a compile-time error iffinal appears more than once as a modifier for a local variable declaration.
It is a compile-time error if theLocalVariableType isvar and any of the following are true:
Example 14.4-1. Local Variables Declared Withvar
The following code illustrates these rules restricting the use ofvar:
var a = 1; // Legalvar b = 2, c = 3.0; // Illegal: multiple declaratorsvar d[] = new int[4]; // Illegal: extra bracket pairsvar e; // Illegal: no initializervar f = { 6 }; // Illegal: array initializervar g = (g = 7); // Illegal: self reference in initializerThese restrictions help to avoid confusion about the type being represented byvar.
Eachdeclarator in a local variable declaration declares one local variable, whose name is theIdentifier that appears in the declarator.
If the optional keywordfinal appears at the start of the declaration, the variable being declared is a final variable (§4.12.4).
The declared type of a local variable is determined as follows:
If theLocalVariableType isUnannType, and no bracket pairs appear inUnannType orVariableDeclaratorId, then the type of the local variable is denoted byUnannType.
If theLocalVariableType isUnannType, and bracket pairs appear inUnannType orVariableDeclaratorId, then the type of the local variable is specified by§10.2.
If theLocalVariableType isvar, then letT be the type of the initializer expression when treated as if it did not appear in an assignment context, and were thus a standalone expression (§15.2). The type of the local variable is the upward projection ofT with respect to all synthetic type variables mentioned byT (§4.10.5).
It is a compile-time error ifT is the null type.
Because the initializer is treated as if it did not appear in an assignment context, an error occurs if it is a lambda expression (§15.27) or a method reference expression (§15.13).
The scope and shadowing of a local variable declaration is specified in§6.3 and§6.4.
References to a local variable from a nested class or interface, or a lambda expression, are restricted, as specified in§6.5.6.1.
Example 14.4.1-1. Type of Local Variables Declared Withvar
The following code illustrates the typing of variables declared withvar:
var a = 1; // a has type 'int'var b = java.util.List.of(1, 2); // b has type 'List<Integer>'var c = "x".getClass(); // c has type 'Class<? extends String>' // (see JLS 15.12.2.6)var d = new Object() {}; // d has the type of the anonymous classvar e = (CharSequence & Comparable<String>) "x"; // e has type CharSequence & Comparable<String>var f = () -> "hello"; // Illegal: lambda not in an assignment contextvar g = null; // Illegal: null typeNote that some variables declared withvar cannot be declared with an explicit type, because the type of the variable is not denotable.
Upward projection is applied to the type of the initializer when determining the type of the variable. If the type of the initializer contains capture variables, this projection maps the type of the initializer to a supertype that does not contain capture variables.
While it would be possible to allow the type of the variable to mention capture variables, by projecting them away we enforce an attractive invariant that the scope of a capture variable is never larger than the statement containing the expression whose type is captured. Informally, capture variables cannot "leak" into subsequent statements.
Alocal variable declaration statement consists of a local variable declaration.
Every local variable declaration statement is immediately contained by a block, whereas other kinds of statement (§14.5) may be immediately contained by either a block or another statement.
In the containing block, local variable declaration statements may be intermixed freely with other kinds of statements and with local class and interface declarations.
A local variable declaration statement is an executable statement. Every time it is executed, the declarators are processed in order from left to right. If a declarator has an initializer, the initializer is evaluated and its value is assigned to the variable.
If a declarator does not have an initializer, then every reference to the variable must be preceded by execution of an assignment to the variable, or a compile-time error occurs by the rules of§16 (Definite Assignment).
Each initializer (except the first) is evaluated only if evaluation of the preceding initializer completes normally.
Execution of the local variable declaration statement completes normally only if evaluation of the last initializer completes normally.
If none of the declarators in a local variable declaration statement have an initializer, then executing the statement always completes normally.
There are many kinds of statements in the Java programming language. Most correspond to statements in the C and C++ languages, but some are unique.
As in C and C++, theif statement of the Java programming language suffers from the so-called "danglingelse problem," illustrated by this misleadingly formatted example:
if (door.isOpen()) if (resident.isVisible()) resident.greet("Hello!");else door.bell.ring(); // A "dangling else"The problem is that both the outerif statement and the innerif statement might conceivably own theelse clause. In this example, one might surmise that the programmer intended theelse clause to belong to the outerif statement.
The Java programming language, like C and C++ and many programming languages before them, arbitrarily decrees that anelse clause belongs to the innermostif to which it might possibly belong. This rule is captured by the following grammar:
The following productions from§14.9 are shown here for convenience:
Statements are thus grammatically divided into two categories: those that might end in anif statement that has noelse clause (a "shortif statement") and those that definitely do not.
Only statements that definitely do not end in a shortif statement may appear as an immediate substatement before the keywordelse in anif statement that does have anelse clause.
This simple rule prevents the "danglingelse" problem. The execution behavior of a statement with the "no shortif" restriction is identical to the execution behavior of the same kind of statement without the "no shortif" restriction; the distinction is drawn purely to resolve the syntactic difficulty.
Statements may havelabel prefixes.
TheIdentifier is declared to be the label of the immediately containedStatement.
Unlike C and C++, the Java programming language has nogoto statement; identifier statement labels are used withbreak orcontinue statements (§14.15,§14.16) appearing anywhere within the labeled statement.
The scope of a label of a labeled statement is the immediately containedStatement.
It is a compile-time error if the name of a label of a labeled statement is used within the scope of the label as a label of another labeled statement.
There is no restriction against using the same identifier as a label and as the name of a package, class, interface, method, field, parameter, or local variable. Use of an identifier to label a statement does not obscure (§6.4.2) a package, class, interface, method, field, parameter, or local variable with the same name. Use of an identifier as a class, interface, method, field, local variable or as the parameter of an exception handler (§14.20) does not obscure a statement label with the same name.
A labeled statement is executed by executing the immediately containedStatement.
If the statement is labeled by anIdentifier and the containedStatement completes abruptly because of abreak with the sameIdentifier, then the labeled statement completes normally. In all other cases of abrupt completion of theStatement, the labeled statement completes abruptly for the same reason.
Example 14.7-1. Labels and Identifiers
The following code was taken from a version of the classString and its methodindexOf, where the label was originally calledtest. Changing the label to have the same name as the local variablei does not obscure the label in the scope of the declaration ofi. Thus, the code is valid.
class Test { char[] value; int offset, count; int indexOf(TestString str, int fromIndex) { char[] v1 = value, v2 = str.value; int max = offset + (count - str.count); int start = offset + ((fromIndex < 0) ? 0 : fromIndex); i: for (int i = start; i <= max; i++) { int n = str.count, j = i, k = str.offset; while (n-- != 0) { if (v1[j++] != v2[k++]) continue i; } return i - offset; } return -1; }}The identifiermax could also have been used as the statement label; the label would not obscure the local variablemax within the labeled statement.
Certain kinds of expressions may be used as statements by following them with semicolons.
Anexpression statement is executed by evaluating the expression; if the expression has a value, the value is discarded.
Execution of the expression statement completes normally if and only if evaluation of the expression completes normally.
Unlike C and C++, the Java programming language allows only certain forms of expressions to be used as expression statements. For example, it is legal to use a method invocation expression (§15.12):
System.out.println("Hello world"); // OKbut it is not legal to use a parenthesized expression (§15.8.5):
(System.out.println("Hello world")); // illegalNote that the Java programming language does not allow a "cast tovoid" -void is not a type - so the traditional C trick of writing an expression statement such as:
(void)... ; // incorrect!
does not work. On the other hand, the Java programming language allows all the most useful kinds of expressions in expression statements, and it does not require a method invocation used as an expression statement to invoke avoid method, so such a trick is almost never needed. If a trick is needed, either an assignment statement (§15.26) or a local variable declaration statement (§14.4) can be used instead.
Theif statement allows conditional execution of a statement or a conditional choice of two statements, executing one or the other but not both.
TheExpression must have typeboolean orBoolean, or a compile-time error occurs.
Anif-then statement is executed by first evaluating theExpression. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation of theExpression or the subsequent unboxing conversion (if any) completes abruptly for some reason, theif-then statement completes abruptly for the same reason.
Otherwise, execution continues by making a choice based on the resulting value:
Anif-then-else statement is executed by first evaluating theExpression. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation of theExpression or the subsequent unboxing conversion (if any) completes abruptly for some reason, then theif-then-else statement completes abruptly for the same reason.
Otherwise, execution continues by making a choice based on the resulting value:
If the value istrue, then the first containedStatement (the one before theelse keyword) is executed; theif-then-else statement completes normally if and only if execution of that statement completes normally.
If the value isfalse, then the second containedStatement (the one after theelse keyword) is executed; theif-then-else statement completes normally if and only if execution of that statement completes normally.
Anassertion is anassert statement containing a boolean expression. An assertion is eitherenabled ordisabled. If an assertion is enabled, execution of the assertion causes evaluation of the boolean expression and an error is reported if the expression evaluates tofalse. If the assertion is disabled, execution of the assertion has no effect whatsoever.
To ease the presentation, the firstExpression in both forms of theassert statement is referred to asExpression1. In the second form of theassert statement, the secondExpression is referred to asExpression2.
It is a compile-time error ifExpression1 does not have typeboolean orBoolean.
It is a compile-time error if, in the second form of theassert statement,Expression2 is void (§15.1).
Anassert statement that is executedafter its class or interface has completed initialization is enabled if and only if the host system has determined that the top level class or interface that lexically contains theassert statement enables assertions.
Whether a top level class or interface enables assertions is determined no later than the earliest of (i) the initialization of the top level class or interface, and (ii) the initialization of any class or interface nested in the top level class or interface. Whether a top level class or interface enables assertions cannot be changed after it has been determined.
Anassert statement that is executedbefore its class or interface has completed initialization is enabled.
This rule is motivated by a case that demands special treatment. Recall that the assertion status of a class is set no later than the time it is initialized. It is possible, though generally not desirable, to execute methods or constructors prior to initialization. This can happen when a class hierarchy contains a circularity in its static initialization, as in the following example:
public class Foo { public static void main(String[] args) { Baz.testAsserts(); // Will execute after Baz is initialized. }}class Bar { static { Baz.testAsserts(); // Will execute before Baz is initialized! }}class Baz extends Bar { static void testAsserts() { boolean enabled = false; assert enabled = true; System.out.println("Asserts " + (enabled ? "enabled" : "disabled")); }}InvokingBaz.testAsserts() causesBaz to be initialized. Before this can happen,Bar must be initialized.Bar's static initializer again invokesBaz.testAsserts(). Because initialization ofBaz is already in progress by the current thread, the second invocation executes immediately, thoughBaz is not initialized (§12.4.2).
Because of the rule above, if the program above is executed without enabling assertions, it must print:
Asserts enabledAsserts disabled
A disabledassert statement does nothing. In particular, neitherExpression1 norExpression2 (if it is present) are evaluated. Execution of a disabledassert statement always completes normally.
An enabledassert statement is executed by first evaluatingExpression1. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation ofExpression1 or the subsequent unboxing conversion (if any) completes abruptly for some reason, theassert statement completes abruptly for the same reason.
Otherwise, execution continues by making a choice based on the value ofExpression1:
Typically, assertion checking is enabled during program development and testing, and disabled for deployment, to improve performance.
Because assertions may be disabled, programs must not assume that the expressions contained in assertions will be evaluated. Thus, these boolean expressions should generally be free of side effects. Evaluating such a boolean expression should not affect any state that is visible after the evaluation is complete. It is not illegal for a boolean expression contained in an assertion to have a side effect, but it is generally inappropriate, as it could cause program behavior to vary depending on whether assertions were enabled or disabled.
In light of this, assertions should not be used for argument checking inpublic methods. Argument checking is typically part of the contract of a method, and this contract must be upheld whether assertions are enabled or disabled.
A secondary problem with using assertions for argument checking is that erroneous arguments should result in an appropriate run-time exception (such asIllegalArgumentException,ArrayIndexOutOfBoundsException, orNullPointerException). An assertion failure will not throw an appropriate exception. Again, it is not illegal to use assertions for argument checking onpublic methods, but it is generally inappropriate. It is intended thatAssertionError never be caught, but it is possible to do so, thus the rules fortry statements should treat assertions appearing in atry block similarly to the current treatment ofthrow statements.
Theswitch statement transfers control to one of several statements or expressions, depending on the value of an expression.
TheExpression is called theselector expression. The type of the selector expression must bechar,byte,short,int,Character,Byte,Short,Integer,String, or an enum type (§8.9), or a compile-time error occurs.
The body of both aswitch statement and aswitch expression (§15.28) is called aswitch block. This subsection presents general rules which apply to all switch blocks, whether they appear inswitch statements orswitch expressions. Other subsections present additional rules which apply either to switch blocks inswitch statements (§14.11.2) or to switch blocks inswitch expressions (§15.28.1).
A switch block can consist of either:
Every switch rule and switch labeled statement group starts with aswitch label, which is either acase label or adefault label. Multiple switch labels are permitted for a switch labeled statement group.
Acase label has one or morecase constants. Everycase constant must be either a constant expression (§15.29) or the name of an enum constant (§8.9.1), or a compile-time error occurs.
Switch labels and theircase constants are said to beassociated with the switch block. No two of thecase constants associated with a switch block may have the same value, or a compile-time error occurs.
The switch block of aswitch statement or aswitch expression iscompatible with the type of the selector expression,T, if both of the following are true:
IfT is not an enum type, then everycase constant associated with the switch block is assignment compatible withT (§5.2).
IfT is an enum type, then everycase constant associated with the switch block is an enum constant of typeT.
The switch block of aswitch statement or aswitch expression must be compatible with the type of the selector expression, or a compile-time error occurs.
Both the execution of aswitch statement (§14.11.3) and the evaluation of aswitch expression (§15.28.2) need to determine if a switch labelmatches the value of the selector expression. To determine whether a switch label in a switch block matches a given value, the value is compared with thecase constants associated with the switch block. Then:
If one of thecase constants is equal to the value, then we say that thecase label which contains thecase constantmatches.
Equality is defined in terms of the== operator (§15.21) unless the value is aString, in which case equality is defined in terms of theequals method of classString.
If nocase label matches but there is adefault label, then we say that thedefault labelmatches.
Acase label can contain severalcase constants. The label matches the value of the selector expression if any one of its constants matches the value of the selector expression. For example, in the following code, thecase label matches if the enum variableday is either one of the enum constants shown:
switch (day) { ... case SATURDAY, SUNDAY : System.out.println("It's the weekend!"); break; ...}null cannot be used as acase constant because it is not a constant expression. Even ifcasenull was allowed, it would be undesirable because the code in thatcase would never be executed. This is due to the fact that, given a selector expression of a reference type (that is,String or a boxed primitive type or an enum type), an exception will occur if the selector expression evaluates tonull at run time. In the judgment of the designers of the Java programming language, propagating the exception is a better outcome than either having nocase label match, or having thedefault label match.
A Java compiler is encouraged (but not required) to provide a warning if aswitch statement with an enum-typed selector expression lacks adefault label and lackscase labels for one or more of the enum's constants. Such aswitch statement will silently do nothing if the expression evaluates to one of the missing constants.
In C and C++ the body of aswitch statement can be a statement and statements withcase labels do not have to be immediately contained by that statement. Consider the simple loop:
for (i = 0; i < n; ++i) foo();
wheren is known to be positive. A trick known asDuff's device can be used in C or C++ to unroll the loop, but this is not valid code in the Java programming language:
int q = (n+7)/8;switch (n%8) { case 0: do { foo(); // Great C hack, Tom, case 7: foo(); // but it's not valid here. case 6: foo(); case 5: foo(); case 4: foo(); case 3: foo(); case 2: foo(); case 1: foo(); } while (--q > 0);}Fortunately, this trick does not seem to be widely known or used. Moreover, it is less needed nowadays; this sort of code transformation is properly in the province of state-of-the-art optimizing compilers.
In addition to the general rules for switch blocks (§14.11.1), there are further rules for switch blocks inswitch statements. Namely, all of the following must be true for the switch block of aswitch statement, or a compile-time error occurs:
No more than onedefault label is associated with theswitch block.
Every switch rule expression in the switch block is a statement expression (§14.8).
switch statements differ fromswitch expressions in terms of which expressions may appear to the right of an arrow (->) in the switch block, that is, which expressions may be used asswitch rule expressions. In aswitch statement, only a statement expression may be used as a switch rule expression, but in aswitch expression, any expression may be used (§15.28.1).
Aswitch statement is executed by first evaluating the selector expression. Then:
If evaluation of the selector expression completes abruptly, then the entireswitch statement completes abruptly for the same reason.
Otherwise, if the result of evaluating the selector expression isnull, then aNullPointerException is thrown and the entireswitch statement completes abruptly for that reason.
Otherwise, if the result of evaluating the selector expression is of typeCharacter,Byte,Short, orInteger, it is subjected to unboxing conversion (§5.1.8). If this conversion completes abruptly, the entireswitch statement completes abruptly for the same reason.
If evaluation of the selector expression completes normally and the result is non-null, and the subsequent unboxing conversion (if any) completes normally, then execution of theswitch statement continues by determining if a switch label associated with the switch block matches the value of the selector expression (§14.11.1). Then:
If no switch label matches, the entireswitch statement completes normally.
If a switch label matches, then one of the following applies:
If it is the switch label for a switch rule expression, then the switch rule expression is necessarily a statement expression (§14.11.2). The statement expression is evaluated. If the evaluation completes normally, then theswitch statement completes normally. If the result of evaluation is a value, it is discarded.
If it is the switch label for a switch rule block, then the block is executed. If this block completes normally, then theswitch statement completes normally.
If it is the switch label for a switch rulethrow statement, then thethrow statement is executed.
If it is the switch label for a switch labeled statement group, then all the statements in the switch block that follow the switch label are executed in order. If these statements complete normally, then theswitch statement completes normally.
Otherwise, there are no statements that follow the matched switch label in the switch block, and theswitch statement completes normally.
If execution of any statement or expression in the switch block completes abruptly, it is handled as follows:
If execution of a statement completes abruptly because of abreak with no label, then no further action is taken and theswitch statement completes normally.
Abrupt completion because of abreak with a label is handled by the general rule for labeled statements (§14.7).
If execution of a statement or expression completes abruptly for any other reason, then theswitch statement completes abruptly for the same reason.
Abrupt completion because of ayield statement is handled by the general rule for switch expressions (§15.28.2).
Example 14.11.3-1. Fall-Through in theswitch Statement
When a selector expression matches a switch label for a switch rule, the switch rule expression or statement introduced by the switch label is executed, and nothing else. In the case of a switch label for a statement group, all the block statements in the switch block that follow the switch label are executed, including those that appear after subsequent switch labels. The effect is that, as in C and C++, execution of statements can "fall through labels."
For example, the program:
class TooMany { static void howMany(int k) { switch (k) { case 1: System.out.print("one "); case 2: System.out.print("too "); case 3: System.out.println("many"); } } public static void main(String[] args) { howMany(3); howMany(2); howMany(1); }}contains aswitch block in which the code for eachcase falls through into the code for the nextcase. As a result, the program prints:
manytoo manyone too many
Fall through can be the cause of subtle bugs. If code is not to fall throughcase tocase in this manner, thenbreak statements can be used to indicate when control should be transferred, or switch rules can be used, as in the program:
class TwoMany { static void howMany(int k) { switch (k) { case 1: System.out.println("one"); break; // exit the switch case 2: System.out.println("two"); break; // exit the switch case 3: System.out.println("many"); break; // not needed, but good style } } static void howManyAgain(int k) { switch (k) { case 1 -> System.out.println("one"); case 2 -> System.out.println("two"); case 3 -> System.out.println("many"); } } public static void main(String[] args) { howMany(1); howMany(2); howMany(3); howManyAgain(1); howManyAgain(2); howManyAgain(3); }}This program prints:
onetwomanyonetwomany
Thewhile statement executes anExpression and aStatement repeatedly until the value of theExpression isfalse.
TheExpression must have typeboolean orBoolean, or a compile-time error occurs.
Awhile statement is executed by first evaluating theExpression. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation of theExpression or the subsequent unboxing conversion (if any) completes abruptly for some reason, thewhile statement completes abruptly for the same reason.
Otherwise, execution continues by making a choice based on the resulting value:
If the value istrue, then the containedStatement is executed. Then there is a choice:
If execution of theStatement completes normally, then the entirewhile statement is executed again, beginning by re-evaluating theExpression.
If execution of theStatement completes abruptly, see§14.12.1.
If the (possibly unboxed) value of theExpression isfalse, no further action is taken and thewhile statement completes normally.
If the (possibly unboxed) value of theExpression isfalse the first time it is evaluated, then theStatement is not executed.
Abrupt completion of the containedStatement is handled in the following manner:
If execution of theStatement completes abruptly because of abreak with no label, no further action is taken and thewhile statement completes normally.
If execution of theStatement completes abruptly because of acontinue with no label, then the entirewhile statement is executed again.
If execution of theStatement completes abruptly because of acontinue with labelL, then there is a choice:
If execution of theStatement completes abruptly for any other reason, thewhile statement completes abruptly for the same reason.
The case of abrupt completion because of abreak with a label is handled by the general rule for labeled statements (§14.7).
Thedo statement executes aStatement and anExpression repeatedly until the value of theExpression isfalse.
TheExpression must have typeboolean orBoolean, or a compile-time error occurs.
Ado statement is executed by first executing theStatement. Then there is a choice:
If execution of theStatement completes normally, then theExpression is evaluated. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation of theExpression or the subsequent unboxing conversion (if any) completes abruptly for some reason, thedo statement completes abruptly for the same reason.
If execution of theStatement completes abruptly, see§14.13.1.
Executing ado statement always executes the containedStatement at least once.
Abrupt completion of the containedStatement is handled in the following manner:
If execution of theStatement completes abruptly because of abreak with no label, then no further action is taken and thedo statement completes normally.
If execution of theStatement completes abruptly because of acontinue with no label, then theExpression is evaluated. Then there is a choice based on the resulting value:
If execution of theStatement completes abruptly because of acontinue with labelL, then there is a choice:
If execution of theStatement completes abruptly for any other reason, thedo statement completes abruptly for the same reason.
The case of abrupt completion because of abreak with a label is handled by the general rule for labeled statements (§14.7).
Example 14.13-1. Thedo Statement
The following code is one possible implementation of thetoHexString method of classInteger:
public static String toHexString(int i) { StringBuffer buf = new StringBuffer(8); do { buf.append(Character.forDigit(i & 0xF, 16)); i >>>= 4; } while (i != 0); return buf.reverse().toString();}Because at least one digit must be generated, thedo statement is an appropriate control structure.
Thefor statement has two forms:
The basicfor statement executes some initialization code, then executes anExpression, aStatement, and some update code repeatedly until the value of theExpression isfalse.
The type of theExpression must beboolean orBoolean, or a compile-time error occurs.
The scope and shadowing of a local variable declared in theForInit part of a basicfor statement is specified in§6.3 and§6.4.
References to a local variable declared in theForInit part of a basicfor statement from a nested class or interface, or a lambda expression, are restricted, as specified in§6.5.6.1.
Afor statement is executed by first executing theForInit code:
If theForInit code is a list of statement expressions (§14.8), the expressions are evaluated in sequence from left to right; their values, if any, are discarded.
If evaluation of any expression completes abruptly for some reason, thefor statement completes abruptly for the same reason; anyForInit statement expressions to the right of the one that completed abruptly are not evaluated.
If theForInit code is a local variable declaration (§14.4), it is executed as if it were a local variable declaration statement appearing in a block (§14.4.2).
If execution of the local variable declaration completes abruptly for any reason, thefor statement completes abruptly for the same reason.
Next, afor iteration step is performed, as follows:
If theExpression is present, it is evaluated. If the result is of typeBoolean, it is subjected to unboxing conversion (§5.1.8).
If evaluation of theExpression or the subsequent unboxing conversion (if any) completes abruptly, thefor statement completes abruptly for the same reason.
Otherwise, there is then a choice based on the presence or absence of theExpression and the resulting value if theExpression is present; see next bullet.
If theExpression is not present, or it is present and the value resulting from its evaluation (including any possible unboxing) istrue, then the containedStatement is executed. Then there is a choice:
If execution of theStatement completes normally, then the following two steps are performed in sequence:
First, if theForUpdate part is present, the expressions are evaluated in sequence from left to right; their values, if any, are discarded. If evaluation of any expression completes abruptly for some reason, thefor statement completes abruptly for the same reason; anyForUpdate statement expressions to the right of the one that completed abruptly are not evaluated.
If execution of theStatement completes abruptly, see§14.14.1.3.
If theExpression is present and the value resulting from its evaluation (including any possible unboxing) isfalse, no further action is taken and thefor statement completes normally.
If the (possibly unboxed) value of theExpression isfalse the first time it is evaluated, then theStatement is not executed.
If theExpression is not present, then the only way afor statement can complete normally is by use of abreak statement.
Abrupt completion of the containedStatement is handled in the following manner:
If execution of theStatement completes abruptly because of abreak with no label, no further action is taken and thefor statement completes normally.
If execution of theStatement completes abruptly because of acontinue with no label, then the following two steps are performed in sequence:
If execution of theStatement completes abruptly because of acontinue with labelL, then there is a choice:
If execution of theStatement completes abruptly for any other reason, thefor statement completes abruptly for the same reason.
Note that the case of abrupt completion because of abreak with a label is handled by the general rule for labeled statements (§14.7).
The enhancedfor statement has the form:
The following productions from§4.3,§8.3,§8.4.1, and§14.4 are shown here for convenience:
The type of theExpression must be an array type (§10.1) or a subtype of the raw typeIterable, or a compile-time error occurs.
The header of the enhancedfor statement declares a local variable whose name is the identifier given byVariableDeclaratorId. When the enhancedfor statement is executed, the local variable is initialized, on each iteration of the loop, to successive elements of theIterable or the array produced by the expression.
The rules for a local variable declared in the header of an enhancedfor statement are specified in§14.4, disregarding any rules in that section which apply when theLocalVariableType isvar. In addition, all of the following must be true, or a compile-time error occurs:
The scope and shadowing of a local variable declared in the header of an enhancedfor statement is specified in§6.3 and§6.4.
References to the local variable from a nested class or interface, or a lambda expression, are restricted, as specified in§6.5.6.1.
The typeT of the local variable declared in the header of the enhancedfor statement is determined as follows:
If theLocalVariableType isUnannType, and no bracket pairs appear inUnannType orVariableDeclaratorId, thenT is the type denoted byUnannType.
If theLocalVariableType isUnannType, and bracket pairs appear inUnannType orVariableDeclaratorId, thenT is specified by§10.2.
If theLocalVariableType isvar, then letR be derived from the type of theExpression, as follows:
T is the upward projection ofR with respect to all synthetic type variables mentioned byR (§4.10.5).
The precise meaning of the enhancedfor statement is given by translation into a basicfor statement, as follows:
If the type ofExpression is a subtype ofIterable, then the basicfor statement has this form:
for (I #i =Expression.iterator(); #i.hasNext(); ) {{VariableModifier} T Identifier = (TargetType) #i.next();Statement}
If the type ofExpression is a subtype ofIterable<X> for some type argumentX, thenI is the typejava.util.Iterator<X>. Otherwise,I is the raw typejava.util.Iterator.
#i is an automatically generated identifier that is distinct from any other identifiers (automatically generated or otherwise) that are in scope (§6.3) at the point where the enhancedfor statement occurs.
{VariableModifier} is as given in the header of the enhancedfor statement.
IfT is a reference type, thenTargetType isT. Otherwise,TargetType is the upper bound of the capture conversion (§5.1.10) of the type argument ofI, orObject ifI is raw.
Otherwise, theExpression necessarily has an array type,S[], and the basicfor statement has this form:
S[]#a =Expression;L1:L2: ...Lm:for (int #i = 0; #i < #a.length; #i++) {{VariableModifier} T Identifier = #a[#i];Statement}
L1 ...Lm is the (possibly empty) sequence of labels immediately preceding the enhancedfor statement.
#a and#i are automatically generated identifiers that are distinct from any other identifiers (automatically generated or otherwise) that are in scope at the point where the enhancedfor statement occurs.
{VariableModifier} is as given in the header of the enhancedfor statement.
For example, this code:
List<? extends Integer> l = ...for (float i : l) ...
will be translated to:
for (Iterator<Integer> #i = l.iterator(); #i.hasNext(); ) { float #i0 = (Integer)#i.next(); ...Example 14.14-1. Enhancedfor And Arrays
The following program, which calculates the sum of an integer array, shows how enhancedfor works for arrays:
int sum(int[] a) { int sum = 0; for (int i : a) sum += i; return sum;}Example 14.14-2. Enhancedfor And Unboxing Conversion
The following program combines the enhancedfor statement with auto-unboxing to translate a histogram into a frequency table:
Map<String, Integer> histogram = ...;double total = 0;for (int i : histogram.values()) total += i;for (Map.Entry<String, Integer> e : histogram.entrySet()) System.out.println(e.getKey() + " " + e.getValue() / total);}
Abreak statement transfers control out of an enclosing statement.
There are two kinds ofbreak statement:
Abreak statement with no label attempts to transfer control to the innermost enclosingswitch,while,do, orfor statement; this enclosing statement, which is called thebreak target, then immediately completes normally.
Abreak statement with labelIdentifier attempts to transfer control to the enclosing labeled statement (§14.7) that has the sameIdentifier as its label; this enclosing statement, which is called thebreak target, then immediately completes normally. In this case, the break target need not be aswitch,while,do, orfor statement.
It is a compile-time error if abreak statement has no break target.
It is a compile-time error if the break target contains any method, constructor, instance initializer, static initializer, lambda expression, or switch expression that encloses thebreak statement. That is, there are no non-local jumps.
Execution of abreak statement with no label always completes abruptly, the reason being abreak with no label.
Execution of abreak statement with labelIdentifier always completes abruptly, the reason being abreak with labelIdentifier.
It can be seen, then, that abreak statement always completes abruptly.
The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are anytry statements (§14.20) within the break target whosetry blocks orcatch clauses contain thebreak statement, then anyfinally clauses of thosetry statements are executed, in order, innermost to outermost, before control is transferred to the break target. Abrupt completion of afinally clause can disrupt the transfer of control initiated by abreak statement.
Example 14.15-1. Thebreak Statement
In the following example, a mathematical graph is represented by an array of arrays. A graph consists of a set of nodes and a set of edges; each edge is an arrow that points from some node to some other node, or from a node to itself. In this example it is assumed that there are no redundant edges; that is, for any two nodesP andQ, whereQ may be the same asP, there is at most one edge fromP toQ.
Nodes are represented by integers, and there is an edge from nodei to nodeedges[ for everyi][j]i andj for which the array referenceedges[ does not throw ani][j]ArrayIndexOutOfBoundsException.
The task of the methodloseEdges, given integersi andj, is to construct a new graph by copying a given graph but omitting the edge from nodei to nodej, if any, and the edge from nodej to nodei, if any:
class Graph { int[][] edges; public Graph(int[][] edges) { this.edges = edges; } public Graph loseEdges(int i, int j) { int n = edges.length; int[][] newedges = new int[n][]; for (int k = 0; k < n; ++k) {edgelist:{ int z;search:{ if (k == i) { for (z = 0; z < edges[k].length; ++z) { if (edges[k][z] == j) break search; } } else if (k == j) { for (z = 0; z < edges[k].length; ++z) { if (edges[k][z] == i) break search; } } // No edge to be deleted; share this list. newedges[k] = edges[k]; break edgelist;} //search // Copy the list, omitting the edge at position z. int m = edges[k].length - 1; int[] ne = new int[m]; System.arraycopy(edges[k], 0, ne, 0, z); System.arraycopy(edges[k], z+1, ne, z, m-z); newedges[k] = ne;} //edgelist } return new Graph(newedges); }}Note the use of two statement labels,edgelist andsearch, and the use ofbreak statements. This allows the code that copies a list, omitting one edge, to be shared between two separate tests, the test for an edge from nodei to nodej, and the test for an edge from nodej to nodei.
Acontinue statement may occur only in awhile,do, orfor statement; statements of these three kinds are callediteration statements. Control passes to the loop-continuation point of an iteration statement.
There are two kinds ofcontinue statement:
Acontinue statement with no label attempts to transfer control to the innermost enclosingwhile,do, orfor statement; this enclosing statement, which is called thecontinue target, then immediately ends the current iteration and begins a new one.
Acontinue statement with labelIdentifier attempts to transfer control to the enclosing labeled statement (§14.7) that has the sameIdentifier as its label; this enclosing statement, which is called thecontinue target, then immediately ends the current iteration and begins a new one. In this case, the continue target must be awhile,do, orfor statement, or a compile-time error occurs.
It is a compile-time error if acontinue statement has no continue target.
It is a compile-time error if the continue target contains any method, constructor, instance initializer, static initializer, lambda expression, or switch expression that encloses thecontinue statement. That is, there are no non-local jumps.
Execution of acontinue statement with no label always completes abruptly, the reason being acontinue with no label.
Execution of acontinue statement with labelIdentifier always completes abruptly, the reason being acontinue with labelIdentifier.
It can be seen, then, that acontinue statement always completes abruptly.
See the descriptions of thewhile statement (§14.12),do statement (§14.13), andfor statement (§14.14) for a discussion of the handling of abrupt termination because ofcontinue.
The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are anytry statements (§14.20) within the continue target whosetry blocks orcatch clauses contain thecontinue statement, then anyfinally clauses of thosetry statements are executed, in order, innermost to outermost, before control is transferred to the continue target. Abrupt completion of afinally clause can disrupt the transfer of control initiated by acontinue statement.
Example 14.16-1. Thecontinue Statement
In theGraph class in§14.15, one of thebreak statements is used to finish execution of the entire body of the outermostfor loop. This break can be replaced by acontinue if thefor loop itself is labeled:
class Graph { int[][] edges; public Graph(int[][] edges) { this.edges = edges; } public Graph loseEdges(int i, int j) { int n = edges.length; int[][] newedges = new int[n][];edgelists: for (int k = 0; k < n; ++k) { int z;search:{ if (k == i) { for (z = 0; z < edges[k].length; ++z) { if (edges[k][z] == j) break search; } } else if (k == j) { for (z = 0; z < edges[k].length; ++z) { if (edges[k][z] == i) break search; } } // No edge to be deleted; share this list. newedges[k] = edges[k]; continue edgelists;} //search // Copy the list, omitting the edge at position z. int m = edges[k].length - 1; int[] ne = new int[m]; System.arraycopy(edges[k], 0, ne, 0, z); System.arraycopy(edges[k], z+1, ne, z, m-z); newedges[k] = ne; } //edgelists return new Graph(newedges); }}Which to use, if either, is largely a matter of programming style.
Areturn statement returns control to the invoker of a method (§8.4,§15.12) or constructor (§8.8,§15.9).
There are two kinds ofreturn statement:
Areturn statement attempts to transfer control to the invoker of the innermost enclosing constructor, method, or lambda expression; this enclosing declaration or expression is called thereturn target. In the case of areturn statement with valueExpression, the value of theExpression becomes the value of the invocation.
It is a compile-time error if areturn statement has no return target.
It is a compile-time error if the return target contains either (i) an instance or static initializer that encloses thereturn statement, or (ii) aswitch expression that encloses thereturn statement.
It is a compile-time error if the return target of areturn statement with no value is a method, and that method is not declaredvoid.
It is a compile-time error if the return target of areturn statement with valueExpression is either a constructor, or a method that is declaredvoid.
It is a compile-time error if the return target of areturn statement with valueExpression is a method with declared return typeT, and the type ofExpression is not assignable compatible (§5.2) withT.
Execution of areturn statement with no value always completes abruptly, the reason being a return with no value.
Execution of areturn statement with valueExpression first evaluates theExpression. If the evaluation of theExpression completes abruptly for some reason, then thereturn statement completes abruptly for that reason. If evaluation of theExpression completes normally, producing a valueV, then thereturn statement completes abruptly, the reason being a return with valueV.
It can be seen, then, that areturn statement always completes abruptly.
The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are anytry statements (§14.20) within the method or constructor whosetry blocks orcatch clauses contain thereturn statement, then anyfinally clauses of thosetry statements will be executed, in order, innermost to outermost, before control is transferred to the invoker of the method or constructor. Abrupt completion of afinally clause can disrupt the transfer of control initiated by areturn statement.
Athrow statement causes an exception (§11 (Exceptions)) to be thrown. The result is an immediate transfer of control (§11.3) that may exit multiple statements and multiple constructor, instance initializer, static initializer and field initializer evaluations, and method invocations until atry statement (§14.20) is found that catches the thrown value. If no suchtry statement is found, then execution of the thread (§17 (Threads and Locks)) that executed thethrow is terminated (§11.3) after invocation of theuncaughtException method for the thread group to which the thread belongs.
TheExpression in athrow statement must either denote a variable or value of a reference type which is assignable (§5.2) to the typeThrowable, or denote the null reference, or a compile-time error occurs.
The reference type of theExpression will always be a class type (since no interface types are assignable toThrowable) which is not parameterized (since a subclass ofThrowable cannot be generic (§8.1.2)).
At least one of the following three conditions must be true, or a compile-time error occurs:
The type of theExpression is an unchecked exception class (§11.1.1) or the null type (§4.1).
Thethrow statement is contained in thetry block of atry statement (§14.20) and it is not the case that thetry statement can throw an exception of the type of theExpression. (In this case we say the thrown value iscaught by thetry statement.)
Thethrow statement is contained in a method or constructor declaration and the type of theExpression is assignable (§5.2) to at least one type listed in thethrows clause (§8.4.6,§8.8.5) of the declaration.
The exception types that athrow statement can throw are specified in§11.2.2.
Athrow statement first evaluates theExpression. Then:
If evaluation of theExpression completes abruptly for some reason, then thethrow completes abruptly for that reason.
If evaluation of theExpression completes normally, producing a non-null valueV, then thethrow statement completes abruptly, the reason being athrow with valueV.
If evaluation of theExpression completes normally, producing anull value, then an instanceV' of classNullPointerException is created and thrown instead ofnull. Thethrow statement then completes abruptly, the reason being athrow with valueV'.
It can be seen, then, that athrow statement always completes abruptly.
If there are any enclosingtry statements (§14.20) whosetry blocks contain thethrow statement, then anyfinally clauses of thosetry statements are executed as control is transferred outward, until the thrown value is caught. Note that abrupt completion of afinally clause can disrupt the transfer of control initiated by athrow statement.
If athrow statement is contained in a method declaration or a lambda expression, but its value is not caught by sometry statement that contains it, then the invocation of the method completes abruptly because of thethrow.
If athrow statement is contained in a constructor declaration, but its value is not caught by sometry statement that contains it, then the class instance creation expression that invoked the constructor will complete abruptly because of thethrow (§15.9.4).
If athrow statement is contained in a static initializer (§8.7), then a compile-time check (§11.2.3) ensures that either its value is always an unchecked exception or its value is always caught by sometry statement that contains it. If at run time, despite this check, the value is not caught by sometry statement that contains thethrow statement, then the value is rethrown if it is an instance of classError or one of its subclasses; otherwise, it is wrapped in anExceptionInInitializerError object, which is then thrown (§12.4.2).
If athrow statement is contained in an instance initializer (§8.6), then a compile-time check (§11.2.3) ensures that either its value is always an unchecked exception or its value is always caught by sometry statement that contains it, or the type of the thrown exception (or one of its superclasses) occurs in thethrows clause of every constructor of the class.
By convention, user-declared throwable types should usually be declared to be subclasses of classException, which is a subclass of classThrowable (§11.1.1).
Asynchronized statement acquires a mutual-exclusion lock (§17.1) on behalf of the executing thread, executes a block, then releases the lock. While the executing thread owns the lock, no other thread may acquire the lock.
The type ofExpression must be a reference type, or a compile-time error occurs.
Asynchronized statement is executed by first evaluating theExpression. Then:
If evaluation of theExpression completes abruptly for some reason, then thesynchronized statement completes abruptly for the same reason.
Otherwise, if the value of theExpression isnull, aNullPointerException is thrown.
Otherwise, let the non-null value of theExpression beV. The executing thread locks the monitor associated withV. Then theBlock is executed, and then there is a choice:
The locks acquired bysynchronized statements are the same as the locks that are acquired implicitly bysynchronized methods (§8.4.3.6). A single thread may acquire a lock more than once.
Acquiring the lock associated with an object does not in itself prevent other threads from accessing fields of the object or invoking un-synchronized methods on the object. Other threads can also usesynchronized methods or thesynchronized statement in a conventional manner to achieve mutual exclusion.
Example 14.19-1. Thesynchronized Statement
class Test { public static void main(String[] args) { Test t = new Test(); synchronized(t) { synchronized(t) { System.out.println("made it!"); } } }}This program produces the output:
made it!
Note that this program would deadlock if a single thread were not permitted to lock a monitor more than once.
Atry statement executes a block. If a value is thrown and thetry statement has one or morecatch clauses that can catch it, then control will be transferred to the first suchcatch clause. If thetry statement has afinally clause, then another block of code is executed, no matter whether thetry block completes normally or abruptly, and no matter whether acatch clause is first given control.
See§8.3 forUnannClassType. The following productions from§4.3,§8.3, and§8.4.1 are shown here for convenience:
TheBlock immediately after the keywordtry is called thetry block of thetry statement.
TheBlock immediately after the keywordfinally is called thefinally block of thetry statement.
Atry statement may havecatch clauses, also calledexception handlers.
Acatch clause declares exactly one parameter, which is called anexception parameter.
It is a compile-time error iffinal appears more than once as a modifier for an exception parameter declaration.
The scope and shadowing of an exception parameter is specified in§6.3 and§6.4.
References to an exception parameter from a nested class or interface, or a lambda expression, are restricted, as specified in§6.5.6.1.
An exception parameter may denote its type as either a single class type or a union of two or more class types (calledalternatives). The alternatives of a union are syntactically separated by|.
Acatch clause whose exception parameter is denoted as a single class type is called auni-catch clause.
Acatch clause whose exception parameter is denoted as a union of types is called amulti-catch clause.
Each class type used in the denotation of the type of an exception parameter must be the classThrowable or a subclass ofThrowable, or a compile-time error occurs.
It is a compile-time error if a type variable is used in the denotation of the type of an exception parameter.
It is a compile-time error if a union of types contains two alternativesDi andDj (i≠j) whereDi is a subtype ofDj (§4.10.2).
The declared type of an exception parameter that denotes its type with a single class type is that class type.
The declared type of an exception parameter that denotes its type as a union with alternativesD1|D2| ...|Dn is lub(D1,D2, ...,Dn).
An exception parameter of a multi-catch clause is implicitly declaredfinal if it is not explicitly declaredfinal.
It is a compile-time error if an exception parameter that is implicitly or explicitly declaredfinal is assigned to within the body of thecatch clause.
An exception parameter of a uni-catch clause is never implicitly declaredfinal, but it may be explicitly declaredfinal or be effectively final (§4.12.4).
An implicitlyfinal exception parameter is final by virtue of its declaration, while an effectively final exception parameter is (as it were) final by virtue of how it is used. An exception parameter of a multi-catch clause is implicitly declaredfinal, so will never occur as the left-hand operand of an assignment operator, but it isnot considered effectively final.
If an exception parameter is effectively final (in a uni-catch clause) or implicitly final (in a multi-catch clause), then adding an explicitfinal modifier to its declaration will not introduce any compile-time errors. On the other hand, if the exception parameter of a uni-catch clause is explicitly declaredfinal, then removing thefinal modifier may introduce compile-time errors because the exception parameter, now considered to be effectively final, can no longer longer be referenced by anonymous and local class declarations in the body of thecatch clause. If there are no compile-time errors, it is possible to further change the program so that the exception parameter is re-assigned in the body of thecatch clause and thus will no longer be considered effectively final.
The exception types that atry statement can throw are specified in§11.2.2.
The relationship of the exceptions thrown by thetry block of atry statement and caught by thecatch clauses (if any) of thetry statement is specified in§11.2.3.
Exception handlers are considered in left-to-right order: the earliest possiblecatch clause accepts the exception, receiving as its argument the thrown exception object, as specified in§11.3.
A multi-catch clause can be thought of as a sequence of uni-catch clauses. That is, acatch clause where the type of the exception parameter is denoted as a unionD1|D2|...|Dn is equivalent to a sequence ofncatch clauses where the types of the exception parameters are class typesD1,D2, ...,Dn respectively. In theBlock of each of thencatch clauses, the declared type of the exception parameter is lub(D1,D2, ...,Dn). For example, the following code:
try { ... throws ReflectiveOperationException ...}catch (ClassNotFoundException | IllegalAccessException ex) { ... body ...}is semantically equivalent to the following code:
try { ... throws ReflectiveOperationException ...}catch (final ClassNotFoundException ex1) { final ReflectiveOperationException ex = ex1; ... body ...}catch (final IllegalAccessException ex2) { final ReflectiveOperationException ex = ex2; ... body ...} where the multi-catch clause with two alternatives has been translated into two uni-catch clauses, one for each alternative. A Java compiler is neither required nor recommended to compile a multi-catch clause by duplicating code in this manner, since it is possible to represent the multi-catch clause in aclass file without duplication.
Afinally clause ensures that thefinally block is executed after thetry block and anycatch block that might be executed, no matter how control leaves thetry block orcatch block. Handling of thefinally block is rather complex, so the two cases of atry statement with and without afinally block are described separately (§14.20.1,§14.20.2).
Atry statement is permitted to omitcatch clauses and afinally clause if it is atry-with-resources statement (§14.20.3).
Atry statement without afinally block is executed by first executing thetry block. Then there is a choice:
If execution of thetry block completes normally, then no further action is taken and thetry statement completes normally.
If execution of thetry block completes abruptly because of athrow of a valueV, then there is a choice:
If the run-time type ofV is assignment compatible with (§5.2) a catchable exception class of anycatch clause of thetry statement, then the first (leftmost) suchcatch clause is selected. The valueV is assigned to the parameter of the selectedcatch clause, and theBlock of thatcatch clause is executed, and then there is a choice:
If the run-time type ofV is not assignment compatible with a catchable exception class of anycatch clause of thetry statement, then thetry statement completes abruptly because of athrow of the valueV.
If execution of thetry block completes abruptly for any other reason, then thetry statement completes abruptly for the same reason.
Example 14.20.1-1. Catching An Exception
class BlewIt extends Exception { BlewIt() { } BlewIt(String s) { super(s); }}class Test { static void blowUp() throws BlewIt { throw new BlewIt(); } public static void main(String[] args) { try { blowUp(); } catch (RuntimeException r) { System.out.println("Caught RuntimeException"); } catch (BlewIt b) { System.out.println("Caught BlewIt"); } }}Here, the exceptionBlewIt is thrown by the methodblowUp. Thetry-catch statement in the body ofmain has twocatch clauses. The run-time type of the exception isBlewIt which is not assignable to a variable of typeRuntimeException, but is assignable to a variable of typeBlewIt, so the output of the example is:
Caught BlewIt
Atry statement with afinally block is executed by first executing thetry block. Then there is a choice:
If execution of thetry block completes normally, then thefinally block is executed, and then there is a choice:
If execution of thetry block completes abruptly because of athrow of a valueV, then there is a choice:
If the run-time type ofV is assignment compatible with a catchable exception class of anycatch clause of thetry statement, then the first (leftmost) suchcatch clause is selected. The valueV is assigned to the parameter of the selectedcatch clause, and theBlock of thatcatch clause is executed. Then there is a choice:
If the run-time type ofV is not assignment compatible with a catchable exception class of anycatch clause of thetry statement, then thefinally block is executed. Then there is a choice:
If execution of thetry block completes abruptly for any other reasonR, then thefinally block is executed, and then there is a choice:
Example 14.20.2-1. Handling An Uncaught Exception Withfinally
class BlewIt extends Exception { BlewIt() { } BlewIt(String s) { super(s); }}class Test { static void blowUp() throws BlewIt { throw new NullPointerException(); } public static void main(String[] args) { try { blowUp(); } catch (BlewIt b) { System.out.println("Caught BlewIt"); } finally { System.out.println("Uncaught Exception"); } }}This program produces the output:
Uncaught ExceptionException in thread "main" java.lang.NullPointerException at Test.blowUp(Test.java:7) at Test.main(Test.java:11)
TheNullPointerException (which is a kind ofRuntimeException) that is thrown by methodblowUp is not caught by thetry statement inmain, because aNullPointerException is not assignable to a variable of typeBlewIt. This causes thefinally clause to execute, after which the thread executingmain, which is the only thread of the test program, terminates because of an uncaught exception, which typically results in printing the exception name and a simple backtrace. However, a backtrace is not required by this specification.
The problem with mandating a backtrace is that an exception can be created at one point in the program and thrown at a later one. It is prohibitively expensive to store a stack trace in an exception unless it is actually thrown (in which case the trace may be generated while unwinding the stack). Hence we do not mandate a back trace in every exception.
Atry-with-resources statement is parameterized with variables (known asresources) that are initialized before execution of thetry block and closed automatically, in the reverse order from which they were initialized, after execution of thetry block.catch clauses and afinally clause are often unnecessary when resources are closed automatically.
The following productions from§4.3,§8.3,§8.4.1, and§14.4 are shown here for convenience:
See§8.3 forUnannType.
Theresource specification denotes the resources of thetry-with-resources statement, either by declaring local variables with initializer expressions or by referring to existing variables. An existing variable is referred to by an expression name (§6.5.6) or a field access expression (§15.11).
The rules for a local variable declared in a resource specification are specified in§14.4. In addition, all of the following must be true, or a compile-time error occurs:
The scope and shadowing of a local variable declared in a resource specification is specified in§6.3 and§6.4.
References to the local variable from a nested class or interface, or a lambda expression, are restricted, as specified in§6.5.6.1.
The type of a local variable declared in a resource specification is specified in§14.4.1.
The type of a local variable declared in a resource specification, or the type of an existing variable referred to in a resource specification, must be a subtype ofAutoCloseable, or a compile-time error occurs.
It is a compile-time error for a resource specification to declare two local variables with the same name.
A local variable declared in a resource specification is implicitly declaredfinal if it is not explicitly declaredfinal (§4.12.4).
An existing variable referred to in a resource specification must be afinal or effectivelyfinal variable that is definitely assigned before thetry-with-resources statement (§16 (Definite Assignment)), or a compile-time error occurs.
Resources are initialized in left-to-right order. If a resource fails to initialize (that is, its initializer expression throws an exception), then all resources initialized so far by thetry-with-resources statement are closed. If all resources initialize successfully, thetry block executes as normal and then all non-null resources of thetry-with-resources statement are closed.
Resources are closed in the reverse order from that in which they were initialized. A resource is closed only if it initialized to a non-null value. An exception from the closing of one resource does not prevent the closing of other resources. Such an exception issuppressed if an exception was thrown previously by an initializer, thetry block, or the closing of a resource.
Atry-with-resources statement whose resource specification indicates multiple resources is treated as if it were multipletry-with-resources statements, each of which has a resource specification that indicates a single resource. When atry-with-resources statement withn resources (n > 1) is translated, the result is atry-with-resources statement withn-1 resources. Aftern such translations, there aren nestedtry-catch-finally statements, and the overall translation is complete.
Atry-with-resources statement with nocatch clauses orfinally clause is called abasictry-with-resources statement.
If a basictry-with-resources statement is of the form:
try (VariableAccess ...)Blockthen the resource is first converted to a local variable declaration by the following translation:
try (T #r = VariableAccess ...) {Block}T is the type of the variable denoted byVariableAccess and#r is an automatically generated identifier that is distinct from any other identifiers (automatically generated or otherwise) that are in scope at the point where thetry-with-resources statement occurs. Thetry-with-resources statement is then translated according to the rest of this section.
The meaning of a basictry-with-resources statement of the form:
try ({VariableModifier} R Identifier =Expression ...)Block
is given by the following translation to a local variable declaration and atry-catch-finally statement:
{ final{VariableModifierNoFinal} R Identifier =Expression; Throwable #primaryExc = null; tryResourceSpecification_tailBlock catch (Throwable #t) { #primaryExc = #t; throw #t; } finally { if (Identifier != null) { if (#primaryExc != null) { try {Identifier.close(); } catch (Throwable #suppressedExc) { #primaryExc.addSuppressed(#suppressedExc); } } else {Identifier.close(); } } }}{VariableModifierNoFinal} is defined as{VariableModifier} withoutfinal, if present.
#t,#primaryExc, and#suppressedExc are automatically generated identifiers that are distinct from any other identifiers (automatically generated or otherwise) that are in scope at the point where thetry-with-resources statement occurs.
If the resource specification indicates one resource, thenResourceSpecification_tail is empty (and thetry-catch-finally statement is not itself atry-with-resources statement).
If the resource specification indicatesn > 1 resources, thenResourceSpecification_tail consists of the 2nd, 3rd, ...,n'th resources indicated in the resource specification, in the same order (and thetry-catch-finally statement is itself atry-with-resources statement).
Reachability and definite assignment rules for the basictry-with-resources statement are implicitly specified by the translation above.
In a basictry-with-resources statement that manages a single resource:
If the initialization of the resource completes abruptly because of athrow of a valueV, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
If the initialization of the resource completes normally, and thetry block completes abruptly because of athrow of a valueV, then:
If the automatic closing of the resource completes normally, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
If the automatic closing of the resource completes abruptly because of athrow of a valueV2, then thetry-with-resources statement completes abruptly because of athrow of the valueV, withV2 added to the suppressed exception list ofV.
If the initialization of the resource completes normally, and thetry block completes normally, and the automatic closing of the resource completes abruptly because of athrow of a valueV, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
In a basictry-with-resources statement that manages multiple resources:
If the initialization of a resource completes abruptly because of athrow of a valueV, then:
If the automatic closings of all successfully initialized resources (possibly zero) complete normally, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
If the automatic closings of all successfully initialized resources (possibly zero) complete abruptly because ofthrows of valuesV1...Vn, then thetry-with-resources statement completes abruptly because of athrow of the valueV, with any remaining valuesV1...Vn added to the suppressed exception list ofV.
If the initialization of all resources completes normally, and thetry block completes abruptly because of athrow of a valueV, then:
If the automatic closings of all initialized resources complete normally, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
If the automatic closings of one or more initialized resources complete abruptly because ofthrows of valuesV1...Vn, then thetry-with-resources statement completes abruptly because of athrow of the valueV, with any remaining valuesV1...Vn added to the suppressed exception list ofV.
If the initialization of every resource completes normally, and thetry block completes normally, then:
If one automatic closing of an initialized resource completes abruptly because of athrow of valueV, and all other automatic closings of initialized resources complete normally, then thetry-with-resources statement completes abruptly because of athrow of the valueV.
If more than one automatic closing of an initialized resource completes abruptly because ofthrows of valuesV1...Vn (whereV1 is the exception from the rightmost resource failing to close andVn is the exception from the leftmost resource failing to close), then thetry-with-resources statement completes abruptly because of athrow of the valueV1, with any remaining valuesV2...Vn added to the suppressed exception list ofV1.
Atry-with-resources statement with at least onecatch clause and/or afinally clause is called anextendedtry-with-resources statement.
The meaning of an extendedtry-with-resources statement:
tryResourceSpecificationBlock[Catches][Finally]
is given by the following translation to a basictry-with-resources statement nested inside atry-catch ortry-finally ortry-catch-finally statement:
try { tryResourceSpecification Block}[Catches][Finally]The effect of the translation is to put the resource specification "inside" thetry statement. This allows acatch clause of an extendedtry-with-resources statement to catch an exception due to the automatic initialization or closing of any resource.
Furthermore, all resources will have been closed (or attempted to be closed) by the time thefinally block is executed, in keeping with the intent of thefinally keyword.
Ayield statement transfers control by causing an enclosingswitch expression (§15.28) to produce a specified value.
Ayield statement attempts to transfer control to the innermost enclosingswitch expression; this enclosing expression, which is called theyield target, then immediately completes normally and the value of theExpression becomes the value of theswitch expression.
It is a compile-time error if ayield statement has no yield target.
It is a compile-time error if the yield target contains any method, constructor, instance initializer, static initializer, or lambda expression that encloses theyield statement. That is, there are no non-local jumps.
It is a compile-time error if theExpression of ayield statement is void (§15.1).
Execution of ayield statement first evaluates theExpression. If the evaluation of theExpression completes abruptly for some reason, then theyield statement completes abruptly for that reason. If evaluation of theExpression completes normally, producing a valueV, then theyield statement completes abruptly, the reason being a yield with valueV.
It can be seen, then, that ayield statement always completes abruptly.
Example 14.21-1. Theyield Statement
In the following example, ayield statement is used to produce a value for the enclosingswitch expression.
class Test { enum Day { MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY } public int calculate(Day d) { return switch (d) { case SATURDAY, SUNDAY -> d.ordinal(); default -> { int len = d.toString().length(); yield len*len; } }; }}It is a compile-time error if a statement cannot be executed because it isunreachable.
This section is devoted to a precise explanation of the word "reachable." The idea is that there must be some possible execution path from the beginning of the constructor, method, instance initializer, or static initializer that contains the statement to the statement itself. The analysis takes into account the structure of statements. Except for the special treatment ofwhile,do, andfor statements whose condition expression has the constant valuetrue, the values of expressions are not taken into account in the flow analysis.
For example, a Java compiler will accept the code:
{ int n = 5; while (n > 7) k = 2;}even though the value ofn is known at compile time and in principle it can be known at compile time that the assignment tok can never be executed.
The rules in this section define two technical terms:
The rules allow a statement to complete normally only if it is reachable.
Two further technical terms are used:
A reachablebreak statementexits a statement if, within the break target, either there are notry statements whosetry blocks contain thebreak statement, or there aretry statements whosetry blocks contain thebreak statement and allfinally clauses of thosetry statements can complete normally.
This definition is based on the logic around "attempts to transfer control" in§14.15.
Acontinue statementcontinues ado statement if, within thedo statement, either there are notry statements whosetry blocks contain thecontinue statement, or there aretry statements whosetry blocks contain thecontinue statement and allfinally clauses of thosetry statements can complete normally.
The block that is the body of a constructor, method, instance initializer, static initializer, lambda expression, orswitch expression is reachable.
An empty block that is not a switch block can complete normally iff it is reachable.
A non-empty block that is not a switch block can complete normally iff the last statement in it can complete normally.
The first statement in a non-empty block that is not a switch block is reachable iff the block is reachable.
Every other statementS in a non-empty block that is not a switch block is reachable iff the statement precedingS can complete normally.
A local class declaration statement can complete normally iff it is reachable.
A local variable declaration statement can complete normally iff it is reachable.
An empty statement can complete normally iff it is reachable.
A labeled statement can complete normally if at least one of the following is true:
The contained statement is reachable iff the labeled statement is reachable.
An expression statement can complete normally iff it is reachable.
Anif-then statement can complete normally iff it is reachable.
Thethen-statement is reachable iff theif-then statement is reachable.
Anif-then-else statement can complete normally iff thethen-statement can complete normally or theelse-statement can complete normally.
Thethen-statement is reachable iff theif-then-else statement is reachable.
Theelse-statement is reachable iff theif-then-else statement is reachable.
This handling of anif statement, whether or not it has anelse part, is rather unusual. The rationale is given at the end of this section.
Anassert statement can complete normally iff it is reachable.
Aswitch statement whose switch block is empty, or contains only switch labels, can complete normally.
Aswitch statementwhose switch block consists of switch labeled statement groups can complete normally iff at least one of the following is true:
Aswitch statementwhose switch block consists of switch rules can complete normally iff at least one of the following is true:
One of the switch rules introduces a switch rule expression (which is necessarily a statement expression).
One of the switch rules introduces a switch rule block that can complete normally.
One of the switch rules introduces a switch rule block that contains a reachablebreak statement which exits theswitch statement.
A switch block is reachable iff itsswitch statement is reachable.
A statement in a switch blockthat consists of switch labeled statement groups is reachable iff the switch block is reachable and at least one of the following is true:
A switch rule block in a switch block is reachable iff the switch block is reachable.
A switch rulethrow statement in a switch block is reachable iff the switch block is reachable.
Awhile statement can complete normally iff at least one of the following is true:
Thewhile statement is reachable and the condition expression is not a constant expression (§15.29) with valuetrue.
There is a reachablebreak statement that exits thewhile statement.
The contained statement is reachable iff thewhile statement is reachable and the condition expression is not a constant expression whose value isfalse.
Ado statement can complete normally iff at least one of the following is true:
The containedstatement can complete normally and the condition expression is not a constant expression (§15.29) with valuetrue.
Thedo statement contains a reachablecontinue statement with no label, and thedo statement is the innermostwhile,do, orfor statement that contains thatcontinue statement, and thecontinue statement continues thatdo statement, and the condition expression is not a constant expression with valuetrue.
Thedo statement contains a reachablecontinue statement with labelL, and thedo statement has labelL, and thecontinue statement continues thatdo statement, and the condition expression is not a constant expression with valuetrue.
There is a reachablebreak statement that exits thedo statement.
The contained statement is reachable iff thedo statement is reachable.
A basicfor statement can complete normally iff at least one of the following is true:
Thefor statement is reachable, there is a condition expression, and the condition expression is not a constant expression (§15.29) with valuetrue.
There is a reachablebreak statement that exits theforstatement.
The contained statement is reachable iff thefor statement is reachable and the condition expression is not a constant expression whose value isfalse.
An enhancedfor statement can complete normally iff it is reachable.
Abreak,continue,return,throw, oryield statement cannot complete normally.
Asynchronized statement can complete normally iff the contained statement can complete normally.
The contained statement is reachable iff thesynchronized statement is reachable.
Atry statement can complete normally iff both of the following are true:
Thetry block is reachable iff thetry statement is reachable.
Acatch blockC is reachable iff both of the following are true:
Either the type ofC's parameter is an unchecked exception type orException or a superclass ofException, or some expression orthrow statement in thetry block is reachable and can throw a checked exception whose type is assignment compatible (§5.2) with the type ofC's parameter. (An expression is reachable iff the innermost statement containing it is reachable.)
See§15.6 for normal and abrupt completion of expressions.
There is no earliercatch blockA in thetry statement such that the type ofC's parameter is the same as, or a subclass of, the type ofA's parameter.
TheBlock of acatch block is reachable iff thecatch block is reachable.
If afinally block is present, it is reachable iff thetry statement is reachable.
Onemight expect theif statement to be handled in the following manner:
Anif-then statement can complete normally iff at least one of the following is true:
Theif-then statement is reachable and the condition expression is not a constant expression whose value istrue.
Thethen-statement can complete normally.
Thethen-statement is reachable iff theif-then statement is reachable and the condition expression is not a constant expression whose value isfalse.
Anif-then-else statement can complete normally iff thethen-statement can complete normally or theelse-statement can complete normally.
Thethen-statement is reachable iff theif-then-else statement is reachable and the condition expression is not a constant expression whose value isfalse.
Theelse-statement is reachable iff theif-then-else statement is reachable and the condition expression is not a constant expression whose value istrue.
This approach would be consistent with the treatment of other control structures. However, in order to allow theif statement to be used conveniently for "conditional compilation" purposes, the actual rules differ.
As an example, the following statement results in a compile-time error:
while (false) { x=3; }because the statementx=3; is not reachable; but the superficially similar case:
if (false) { x=3; }does not result in a compile-time error. An optimizing compiler may realize that the statementx=3; will never be executed and may choose to omit the code for that statement from the generatedclass file, but the statementx=3; is not regarded as "unreachable" in the technical sense specified here.
The rationale for this differing treatment is to allow programmers to define "flag" variables such as:
static final boolean DEBUG = false;
and then write code such as:
if (DEBUG) { x=3; }The idea is that it should be possible to change the value ofDEBUG fromfalse totrue or fromtrue tofalse and then compile the code correctly with no other changes to the program text.
Conditional compilation comes with a caveat. If a set of classes that use a "flag" variable - or more precisely, anystatic constant variable (§4.12.4) - are compiled and conditional code is omitted, it does not suffice later to distribute just a new version of the class or interface that contains the definition of the flag. The classes that use the flag will not see its new value, so their behavior may be surprising. In essence, a change to the value of a flag is binary compatible with pre-existing binaries (noLinkageError occurs) but not behaviorally compatible.
Another reason for "inlining" values ofstatic constant variables is because ofswitch statements. They are the only kind of statement that relies on constant expressions, namely that eachcase label of aswitch statement must be a constant expression whose value is different than every othercase label.case labels are often references tostatic constant variables so it may not be immediately obvious that all the labels have different values. If it is proven that there are no duplicate labels at compile time, then inlining the values into theclass file ensures there are no duplicate labels at run time either - a very desirable property.
Example 14.22-1. Conditional Compilation
If the example:
class Flags { static final boolean DEBUG = true; }class Test { public static void main(String[] args) { if (Flags.DEBUG) System.out.println("DEBUG is true"); }}is compiled and executed, it produces the output:
DEBUG is true
Suppose that a new version of classFlags is produced:
class Flags { static final boolean DEBUG = false; }IfFlags is recompiled but notTest, then running the new binary with the existing binary ofTest produces the output:
DEBUG is true
becauseDEBUG is astatic constant variable, so its value could have been used in compilingTest without making a reference to the classFlags.
This behavior would also occur ifFlags was an interface, as in the modified example:
interface Flags { boolean DEBUG = true; }class Test { public static void main(String[] args) { if (Flags.DEBUG) System.out.println("DEBUG is true"); }}In fact, because the fields of interfaces are alwaysstatic andfinal, we recommend that only constant expressions be assigned to fields of interfaces. We note, but do not recommend, that if a field of primitive type of an interface may change, its value may be expressed idiomatically as in:
interface Flags { boolean debug = Boolean.valueOf(true).booleanValue();}ensuring that this value is not a constant expression. Similar idioms exist for the other primitive types.
Apattern describes a test that can be performed on a value. Patterns appear as operands of statements and expressions, which provide the values to be tested. Patterns declare local variables, known aspattern variables.
The process of testing a value against a pattern is known aspattern matching. If a value successfully matches a pattern, then the process of pattern matching initializes the pattern variable declared by the pattern.
Pattern variables are only in scope (§6.3) where pattern matching succeeds and thus the pattern variables will have been initialized. It is not possible to use a pattern variable that has not been initialized.
Atype pattern is used to test whether a value is an instance of the type appearing in the pattern.
The following productions from§4.3,§8.3,§8.4.1, and§14.4 are shown here for convenience:
See§8.3 forUnannType.
A type pattern declares one local variable, known as a pattern variable. TheIdentifier in the local variable declaration specifies the name of the pattern variable.
The rules for a local variable declared in a type pattern are specified in§14.4. In addition, all of the following must be true, or a compile-time error occurs:
The type of a pattern variable is the reference type denoted byLocalVariableType.
The type of a type pattern is the type of its pattern variable.
An expressione iscompatible with a pattern of typeT ife is downcast compatible withT (§5.5).
Compatibility of an expression with a pattern is used by theinstanceof pattern match operator (§15.20.2).
Pattern matching is the process of testing a value against a pattern at run time. Pattern matching is distinct from statement execution (§14.1) and expression evaluation (§15.1).
The rules for determining whether a value matches a pattern, and for initializing pattern variables, are as follows:
A valuev that is not the null referencematches a type pattern of typeT ifv can be cast toT without raising aClassCastException; anddoes not match otherwise.
Ifv matches, then the pattern variable declared by the type pattern is initialized tov.
Ifv does not match, then the pattern variable declared by the type pattern is not initialized.
There is no rule to cover a value thatis the null reference. This is because the solitary construct that performs pattern matching, theinstanceof pattern match operator (§15.20.2), only does so when a value isnot the null reference. It is possible that future versions of the Java programming language will allow pattern matching in other expressions and statements.