Pattern matching for instanceof (Preview)

This document describes changes to the Java Language Specification to support pattern matching in instanceof expressions. See JEP 305.

Changes are described with respect to existing sections of the JLS. New text is indicated like this and deleted text is indicated like this. Explanation and discussion, as needed, is set aside in grey boxes.

Chapter 4: Types, Values, and Variables

4.12 Variables

4.12.3 Kinds of Variables

There are eight nine kinds of variables:

1. A class variable is a field declared using the keyword static within a class declaration (8.3.1.1), or with or without the keyword static within an interface declaration (9.3).

   A class variable is created when its class or interface is prepared (12.3.2) and is initialized to a default value (4.12.5). The class variable effectively ceases to exist when its class or interface is unloaded (12.7).

2. An instance variable is a field declared within a class declaration without using the keyword static (8.3.1.1).

   If a class T has a field a that is an instance variable, then a new instance variable a is created and initialized to a default value (4.12.5) as part of each newly created object of class T or of any class that is a subclass of T (8.1.4). The instance variable effectively ceases to exist when the object of which it is a field is no longer referenced, after any necessary finalization of the object (12.6) has been completed.

3. Array components are unnamed variables that are created and initialized to default values (4.12.5) whenever a new object that is an array is created (10, 15.10.2). The array components effectively cease to exist when the array is no longer referenced.

4. Method parameters (8.4.1) name argument values passed to a method.

   For every parameter declared in a method declaration, a new parameter variable is created each time that method is invoked (15.12). The new variable is initialized with the corresponding argument value from the method invocation. The method parameter effectively ceases to exist when the execution of the body of the method is complete.

5. Constructor parameters (8.8.1) name argument values passed to a constructor.

   For every parameter declared in a constructor declaration, a new parameter variable is created each time a class instance creation expression (15.9) or explicit constructor invocation (8.8.7) invokes that constructor. The new variable is initialized with the corresponding argument value from the creation expression or constructor invocation. The constructor parameter effectively ceases to exist when the execution of the body of the constructor is complete.

6. Lambda parameters (15.27.1) name argument values passed to a lambda expression body (15.27.2).

   For every parameter declared in a lambda expression, a new parameter variable is created each time a method implemented by the lambda body is invoked (15.12). The new variable is initialized with the corresponding argument value from the method invocation. The lambda parameter effectively ceases to exist when the execution of the lambda expression body is complete.

7. An exception parameter is created each time an exception is caught by a catch clause of a try statement (14.20).

   The new variable is initialized with the actual object associated with the exception (11.3, 14.18). The exception parameter effectively ceases to exist when execution of the block associated with the catch clause is complete.

8. Local variables are declared by local variable declaration statements (14.4).

   Whenever the flow of control enters a block (14.2) or for statement (14.14), a new variable is created for each local variable declared in a local variable declaration statement immediately contained within that block or for statement.

   A local variable declaration statement may contain an expression which initializes the variable. The local variable with an initializing expression is not initialized, however, until the local variable declaration statement that declares it is executed. (The rules of definite assignment (16)(17) prevent the value of a local variable from being used before it has been initialized or otherwise assigned a value.) The local variable effectively ceases to exist when the execution of the block or for statement is complete.

   Were it not for one exceptional situation, a local variable could always be regarded as being created when its local variable declaration statement is executed. The exceptional situation involves the switch statement (14.11), where it is possible for control to enter a block but bypass execution of a local variable declaration statement. Because of the restrictions imposed by the rules of definite assignment (16)(17), however, the local variable declared by such a bypassed local variable declaration statement cannot be used before it has been definitely assigned a value by an assignment expression (15.26).

class Point {
    static int numPoints;          // numPoints is a class variable
    int x, y;                      // x and y are instance variables
    int[] w = new int[10];         // w[0] is an array component
    int setX(int x) {              // x is a method parameter
        int oldx = this.x;         // oldx is a local variable
        this.x = x;
        return oldx;
    }
    boolean equalAtX(Object o) {
        if (o instanceof Point p)  // p is a pattern variable 
            return this.x == p.x;
        else
            return false;
    }
}

4.12.4 final Variables

A variable can be declared final. A final variable may only be assigned to once. It is a compile-time error if a final variable is assigned to unless it is definitely unassigned immediately prior to the assignment ([1617]).

Once a final variable has been assigned, it always contains the same value. If a final variable holds a reference to an object, then the state of the object may be changed by operations on the object, but the variable will always refer to the same object. This applies also to arrays, because arrays are objects; if a final variable holds a reference to an array, then the components of the array may be changed by operations on the array, but the variable will always refer to the same array.

A blank final is a final variable whose declaration lacks an initializer.

A constant variable is a final variable of primitive type or type String that is initialized with a constant expression (15.28). Whether a variable is a constant variable or not may have implications with respect to class initialization (12.4.1), binary compatibility (13.1), reachability (14.21), and definite assignment ([16.1.117.1.1]).

Three Four kinds of variable are implicitly declared final: a field of an interface (9.3), a local variable declared as a resource of a try-with-resources statement (14.20.3), and an exception parameter of a multi-catch clause (14.20), and a pattern variable (16.1). An exception parameter of a uni-catch clause is never implicitly declared final, but may be effectively final.

class Point {
    int x, y;
    int useCount;
    Point(int x, int y) { this.x = x; this.y = y; }
    static final Point origin = new Point(0, 0);
}

Certain variables that are not declared final are instead considered effectively final:

• A local variable whose declarator has an initializer (14.4.2) is effectively final if all of the following are true:

  • It is not declared final.

  • It never occurs as the left hand side in an assignment expression (15.26). (Note that the local variable declarator containing the initializer is not an assignment expression.)

  • It never occurs as the operand of a prefix or postfix increment or decrement operator (15.14, 15.15).

• A local variable whose declarator lacks an initializer is effectively final if all of the following are true:

  • It is not declared final.

  • Whenever it occurs as the left hand side in an assignment expression, it is definitely unassigned and not definitely assigned before the assignment; that is, it is definitely unassigned and not definitely assigned after the right hand side of the assignment expression ( [1617]).

  • It never occurs as the operand of a prefix or postfix increment or decrement operator.

• A method, constructor, lambda, or exception parameter (8.4.1, 8.8.1, 9.4, 15.27.1, 14.20) is treated, for the purpose of determining whether it is effectively final, as a local variable whose declarator has an initializer.

If a variable is effectively final, adding the final modifier to its declaration will not introduce any compile-time errors. Conversely, a local variable or parameter that is declared final in a valid program becomes effectively final if the final modifier is removed.

4.12.5 Initial Values of Variables

Every variable in a program must have a value before its value is used:

• Each class variable, instance variable, or array component is initialized with a default value when it is created (15.9, 15.10.2):

  • For type byte, the default value is zero, that is, the value of (byte)0.

  • For type short, the default value is zero, that is, the value of (short)0.

  • For type int, the default value is zero, that is, 0.

  • For type long, the default value is zero, that is, 0L.

  • For type float, the default value is positive zero, that is, 0.0f.

  • For type double, the default value is positive zero, that is, 0.0d.

  • For type char, the default value is the null character, that is, '\u0000'.

  • For type boolean, the default value is false.

  • For all reference types (4.3), the default value is null.

• Each method parameter (8.4.1) is initialized to the corresponding argument value provided by the invoker of the method (15.12).

• Each constructor parameter (8.8.1) is initialized to the corresponding argument value provided by a class instance creation expression (15.9) or explicit constructor invocation (8.8.7).

• Each pattern variable (16.1) is assigned a value after the pattern matching process has succeeded (16.3).

• An exception parameter (14.20) is initialized to the thrown object representing the exception (11.3, 14.18).

• A local variable (14.4, 14.14) must be explicitly given a value before it is used, by either initialization (14.4) or assignment (15.26), in a way that can be verified using the rules for definite assignment (16).

class Point {
    static int npoints;
    int x, y;
    Point root;
}

class Test {
    public static void main(String[] args) {
        System.out.println("npoints=" + Point.npoints);
        Point p = new Point();
        System.out.println("p.x=" + p.x + ", p.y=" + p.y);
        System.out.println("p.root=" + p.root);
    }
}

npoints=0
p.x=0, p.y=0
p.root=null

Chapter 6: Names

6.1 Declarations

A declaration introduces an entity into a program and includes an identifier (3.8) that can be used in a name to refer to this entity. The identifier is constrained to be a type identifier when the entity being introduced is a class, interface, or type parameter.

A declared entity is one of the following:

• A module, declared in a module declaration (7.7)

• A package, declared in a package declaration (7.4)

• An imported type, declared in a single-type-import declaration or a type-import-on-demand declaration (7.5.1, 7.5.2)

• An imported static member, declared in a single-static-import declaration or a static-import-on-demand declaration (7.5.3, 7.5.4)

• A class, declared in a class type declaration (8.1)

• An interface, declared in an interface type declaration (9.1)

• A type parameter, declared as part of the declaration of a generic class, interface, method, or constructor (8.1.2, 9.1.2, 8.4.4, 8.8.4)

• A member of a reference type (8.2, 9.2, 8.9.3, 9.6, 10.7), one of the following:

  • A member class (8.5, 9.5)

  • A member interface (8.5, 9.5)

  • An enum constant (8.9)

  • A field, one of the following:

    • A field declared in a class type or enum type (8.3, 8.9.2)

    • A field declared in an interface type or annotation type (9.3, 9.6.1)

    • The field length, which is implicitly a member of every array type (10.7)

  • A method, one of the following:

    • A method (abstract or otherwise) declared in a class type or enum type (8.4, 8.9.2)

    • A method (abstract or otherwise) declared in an interface type or annotation type (9.4, 9.6.1)

• A parameter, one of the following:

  • A formal parameter of a method or constructor of a class type or enum type (8.4.1, 8.8.1, 8.9.2), or of a lambda expression (15.27.1)

  • A formal parameter of an abstract method of an interface type or annotation type (9.4, 9.6.1)

  • An exception parameter of an exception handler declared in a catch clause of a try statement (14.20)

• A local variable, one of the following:

  • A local variable declared in a block (14.4)

  • A local variable declared in a for statement (14.14)

• A pattern variable, declared in a pattern (16).

Constructors (8.8) are also introduced by declarations, but use the name of the class in which they are declared rather than introducing a new name.

The declaration of a type which is not generic (class C ...) declares one entity: a non-generic type (C). A non-generic type is not a raw type, despite the syntactic similarity. In contrast, the declaration of a generic type (class C<T> ... or interface C<T> ...) declares two entities: a generic type (C<T>) and a corresponding non-generic type (C). In this case, the meaning of the term C depends on the context where it appears:

• If genericity is unimportant, as in the non-generic contexts identified below, the identifier C denotes the non-generic type C.

• If genericity is important, as in all contexts from 6.5 except the non-generic contexts, the identifier C denotes either:

  • The raw type C which is the erasure (4.6) of the generic type C<T>; or

  • A parameterized type which is a particular parameterization (4.5) of the generic type C<T>.

The 14 non-generic contexts are as follows:

1. In a uses or provides directive in a module declaration (7.7.1)

2. In a single-type-import declaration (7.5.1)

3. To the left of the . in a single-static-import declaration (7.5.3)

4. To the left of the . in a static-import-on-demand declaration (7.5.4)

5. To the left of the ( in a constructor declaration (8.8)

6. After the @ sign in an annotation (9.7)

7. To the left of .class in a class literal (15.8.2)

8. To the left of .this in a qualified this expression (15.8.4)

9. To the left of .super in a qualified superclass field access expression (15.11.2)

10. To the left of .Identifier or .super.Identifier in a qualified method invocation expression (15.12)

11. To the left of .super:: in a method reference expression (15.13)

12. In a qualified expression name in a postfix expression or a try-with-resources statement (15.14.1, 14.20.3)

13. In a throws clause of a method or constructor (8.4.6, 8.8.5, 9.4)

14. In an exception parameter declaration (14.20)

The first eleven non-generic contexts correspond to the first eleven syntactic contexts for a TypeName in 6.5.1. The twelfth non-generic context is where a qualified ExpressionName such as C.x may include a TypeName C to denote static member access. The common use of TypeName in these twelve contexts is significant: it indicates that these contexts involve a less-than-first-class use of a type. In contrast, the thirteenth and fourteenth non-generic contexts employ ClassType, indicating that throws and catch clauses use types in a first-class way, in line with, say, field declarations. The characterization of these two contexts as non-generic is due to the fact that an exception type cannot be parameterized.

Note that the ClassType production allows annotations, so it is possible to annotate the use of a type in a throws or catch clause, whereas the TypeName production disallows annotations, so it is not possible to annotate the name of a type in, say, a single-type-import declaration.

Naming Conventions

The class libraries of the Java SE Platform attempt to use, whenever possible, names chosen according to the conventions presented below. These conventions help to make code more readable and avoid certain kinds of name conflicts.

We recommend these conventions for use in all programs written in the Java programming language. However, these conventions should not be followed slavishly if long-held conventional usage dictates otherwise. So, for example, the sin and cos methods of the class java.lang.Math have mathematically conventional names, even though these method names flout the convention suggested here because they are short and are not verbs.

Package Names and Module Names

Developers should take steps to avoid the possibility of two published packages having the same name by choosing unique package names for packages that are widely distributed. This allows packages to be easily and automatically installed and catalogued. This section specifies a suggested convention for generating such unique package names. Implementations of the Java SE Platform are encouraged to provide automatic support for converting a set of packages from local and casual package names to the unique name format described here.

If unique package names are not used, then package name conflicts may arise far from the point of creation of either of the conflicting packages. This may create a situation that is difficult or impossible for the user or programmer to resolve. The classes ClassLoader and ModuleLayer can be used to isolate packages with the same name from each other in those cases where the packages will have constrained interactions, but not in a way that is transparent to a naïve program.

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as oracle.com. You then reverse this name, component by component, to obtain, in this example, com.oracle, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names. Such a convention might specify that certain package name components be division, department, project, machine, or login names.

com.nighthacks.scrabble.dictionary
org.openjdk.compiler.source.tree
net.jcip.annotations
edu.cmu.cs.bovik.cheese
gov.whitehouse.socks.mousefinder

The first component of a unique package name is always written in all-lowercase ASCII letters and should be one of the top level domain names, such as com, edu, gov, mil, net, or org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166.

In some cases, the Internet domain name may not be a valid package name. Here are some suggested conventions for dealing with these situations:

• If the domain name contains a hyphen, or any other special character not allowed in an identifier (3.8), convert it into an underscore.

• If any of the resulting package name components are keywords (3.9), append an underscore to them.

• If any of the resulting package name components start with a digit, or any other character that is not allowed as an initial character of an identifier, have an underscore prefixed to the component.

The name of a module should correspond to the name of its principal exported package. If a module does not have such a package, or if for legacy reasons it must have a name that does not correspond to one of its exported packages, then its name should still start with the reversed form of an Internet domain with which its author is associated.

com.nighthacks.scrabble
org.openjdk.compiler
net.jcip.annotations

The first component of a package or module name must not be the identifier java. Package and module names that start with the identifier java are reserved for packages and modules of the Java SE Platform.

The name of a package or module is not meant to imply where the package or module is stored on the Internet. For example, a package named edu.cmu.cs.bovik.cheese is not necessarily obtainable from the host cmu.edu or cs.cmu.edu or bovik.cs.cmu.edu. The suggested convention for generating unique package and module names is merely a way to piggyback a package and module naming convention on top of an existing, widely known unique name registry instead of having to create a separate registry for package and module names.

Class and Interface Type Names

Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed case with the first letter of each word capitalized.

`ClassLoader`
SecurityManager
`Thread`
Dictionary
BufferedInputStream

Likewise, names of interface types should be short and descriptive, not overly long, in mixed case with the first letter of each word capitalized. The name may be a descriptive noun or noun phrase, which is appropriate when an interface is used as if it were an abstract superclass, such as interfaces java.io.DataInput and java.io.DataOutput; or it may be an adjective describing a behavior, as for the interfaces Runnable and Cloneable.

Type Variable Names

Type variable names should be pithy (single character if possible) yet evocative, and should not include lower case letters. This makes it easy to distinguish type parameters from ordinary classes and interfaces.

Container types should use the name E for their element type. Maps should use K for the type of their keys and V for the type of their values. The name X should be used for arbitrary exception types. We use T for type, whenever there is not anything more specific about the type to distinguish it. (This is often the case in generic methods.)

If there are multiple type parameters that denote arbitrary types, one should use letters that neighbor T in the alphabet, such as S. Alternately, it is acceptable to use numeric subscripts (e.g., T1, T2) to distinguish among the different type variables. In such cases, all the variables with the same prefix should be subscripted.

If a generic method appears inside a generic class, it is a good idea to avoid using the same names for the type parameters of the method and class, to avoid confusion. The same applies to nested generic classes.

public class HashSet<E> extends AbstractSet<E> { ... }
public class HashMap<K,V> extends AbstractMap<K,V> { ... }
public class ThreadLocal<T> { ... }
public interface Functor<T, X extends Throwable> {
    T eval() throws X;
}

When type parameters do not fall conveniently into one of the categories mentioned, names should be chosen to be as meaningful as possible within the confines of a single letter. The names mentioned above (E, K, V, X, T) should not be used for type parameters that do not fall into the designated categories.

Method Names

Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase and the first letter of any subsequent words capitalized. Here are some additional specific conventions for method names:

• Methods to get and set an attribute that might be thought of as a variable V should be named get*V* and set*V*. An example is the methods getPriority and setPriority of class Thread.

• A method that returns the length of something should be named length, as in class String.

• A method that tests a boolean condition V about an object should be named is*V*. An example is the method isInterrupted of class Thread.

• A method that converts its object to a particular format F should be named to*F*. Examples are the method toString of class Object and the methods toLocaleString and toGMTString of class java.util.Date.

Whenever possible and appropriate, basing the names of methods in a new class on names in an existing class that is similar, especially a class from the Java SE Platform API, will make it easier to use.

Field Names

Names of fields that are not final should be in mixed case with a lowercase first letter and the first letters of subsequent words capitalized. Note that well-designed classes have very few public or protected fields, except for fields that are constants (static final fields).

Fields should have names that are nouns, noun phrases, or abbreviations for nouns.

Examples of this convention are the fields buf, pos, and count of the class java.io.ByteArrayInputStream and the field bytesTransferred of the class java.io.InterruptedIOException.

Constant Names

The names of constants in interface types should be, and final variables of class types may conventionally be, a sequence of one or more words, acronyms, or abbreviations, all uppercase, with components separated by underscore "_" characters. Constant names should be descriptive and not unnecessarily abbreviated. Conventionally they may be any appropriate part of speech.

Examples of names for constants include MIN_VALUE, MAX_VALUE, MIN_RADIX, and MAX_RADIX of the class Character.

A group of constants that represent alternative values of a set, or, less frequently, masking bits in an integer value, are sometimes usefully specified with a common acronym as a name prefix.

For example:

interface ProcessStates {
    int PS_RUNNING   = 0;
    int PS_SUSPENDED = 1;
}

Local Variable and Parameter Names

Local variable and parameter names should be short, yet meaningful. They are often short sequences of lowercase letters that are not words, such as:

• Acronyms, that is the first letter of a series of words, as in cp for a variable holding a reference to a ColoredPoint

• Abbreviations, as in buf holding a pointer to a buffer of some kind

• Mnemonic terms, organized in some way to aid memory and understanding, typically by using a set of local variables with conventional names patterned after the names of parameters to widely used classes. For example:

  • in and out, whenever some kind of input and output are involved, patterned after the fields of System

  • off and len, whenever an offset and length are involved, patterned after the parameters to the read and write methods of the interfaces DataInput and DataOutput of java.io

One-character local variable or parameter names should be avoided, except for temporary and looping variables, or where a variable holds an undistinguished value of a type. Conventional one-character names are:

• b for a byte
• c for a char
• d for a double
• e for an Exception
• f for a float
• i, j, and k for ints
• l for a long
• o for an Object
• s for a String
• v for an arbitrary value of some type

Local variable or parameter names that consist of only two or three lowercase letters should not conflict with the initial country codes and domain names that are the first component of unique package names.

6.3 Scope of a Declaration

The scope of a declaration is the region of the program within which the entity declared by the declaration can be referred to using a simple name, provided it is not shadowed (6.4.1).

A declaration is said to be in scope at a particular point in a program if and only if the declaration's scope includes that point.

The scope of the declaration of an observable top level package (7.4.3) is all observable compilation units associated with modules to which the package is uniquely visible (7.4.3).

The declaration of a package that is not observable is never in scope.

The declaration of a subpackage is never in scope.

The package java is always in scope.

The scope of a type imported by a single-type-import declaration (7.5.1) or a type-import-on-demand declaration (7.5.2) is the module declaration (7.7) and all the class and interface type declarations (7.6) of the compilation unit in which the import declaration appears, as well as any annotations on the module declaration or package declaration of the compilation unit.

The scope of a member imported by a single-static-import declaration (7.5.3) or a static-import-on-demand declaration (7.5.4) is the module declaration and all the class and interface type declarations of the compilation unit in which the import declaration appears, as well as any annotations on the module declaration or package declaration of the compilation unit.

The scope of a top level type (7.6) is all type declarations in the package in which the top level type is declared.

The scope of a declaration of a member m declared in or inherited by a class type C (8.1.6) is the entire body of C, including any nested type declarations.

The scope of a declaration of a member m declared in or inherited by an interface type I (9.1.4) is the entire body of I, including any nested type declarations.

The scope of an enum constant C declared in an enum type T is the body of T, and any case label of a switch statement whose expression is of enum type T (14.11).

The scope of a formal parameter of a method (8.4.1), constructor (8.8.1), or lambda expression (15.27) is the entire body of the method, constructor, or lambda expression.

The scope of a class's type parameter (8.1.2) is the type parameter section of the class declaration, the type parameter section of any superclass or superinterface of the class declaration, and the class body.

The scope of an interface's type parameter (9.1.2) is the type parameter section of the interface declaration, the type parameter section of any superinterface of the interface declaration, and the interface body.

The scope of a method's type parameter (8.4.4) is the entire declaration of the method, including the type parameter section, but excluding the method modifiers.

The scope of a constructor's type parameter (8.8.4) is the entire declaration of the constructor, including the type parameter section, but excluding the constructor modifiers.

The scope of a local class declaration immediately enclosed by a block (14.2) is the rest of the immediately enclosing block, including its own class declaration.

The scope of a local class declaration immediately enclosed by a switch block statement group (14.11) is the rest of the immediately enclosing switch block statement group, including its own class declaration.

The scope of a local variable declaration in a block (14.4) is the rest of the block in which the declaration appears, starting with its own initializer and including any further declarators to the right in the local variable declaration statement.

The scope of a local variable declared in the ForInit part of a basic for statement (14.14.1) includes all of the following:

• Its own initializer

• Any further declarators to the right in the ForInit part of the for statement

• The Expression and ForUpdate parts of the for statement

• The contained Statement

The scope of a local variable declared in the FormalParameter part of an enhanced for statement (14.14.2) is the contained Statement.

The scope of a parameter of an exception handler that is declared in a catch clause of a try statement (14.20) is the entire block associated with the catch.

The scope of a variable declared in the ResourceSpecification of a try-with-resources statement (14.20.3) is from the declaration rightward over the remainder of the ResourceSpecification and the entire try block associated with the try-with-resources statement.

The translation of a try-with-resources statement implies the rule above.

package points;
class Point {
    int x, y;
    PointList list;
    Point next;
}

class PointList {
    Point first;
}

class Test1 {
    static int x;
    public static void main(String[] args) {
        int x = x;
    }
}

class Test2 {
    static int x;
    public static void main(String[] args) {
        int x = (x=2)*2;
        System.out.println(x);
    }
}

4

class Test3 {
    public static void main(String[] args) {
        System.out.print("2+1=");
        int two = 2, three = two + 1;
        System.out.println(three);
    }
}

2+1=3

6.3.1 Pattern Declaration Scopes and Expressions

6.3.1.1 Conditional-And Operator &&

6.3.1.2 Conditional-Or Operator ||

6.3.1.3 Logical Complement Operator !

6.3.1.4 Conditional Operator ? :

6.3.1.5 instanceof Operator

6.3.2 Pattern Declaration Scopes and Statements

if (x instance String s) {
    // String s in scope for this block
    // No explicit cast needed here!
    ...
    System.out.println("The string value was: " + s); 
} else {
    // String s not in scope here
    System.out.println(s); // Compile-time error!
}

public void RequiresAString(Object o) {
    if (!(o instanceof String s)) {
        throw new IllegalArgumentException();
    }
    // Only reachable if the pattern match succeeded
    // String s is thus in scope for the rest of the block
    System.out.println("The parameter string was: " + s); 
    ...
}

6.3.2.1 Blocks

6.3.2.2 if Statements

6.3.2.3 while Statements

6.3.2.4 do Statements

6.3.2.5 for Statements

6.3.2.6 switch Statements

6.4 Shadowing and Obscuring

A local variable (14.4), formal parameter (8.4.1, 15.27.1), exception parameter (14.20), and local class (14.3), and pattern variable (16) can only be referred to using a simple name, not a qualified name (6.2).

Some declarations are not permitted within the scope of a local variable, pattern variable, formal parameter, exception parameter, or local class declaration because it would be impossible to distinguish between the declared entities using only simple names.

For example, if the name of a formal parameter of a method could be redeclared as the name of a local variable in the method body, then the local variable would shadow the formal parameter and there would be no way to refer to the formal parameter - an undesirable outcome.

It is a compile-time error if the name of a formal parameter is used to declare a new variable within the body of the method, constructor, or lambda expression, unless the new variable is declared within a class declaration contained by the method, constructor, or lambda expression.

It is a compile-time error if the name of a local variable v is used to declare a new variable within the scope of v, unless the new variable is declared within a class whose declaration is within the scope of v.

It is a compile-time error if the name of an exception parameter is used to declare a new variable within the Block of the catch clause, unless the new variable is declared within a class declaration contained by the Block of the catch clause.

It is a compile-time error if the name of a local class C is used to declare a new local class within the scope of C, unless the new local class is declared within another class whose declaration is within the scope of C.

These rules allow redeclaration of a variable or local class in nested class declarations that occur in the scope of the variable or local class; such nested class declarations may be local classes (14.3) or anonymous classes (15.9). Thus, the declaration of a formal parameter, local variable, pattern variable, or local class may be shadowed in a class declaration nested within a method, constructor, or lambda expression; and the declaration of an exception parameter may be shadowed in a class declaration nested within the Block of the catch clause.

There are two design alternatives for handling name clashes created by lambda parameters and other variables declared in lambda expressions. One is to mimic class declarations: like local classes, lambda expressions introduce a new "level" for names, and all variable names outside the expression can be redeclared. Another is a "local" strategy: like catch clauses, for loops, and blocks, lambda expressions operate at the same "level" as the enclosing context, and local variables outside the expression cannot be shadowed. The above rules use the local strategy; there is no special dispensation that allows a variable declared in a lambda expression to shadow a variable declared in an enclosing method.

Note that the rule for local classes does not make an exception for a class of the same name declared within the local class itself. However, this case is prohibited by a separate rule: a class cannot have the same name as a class that encloses it (8.1).

class Test1 {
    public static void main(String[] args) {
        int i;
        for (int i = 0; i < 10; i++)
            System.out.println(i);
    }
}

class Test2 {
    public static void main(String[] args) {
        int i;
        class Local {
            {
                for (int i = 0; i < 10; i++)
                    System.out.println(i);
            }
        }
        new Local();
    }
}

class Test3 {
    public static void main(String[] args) {
        for (int i = 0; i < 10; i++)
            System.out.print(i + " ");
        for (int i = 10; i > 0; i--)
            System.out.print(i + " ");
        System.out.println();
    }
}

0 1 2 3 4 5 6 7 8 9 10 9 8 7 6 5 4 3 2 1

class Test4 {
    class Point {
        int x, y;
    }
    public static void test(Object a, Object b, Object c) {
        if (a instanceof Point p) {
            System.out.print("a is a point (" + p.x + ", " + p.y);
        }
        if (b instanceof Point p){
            System.out.print("b is a point (" + p.x + ", " + p.y);
        } else if (c instanceof Point p) {
            System.out.print("c is a point (" + p.x + ", " + p.y);
        }
        System.out.println();
    }
}

class Test5 {
    public static void test(Object a, Object b, Object c) {
        if (a instanceof Point p) {
            System.out.print("a is a point (" + p.x + ", " + p.y);
            if (b instanceof Point p){
                System.out.print("b is a point (" + p.x + ", " + p.y);
            }
        }
        System.out.println();
    }
}

class Test6 {
    class Point {
        int x, y;
        Point(int x, int y) {
            this.x = x;
            this.y = y;
        }
    }
    public static void test(Object o) {
        Point p = new Point(0,0);
        if (o instanceof Point p)
            System.out.println("I get your point");
    }
}

6.4.1 Shadowing

Some declarations may be shadowed in part of their scope by another declaration of the same name, in which case a simple name cannot be used to refer to the declared entity.

Shadowing is distinct from hiding (8.3, 8.4.8.2, 8.5, 9.3, 9.5), which applies only to members which would otherwise be inherited but are not because of a declaration in a subclass. Shadowing is also distinct from obscuring (6.4.2).

A declaration d of a type named n shadows the declarations of any other types named n that are in scope at the point where d occurs throughout the scope of d.

A declaration d of a field or formal parameter named n shadows, throughout the scope of d, the declarations of any other variables named n that are in scope at the point where d occurs.

A declaration d of a local variable, pattern variable, or exception parameter named n shadows, throughout the scope of d, (a) the declarations of any other fields named n that are in scope at the point where d occurs, and (b) the declarations of any other variables named n that are in scope at the point where d occurs but are not declared in the innermost class in which d is declared.

A declaration d of a method named n shadows the declarations of any other methods named n that are in an enclosing scope at the point where d occurs throughout the scope of d.

A package declaration never shadows any other declaration.

A type-import-on-demand declaration never causes any other declaration to be shadowed.

A static-import-on-demand declaration never causes any other declaration to be shadowed.

A single-type-import declaration d in a compilation unit c of package p that imports a type named n shadows, throughout c, the declarations of:

• any top level type named n declared in another compilation unit of p

• any type named n imported by a type-import-on-demand declaration in c

• any type named n imported by a static-import-on-demand declaration in c

A single-static-import declaration d in a compilation unit c of package p that imports a field named n shadows the declaration of any static field named n imported by a static-import-on-demand declaration in c, throughout c.

A single-static-import declaration d in a compilation unit c of package p that imports a method named n with signature s shadows the declaration of any static method named n with signature s imported by a static-import-on-demand declaration in c, throughout c.

A single-static-import declaration d in a compilation unit c of package p that imports a type named n shadows, throughout c, the declarations of:

• any static type named n imported by a static-import-on-demand declaration in c;

• any top level type (7.6) named n declared in another compilation unit (7.3) of p;

• any type named n imported by a type-import-on-demand declaration (7.5.2) in c.

class Test {
    static int x = 1;
    public static void main(String[] args) {
        int x = 0;
        System.out.print("x=" + x);
        System.out.println(", Test.x=" + Test.x);
    }
}

x=0, Test.x=1

class Pair {
    Object first, second;
    public Pair(Object first, Object second) {
        this.first = first;
        this.second = second;
    }
}

import java.util.*;
class Vector {
    int val[] = { 1 , 2 };
}

class Test {
    public static void main(String[] args) {
        Vector v = new Vector();
        System.out.println(v.val[0]);
    }
}

1

6.4.2 Obscuring

A simple name may occur in contexts where it may potentially be interpreted as the name of a variable, a type, or a package. In these situations, the rules of 6.5.2 specify that a variable will be chosen in preference to a type, and that a type will be chosen in preference to a package. Thus, it is may sometimes be impossible to refer to a type or package via its simple name, even though its declaration is in scope and not shadowed. We say that such a declaration is obscured.

Obscuring is distinct from shadowing (6.4.1) and hiding (8.3, 8.4.8.2, 8.5, 9.3, 9.5).

There is no obscuring between the name of a module and the name of a variable, type, or package; thus, modules may share names with variables, types, and packages, though it is not necessarily recommended to name a module after a package it contains.

The naming conventions of 6.1 help reduce obscuring, but if it does occur, here are some notes about what you can do to avoid it.

When package names occur in expressions:

• If a package name is obscured by a field declaration, then import declarations (7.5) can usually be used to make available the type names declared in that package.

• If a package name is obscured by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other code.

The first component of a package name is normally not easily mistaken for a type name, as a type name normally begins with a single uppercase letter. (The Java programming language does not actually rely on case distinctions to determine whether a name is a package name or a type name.)

Obscuring involving class and interface type names is rare. Names of fields, parameters, and local variables normally do not obscure type names because they conventionally begin with a lowercase letter whereas type names conventionally begin with an uppercase letter.

Method names cannot obscure or be obscured by other names (6.5.7).

Obscuring involving field names is rare; however:

• If a field name obscures a package name, then an import declaration (7.5) can usually be used to make available the type names declared in that package.

• If a field name obscures a type name, then a fully qualified name for the type can be used unless the type name denotes a local class (14.3).

• Field names cannot obscure method names.

• If a field name is shadowed by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other code.

Obscuring involving constant names is rare:

• Constant names normally have no lowercase letters, so they will not normally obscure names of packages or types, nor will they normally shadow fields, whose names typically contain at least one lowercase letter.

• Constant names cannot obscure method names, because they are distinguished syntactically.

6.5 Determining the Meaning of a Name

6.5.1 Syntactic Classification of a Name According to Context

A name is syntactically classified as a ModuleName in these contexts:

• In a requires directive in a module declaration (7.7.1)

• To the right of to in an exports or opens directive in a module declaration (7.7.2)

A name is syntactically classified as a PackageName in these contexts:

• To the right of exports or opens in a module declaration

• To the left of the "." in a qualified PackageName

A name is syntactically classified as a TypeName in these contexts:

• The first eleven non-generic contexts (6.1):

  1. In a uses or provides directive in a module declaration (7.7.1)

  2. In a single-type-import declaration (7.5.1)

  3. To the left of the . in a single-static-import declaration (7.5.3)

  4. To the left of the . in a static-import-on-demand declaration (7.5.4)

  5. To the left of the ( in a constructor declaration (8.8)

  6. After the @ sign in an annotation (9.7)

  7. To the left of .class in a class literal (15.8.2)

  8. To the left of .this in a qualified this expression (15.8.4)

  9. To the left of .super in a qualified superclass field access expression (15.11.2)

  10. To the left of .Identifier or .super.Identifier in a qualified method invocation expression (15.12)

  11. To the left of .super:: in a method reference expression (15.13)

• As the Identifier or dotted Identifier sequence that constitutes any ReferenceType (including a ReferenceType to the left of the brackets in an array type, or to the left of the < in a parameterized type, or in a non-wildcard type argument of a parameterized type, or in an extends or super clause of a wildcard type argument of a parameterized type) in the 16 contexts where types are used (4.11):

  1. In an extends or implements clause of a class declaration (8.1.4, 8.1.5, 8.5, 9.5)

  2. In an extends clause of an interface declaration (9.1.3)

  3. The return type of a method (8.4, 9.4) (including the type of an element of an annotation type (9.6.1))

  4. In the throws clause of a method or constructor (8.4.6, 8.8.5, 9.4)

  5. In an extends clause of a type parameter declaration of a generic class, interface, method, or constructor (8.1.2, 9.1.2, 8.4.4, 8.8.4)

  6. The type in a field declaration of a class or interface (8.3, 9.3)

  7. The type in a formal parameter declaration of a method, constructor, or lambda expression (8.4.1, 8.8.1, 9.4, 15.27.1)

  8. The type of the receiver parameter of a method (8.4)

  9. The type in a local variable declaration (14.4, 14.14.1, 14.14.2, 14.20.3)

  10. A type in an exception parameter declaration (14.20)

  11. In an explicit type argument list to an explicit constructor invocation statement or class instance creation expression or method invocation expression (8.8.7.1, 15.9, 15.12)

  12. In an unqualified class instance creation expression, either as the class type to be instantiated (15.9) or as the direct superclass or direct superinterface of an anonymous class to be instantiated (15.9.5)

  13. The element type in an array creation expression (15.10.1)

  14. The type in the cast operator of a cast expression (15.16)

  15. The type that follows the instanceof relational operator (15.20.2)

  16. In a method reference expression (15.13), as the reference type to search for a member method or as the class type or array type to construct.

The extraction of a TypeName from the identifiers of a ReferenceType in the 16 contexts above is intended to apply recursively to all sub-terms of the ReferenceType, such as its element type and any type arguments.

For example, suppose a field declaration uses the type p.q.Foo[]. The brackets of the array type are ignored, and the term p.q.Foo is extracted as a dotted sequence of Identifiers to the left of the brackets in an array type, and classified as a TypeName. A later step determines which of p, q, and Foo is a type name or a package name.

As another example, suppose a cast operator uses the type p.q.Foo<? extends String>. The term p.q.Foo is again extracted as a dotted sequence of Identifier terms, this time to the left of the < in a parameterized type, and classified as a TypeName. The term String is extracted as an Identifier in an extends clause of a wildcard type argument of a parameterized type, and classified as a TypeName.

A name is syntactically classified as an ExpressionName in these contexts:

• As the qualifying expression in a qualified superclass constructor invocation (8.8.7.1)

• As the qualifying expression in a qualified class instance creation expression (15.9)

• As the array reference expression in an array access expression (15.10.3)

• As a PostfixExpression (15.14)

• As the left-hand operand of an assignment operator (15.26)

• As a PatternVariable in a pattern (16.1)

• As a VariableAccess in a try-with-resources statement (14.20.3)

A name is syntactically classified as a MethodName in this context:

• Before the "(" in a method invocation expression (15.12)

A name is syntactically classified as a PackageOrTypeName in these contexts:

• To the left of the "." in a qualified TypeName

• In a type-import-on-demand declaration (7.5.2)

A name is syntactically classified as an AmbiguousName in these contexts:

• To the left of the "." in a qualified ExpressionName

• To the left of the rightmost . that occurs before the "(" in a method invocation expression

• To the left of the "." in a qualified AmbiguousName

• In the default value clause of an annotation type element declaration (9.6.2)

• To the right of an "=" in an an element-value pair (9.7.1)

• To the left of :: in a method reference expression (15.13)

The effect of syntactic classification is to restrict certain kinds of entities to certain parts of expressions:

• The name of a field, parameter, or local variable may be used as an expression (15.14.1).

• The name of a method may appear in an expression only as part of a method invocation expression (15.12).

• The name of a class or interface type may appear in an expression only as part of a class literal (15.8.2), a qualified this expression (15.8.4), a class instance creation expression (15.9), an array creation expression (15.10.1), a cast expression (15.16), an instanceof expression (15.20.2), an enum constant (8.9), or as part of a qualified name for a field or method.

• The name of a package may appear in an expression only as part of a qualified name for a class or interface type.

6.5.2 Reclassification of Contextually Ambiguous Names

An AmbiguousName is then reclassified as follows.

If the AmbiguousName is a simple name, consisting of a single Identifier:

• If the Identifier appears within the scope (6.3) of a local variable declaration (14.4) or pattern variable declaration (16.1) or parameter declaration (8.4.1, 8.8.1, 14.20) or field declaration (8.3) with that name, then the AmbiguousName is reclassified as an ExpressionName.

• Otherwise, if a field of that name is declared in the compilation unit (7.3) containing the Identifier by a single-static-import declaration (7.5.3), or by a static-import-on-demand declaration (7.5.4) then the AmbiguousName is reclassified as an ExpressionName.

• Otherwise, if the Identifier is a valid TypeIdentifier and appears within the scope (6.3) of a top level class (8) or interface type declaration (9), a local class declaration (14.3) or member type declaration (8.5, 9.5) with that name, then the AmbiguousName is reclassified as a TypeName.

• Otherwise, if the Identifier is a valid TypeIdentifier and a type of that name is declared in the compilation unit (7.3) containing the Identifier, either by a single-type-import declaration (7.5.1), or by a type-import-on-demand declaration (7.5.2), or by a single-static-import declaration (7.5.3), or by a static-import-on-demand declaration (7.5.4), then the AmbiguousName is reclassified as a TypeName.

• Otherwise, the AmbiguousName is reclassified as a PackageName. A later step determines whether or not a package of that name actually exists.

If the AmbiguousName is a qualified name, consisting of a name, a ".", and an Identifier, then the name to the left of the "." is first reclassified, for it is itself an AmbiguousName. There is then a choice:

• If the name to the left of the "." is reclassified as a PackageName, then:

  • If the Identifier is a valid TypeIdentifier, and there is a package whose name is the name to the left of the ".", and that package contains a declaration of a type whose name is the same as the Identifier, then this AmbiguousName is reclassified as a TypeName.

  • Otherwise, this AmbiguousName is reclassified as a PackageName. A later step determines whether or not a package of that name actually exists.

• If the name to the left of the "." is reclassified as a TypeName, then:

  • If the Identifier is the name of a method or field of the type denoted by TypeName, then this AmbiguousName is reclassified as an ExpressionName.

  • Otherwise, if the Identifier is a valid TypeIdentifier and is the name of a member type of the type denoted by TypeName, then this AmbiguousName is reclassified as a TypeName.

  • Otherwise, a compile-time error occurs.

• If the name to the left of the "." is reclassified as an ExpressionName, then this AmbiguousName is reclassified as an ExpressionName. A later step determines whether or not a member with the name Identifier actually exists.

The requirement that a potential type name be "a valid TypeIdentifier" prevents treating var as a type name. It is usually redundant, because the rules for declarations already prevent the introduction of types named var. However, in some cases, a compiler may find a binary class named var, and we want to be clear that such classes can never be named. The simplest solution is to consistently check for a valid TypeIdentifier.

package org.rpgpoet;
import java.util.Random;
public interface Music { Random[] wizards = new Random[4]; }

package bazola;
class Gabriel {
    static int n = org.rpgpoet.Music.wizards.length;
}

org.rpgpoet.Music.wizards
org.rpgpoet.Music
org.rpgpoet
org

6.5.6 Meaning of Expression Names

6.5.6.1 Simple Expression Names

If an expression name consists of a single Identifier, then there must be exactly one declaration denoting either a local variable, formal parameter, or field in scope at the point at which the Identifier occurs. Otherwise, a compile-time error occurs.

If the declaration denotes an instance variable (8.3.1.1), the expression name must appear within an instance method (8.4.3.2), instance variable initializer (8.3.2), instance initializer (8.6), or constructor (8.8). If the expression name appears within a class method, class variable initializer, or static initializer (8.7), then a compile-time error occurs.

If the declaration declares a final variable which is definitely assigned before the simple expression, the meaning of the name is the value of that variable. Otherwise, the meaning of the expression name is the variable declared by the declaration.

If the expression name appears in an assignment context, invocation context, or casting context, then the type of the expression name is the declared type of the field, local variable, pattern variable, or parameter after capture conversion (5.1.10).

Otherwise, the type of the expression name is the declared type of the field, local variable, pattern variable, or parameter.

That is, if the expression name appears "on the right hand side", its type is subject to capture conversion. If the expression name is a variable that appears "on the left hand side", its type is not subject to capture conversion.

class Test {
    static int v;
    static final int f = 3;
    public static void main(String[] args) {
        int i;
        i = 1;
        v = 2;
        f = 33;  // compile-time error
        System.out.println(i + " " + v + " " + f);
    }
}

1 2 3

Chapter 15: Expressions

15.20 Relational Operators

The numerical comparison operators <, >, <=, and >=, and the instanceof operator, are called the relational operators.

RelationalExpression:

ShiftExpression

RelationalExpression < ShiftExpression

RelationalExpression > ShiftExpression

RelationalExpression <= ShiftExpression

RelationalExpression >= ShiftExpression

RelationalExpression instanceof ReferenceType Pattern

Patterns are defined in Chapter 16.

The relational operators are syntactically left-associative (they group left-to-right).

However, this fact is not useful. For example, a<b<c parses as (a<b)<c, which is always a compile-time error, because the type of a<b is always boolean and < is not an operator on boolean values.

The type of a relational expression is always boolean.

15.20.2 Type Comparison Operator instanceof The instanceof Operator

class Point   { int x, y; }
class Element { int atomicNumber; }
class Test {
    public static void main(String[] args) {
        Point   p = new Point();
        Element e = new Element();
        if (e instanceof Point) {  // compile-time error
            System.out.println("I get your point!");
            p = (Point)e;  // compile-time error
        }
    }
}

class Point extends Element { int x, y; }

Chapter 16 Patterns

16.1 Kinds of Patterns

16.1.1 Type Test Pattern

16.2 Compatibility of an Expression with a Pattern

16.3 Execution of Pattern Matching