Flexible Constructor Bodies (Third Preview)

This document describes changes to the Java Language Specification to support Flexible Constructor Bodies, which is a proposed feature of Java SE 24. See JEP 492 for an overview of the feature.

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 6: Names

6.5 Determining the Meaning of a Name

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, exception 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 of a class C (8.3.1.1), then both all of the following must be true, or a compile-time error occurs:

• The expression name does not occur in a static context (8.1.3).

• If the expression name occurs in an early construction context of C (8.8.7), then it is the left-hand operand of a simple assignment expression (15.26), the declaration of the named variable lacks an initializer, and the simple assignment expression is not enclosed in a lambda expression or inner class declaration that is contained in the early construction context of C.

• The expression name does not occur in an early construction context of a subclass of C.

• If the expression name appears in a nested class or interface declaration of C, then the immediately enclosing class or interface declaration of the expression name is an inner class of C.

For example, the expression name must not appear in the body of a static method declared by C, nor in the body of an instance method of a static class nested within C.

If the declaration denotes a local variable, formal parameter, or exception parameter, let X be the innermost method declaration, constructor declaration, instance initializer, static initializer, field declaration, or explicit constructor invocation statement which encloses the local variable or parameter declaration. If the expression name appears directly or indirectly in the body of a local class, local interface, or anonymous class D declared directly in X, then both of the following must be true, or a compile-time error occurs:

• The expression name does not occur in a static context.

• D is an inner class, and the immediately enclosing class or interface declaration of the expression name is D or an inner class of D.

For example, the expression name must not appear in the body of a static method declared by D, nor (if D is a local interface) in the body of a default method of D.

If the declaration denotes a local variable, formal parameter, or exception parameter that is neither final nor effectively final (4.12.4), it is a compile-time error if the expression name appears either in an inner class enclosed directly or indirectly by X, or in a lambda expression contained by X (15.27).

The net effect of these rules is that a local variable, formal parameter, or exception parameter can only be referenced from a nested class or interface declared within its scope if (i) the reference is not within a static context, (ii) there is a chain of inner (non-static) classes from the reference to the variable declaration, and (iii) the variable is final or effectively final. References from lambda expressions also require the variable to be final or effectively final.

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, or parameter after capture conversion (5.1.10).

Otherwise, the type of the expression name is the declared type of the field, local 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

class Test {
    static String a;
    String b;

    String concat1() {
        return a + b;
    }

    static String concat2() {
        return a + b;  // compile-time error
    }

    int index() {
        interface I {
            class Matcher {
                void check() {
                    if (a == null ||
                        b == null) {  // compile-time error
                        throw new IllegalArgumentException();
                    }
                }
                int match(String s, String t) {
                    return s.indexOf(t);
                }
            }
    }

    I.Matcher matcher = new I.Matcher();
    matcher.check();
    return matcher.match(a, b);
    }
}

class Test {
    public static void main(String[] args) {
        String first = args[0];

        class Checker {
            void checkWhitespace(int x) {
                String arg = args[x];
                if (!arg.trim().equals(arg)) {
                    throw new IllegalArgumentException();
                }
            }

            static void checkFlag(int x) {
                String arg = args[x];  // compile-time error
                if (!arg.startsWith("-")) {
                    throw new IllegalArgumentException();
                }
            }

            static void checkFirst() {
                Runnable r = new Runnable() {
                    public void run() {
                        if (first == null) {  // compile-time error
                            throw new IllegalArgumentException();
                        }
                    }
                };
                r.run();
            }
        }

        final Checker c = new Checker();
        c.checkFirst();
        for (int i = 1; i < args.length; i++) {
            Runnable r = () -> {
                c.checkWhitespace(i);  // compile-time error
                c.checkFlag(i);  // compile-time error
            };
        }
    }
}

6.5.7 Meaning of Method Names

6.5.7.1 Simple Method Names

A simple method name appears in the context of a method invocation expression (15.12). The simple method name consists of a single UnqualifiedMethodIdentifier which specifies the name of the method to be invoked. The rules of method invocation require that the UnqualifiedMethodIdentifier denotes a method that is in scope at the point of the method invocation. The rules also prohibit (15.12.3) a reference to an instance method occurring in a static context (8.1.3), or in a nested class or interface other than an inner class of the class or interface which declares the instance method. The rules (15.12.3) also prohibit a reference to an instance method occurring in any one of the following:

class T {
    void foo() { ... }
    static class Mid {
        class L {
            ... foo() ... // Compile-time error as L is not an inner class of T
        }
    }
}

class B {
    void foo() { ... }
}
class T extends B {
    class Mid {
        class L {
            ... foo() ... // No compile-time error even though L is not an inner class of B
        }
    }
 }

class Super {
    void f2(String s)       {}
    void f3(String s)       {}
    void f3(int i1, int i2) {}
}

class Test {
    void f1(int i) {}
    void f2(int i) {}
    void f3(int i) {}

    void m() {
        new Super() {
            {
                f1(0);  // OK, resolves to Test.f1(int)
                f2(0);  // compile-time error
                f3(0);  // compile-time error
            }
        };
    }
}

Chapter 8: Classes

A class declaration defines a new class and describes how it is implemented (8.1).

A top level class (7.6) is a class declared directly in a compilation unit.

A nested class is any class whose declaration occurs within the body of another class or interface declaration. A nested class may be a member class (8.5, 9.5), a local class (14.3), or an anonymous class (15.9.5).

Some kinds of nested class are an inner class (8.1.3), which is a class that can refer to enclosing class instances, local variables, and type variables.

An enum class (8.9) is a class declared with abbreviated syntax that defines a small set of named class instances.

A record class (8.10) is a class declared with abbreviated syntax that defines a simple aggregate of values.

This chapter discusses the common semantics of all classes. Details that are specific to particular kinds of classes are discussed in the sections dedicated to these constructs.

A class may be declared public (8.1.1) so it can be referred to from code in any package of its module and potentially from code in other modules.

A class may be declared abstract (8.1.1.1), and must be declared abstract if it is incompletely implemented; such a class cannot be instantiated, but can be extended by subclasses. The degree to which a class can be extended can be controlled explicitly (8.1.1.2): it may be declared sealed to limit its subclasses, or it may be declared final to ensure no subclasses. Each class except Object is an extension of (that is, a subclass of) a single existing class (8.1.4) and may implement interfaces (8.1.5).

A class may be generic (8.1.2), that is, its declaration may introduce type variables whose bindings differ among different instances of the class.

Class declarations may be decorated with annotations (9.7) just like any other kind of declaration.

The body of a class declares members (fields, methods, classes, and interfaces), instance and static initializers, and constructors (8.1.7). The scope (6.3) of a member (8.2) is the entire body of the declaration of the class to which the member belongs. Field, method, member class, member interface, and constructor declarations may include the access modifiers public, protected, or private (6.6). The members of a class include both declared and inherited members (8.2). Newly declared fields can hide fields declared in a superclass or superinterface. Newly declared member classes and member interfaces can hide member classes and member interfaces declared in a superclass or superinterface. Newly declared methods can hide, implement, or override methods declared in a superclass or superinterface.

Field declarations (8.3) describe class variables, which are incarnated once, and instance variables, which are freshly incarnated for each instance of the class. A field may be declared final (8.3.1.2), in which case it can be assigned to only once. Any field declaration may include an initializer.

Member class declarations (8.5) describe nested classes that are members of the surrounding class. Member classes may be static, in which case they have no access to the instance variables of the surrounding class; or they may be inner classes.

Member interface declarations (8.5) describe nested interfaces that are members of the surrounding class.

Method declarations (8.4) describe code that may be invoked by method invocation expressions (15.12). A class method is invoked relative to the class; an instance method is invoked with respect to some particular object that is an instance of a class. A method whose declaration does not indicate how it is implemented must be declared abstract. A method may be declared final (8.4.3.3), in which case it cannot be hidden or overridden. A method may be implemented by platform-dependent native code (8.4.3.4). A synchronized method (8.4.3.6) automatically locks an object before executing its body and automatically unlocks the object on return, as if by use of a synchronized statement (14.19), thus allowing its activities to be synchronized with those of other threads (17).

Method names may be overloaded (8.4.9).

Instance initializers (8.6) are blocks of executable code that may be used to help initialize an instance when it is created (15.9).

Static initializers (8.7) are blocks of executable code that may be used to help initialize a class.

Constructors (8.8) are similar to methods, but cannot be invoked directly by a method call; they are used to initialize new class instances. Like methods, they may be overloaded (8.8.8).

8.1 Class Declarations

8.1.3 Inner Classes and Enclosing Instances

An inner class is a nested class that is not explicitly or implicitly static.

An inner class is one of the following:

• a member class that is not explicitly or implicitly static (8.5)

• a local class that is not implicitly static (14.3)

• an anonymous class (15.9.5)

The following nested classes are implicitly static, so are not inner classes:

• a member enum class (8.9)
• a local enum class (14.3)
• a member record class (8.10)
• a local record class (14.3)
• a member class of an interface (9.5)

All of the rules that apply to nested classes apply to inner classes. In particular, an inner class may declare and inherit static members (8.2), and declare static initializers (8.7), even though the inner class itself is not static.

There are no "inner interfaces" because every nested interface is implicitly static (9.1.1.3).

class HasStatic {
    static int j = 100;
}

class Outer {
    class Inner extends HasStatic {
        static {
            System.out.println("Hello from Outer.Inner");
        }

        static       int x = 3;
        static final int y = 4;

        static void hello() {
            System.out.println("Hello from Outer.Inner.hello");
        }

        static class VeryNestedButNotInner
            extends NestedButNotInner {}
    }

    static class NestedButNotInner {
        int z = Inner.x;
    }

    interface NeverInner {}  // Implicitly static, so never inner
}

A construct (statement, local variable declaration statement, local class declaration, local interface declaration, or expression) occurs in a static context if the innermost:

• method declaration,

• field declaration,

• constructor declaration,

• instance initializer, or

• static initializer, or

• explicit constructor invocation statement

which encloses the construct is one of the following:

• a static method declaration (8.4.3.2, 9.4)

• a static field declaration (8.3.1.1, 9.3)

• a static initializer (8.7)

• an explicit constructor invocation statement (8.8.7.1)

Note that a construct which appears in a constructor declaration or an instance initializer does not occur in a static context.

The purpose of a static context is to demarcate code that must not refer explicitly or implicitly to the current instance of the class whose declaration lexically encloses the static context. for which there is no current instance defined of the class whose declaration lexically encloses the static context. Consequently, code that occurs in a static context is restricted in the following ways:

• this expressions (both unqualified and qualified) are disallowed (15.8.3, 15.8.4).

• Field accesses, method invocations, and method references may not be qualified by super (15.11.2, 15.12.3, 15.13.1).

• Unqualified references to instance variables of any lexically enclosing class or interface declaration are disallowed (6.5.6.1).

• Unqualified invocations of instance methods of any lexically enclosing class or interface declaration are disallowed (15.12.3).

• References to type parameters of any lexically enclosing class or interface declarations are disallowed (6.5.5.1).

• References to type parameters, local variables, formal parameters, and exception parameters declared by methods or constructors of any lexically enclosing class or interface declaration that is outside the immediately enclosing class or interface declaration are disallowed (6.5.5.1, 6.5.6.1).

• Declarations of local normal classes (as opposed to local enum classes) and declarations of anonymous classes both specify classes that are inner, yet when instantiated have no immediately enclosing instances (15.9.2).

• Class instance creation expressions that instantiate inner member classes must be qualified (15.9.2).

An inner class C is a direct inner class of a class or interface O if O is the immediately enclosing class or interface declaration of C and the declaration of C does not occur in a static context.

If an inner class is a local class or an anonymous class, it may be declared in a static context, and in that case is not considered an inner class of any enclosing class or interface.

A class C is an inner class of class or interface O if it is either a direct inner class of O or an inner class of an inner class of O.

It is unusual, but possible, for the immediately enclosing class or interface declaration of an inner class to be an interface. This only occurs if the class is a local or anonymous class declared in a default or static method body (9.4).

A class or interface O is the zeroth lexically enclosing class or interface declaration of itself.

A class O is the n'th lexically enclosing class declaration of a class C if it is the immediately enclosing class declaration of the n-1'th lexically enclosing class declaration of C.

An instance i of a direct inner class C of a class or interface O is may be associated with an instance of O, known as the immediately enclosing instance of i. The immediately enclosing instance of an object, if any, is determined when the object is created (15.9.2).

An object o is the zeroth lexically enclosing instance of itself.

An object o is the n'th lexically enclosing instance of an instance i if it is the immediately enclosing instance of the n-1'th lexically enclosing instance of i.

An instance of an inner local class or an anonymous class whose declaration occurs in a static context has no immediately enclosing instance. Also, an instance of a static nested class (8.1.1.4) has no immediately enclosing instance.

class Outer {
    int x;
    class Inner extends Thread {
        Inner() {
            super(new Runnable() {
                @Override
                public void run() {
                    System.out.println("hello from " + Outer.this.x); // error??
                }
            });
        }
    }
}

For every superclass S of C which is itself a direct inner class of a class or interface SO, there is an instance of SO associated with i, known as the immediately enclosing instance of i with respect to S. The immediately enclosing instance of an object with respect to its class' direct superclass, if any, is determined when the superclass constructor is invoked via an explicit constructor invocation statement (8.8.7.1).

Any local variable, formal parameter, or exception parameter used but not declared in an inner class must either be final or effectively final (4.12.4), as specified in 6.5.6.1.

Any local variable used but not declared in an inner class must be definitely assigned (16) before the body of the inner class, or a compile-time error occurs.

Similar rules on variable use apply in the body of a lambda expression (15.27.2).

A blank final field (4.12.4) of a lexically enclosing class or interface declaration may not be assigned within an inner class, or a compile-time error occurs.

class Outer {
    int i = 100;
    static void classMethod() {
        final int l = 200;
        class LocalInStaticContext {
            int k = i;  // Compile-time error
            int m = l;  // OK
        }
    }
    void foo() {
        class Local {  // A local class
            int j = i;
        }
    }
}

class WithDeepNesting {
    boolean toBe;
    WithDeepNesting(boolean b) { toBe = b; }

    class Nested {
        boolean theQuestion;
        class DeeplyNested {
            DeeplyNested(){
                theQuestion = toBe || !toBe;
            }
        }
    }
}

8.8 Constructor Declarations

8.8.7 Constructor Body

The first statement of a constructor body may be an explicit invocation of another constructor of the same class or of the direct superclass (8.8.7.1).

ConstructorBody:

{ [ExplicitConstructorInvocation] [BlockStatements] }

{ [BlockStatements] }

{ [BlockStatements] ExplicitConstructorInvocation [BlockStatements] }

It is a compile-time error for a constructor to directly or indirectly invoke itself through a series of one or more explicit constructor invocations involving this.

If a constructor body does not begin with contain an explicit constructor invocation and the constructor being declared is not part of the primordial class Object, then the constructor body (1) has an empty prologue, (2) implicitly begins with a superclass constructor invocation "super();", an invocation of the constructor of its the direct superclass that takes no arguments, and (3) the statements, if any, given in the constructor body, are taken to form the epilogue of the constructor body.

Except for the possibility of explicit or implicit constructor invocations, and the prohibition on explicitly returning a value prohibitions on return statements (14.17), the body of a constructor is like the body of a method (8.4.7).

A return statement (14.17) may be used in the body of a constructor if it does not include an expression.

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}
class ColoredPoint extends Point {
    static final int WHITE = 0, BLACK = 1;
    int color;
    ColoredPoint(int x, int y) {
        this(x, y, WHITE);
    }
    ColoredPoint(int x, int y, int color) {
        super(x, y);
        this.color = color;
    }
}

8.8.7.1 Explicit Constructor Invocations

ExplicitConstructorInvocation:

[TypeArguments] this ( [ArgumentList] ) ;

[TypeArguments] super ( [ArgumentList] ) ;

ExpressionName . [TypeArguments] super ( [ArgumentList] ) ;

Primary . [TypeArguments] super ( [ArgumentList] ) ;

The following productions from 4.5.1 and 15.12 are shown here for convenience:

TypeArguments:

< TypeArgumentList >

ArgumentList:

Expression {, Expression}

Explicit constructor invocation statements invocations are divided into two kinds:

• Alternate constructor invocations begin with the keyword this (possibly prefaced with explicit type arguments). They are used to invoke an alternate constructor of the same class.

• Superclass constructor invocations begin with either the keyword super (possibly prefaced with explicit type arguments) or a Primary expression or an ExpressionName. They are used to invoke a constructor of the direct superclass. They are further divided:

  • Unqualified superclass constructor invocations begin with the keyword super (possibly prefaced with explicit type arguments).

  • Qualified superclass constructor invocations begin with a Primary expression or an ExpressionName. They allow a subclass constructor to explicitly specify the newly created object's immediately enclosing instance with respect to the direct superclass (8.1.3). This may be necessary when the superclass is an inner class.

If TypeArguments is present to the left of this or super, then it is a compile-time error if any of the type arguments are wildcards (4.5.1).

The rules for a superclass constructor invocation, where Let C be is the class being instantiated, and let S be is the direct superclass of C, are as follows:

• If a superclass constructor invocation statement is unqualified, then:

  • If S is an inner member class, but S is not a member of a class enclosing C, then a compile-time error occurs.

    Otherwise, let O be the innermost enclosing class of C of which S is a member. C must be an inner class of O (8.1.3), or a compile-time error occurs. If the superclass constructor invocation occurs in an early construction context of the class O, then a compile-time error occurs.

  • If S is an inner local class, and S does not occur in a static context, let O be the immediately enclosing class or interface declaration of S. C must be an inner class of O, or a compile-time error occurs.

• If a superclass constructor invocation statement is qualified, then:

  • If S is not an inner class, or if the declaration of S occurs in a static context, then a compile-time error occurs.

  • Otherwise, let p be the Primary expression or the ExpressionName immediately preceding ".super", and let O be the immediately enclosing class of S. It is a compile-time error if the type of p is not O or a subclass of O, or if the type of p is not accessible (6.6).

The exception types that an explicit constructor invocation statement can throw are specified in 11.2.2.

Evaluation of an alternate constructor invocation statement proceeds by first evaluating the arguments to the constructor, left-to-right, as in an ordinary method invocation; and then invoking the constructor.

Evaluation of a superclass constructor invocation proceeds as follows:

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}
class ColoredPoint extends Point {
    static final int WHITE = 0, BLACK = 1;
    int color;
    ColoredPoint(int x, int y) {
        this(x, y, color);  // Changed to color from WHITE
    }
    ColoredPoint(int x, int y, int color) {
        super(x, y);
        this.color = color;
    }
}

class Outer {
    class Inner {}
}
class ChildOfInner extends Outer.Inner {
    ChildOfInner() { (new Outer()).super(); }
}

class Outer {
    int secret = 5;
    class Inner {
        int  getSecret()      { return secret; }
        void setSecret(int s) { secret = s; }
    }
}
class ChildOfInner extends Outer.Inner {
    ChildOfInner(Outer x) { x.super(); }
}

public class Test {
    public static void main(String[] args) {
        Outer x = new Outer();
        ChildOfInner a = new ChildOfInner(x);
        ChildOfInner b = new ChildOfInner(x);
        System.out.println(b.getSecret());
        a.setSecret(6);
        System.out.println(b.getSecret());
    }
}

5
6

8.10 Record Classes

8.10.4 Record Constructor Declarations

To ensure proper initialization of its record components, a record class does not implicitly declare a default constructor (8.8.9). Instead, a record class has a canonical constructor, declared explicitly or implicitly, that initializes all the component fields of the record class.

There are two ways to explicitly declare a canonical constructor in a record declaration: by declaring a normal constructor with a suitable signature (8.10.4.1) or by declaring a compact constructor (8.10.4.2).

Given the signature of a normal constructor that qualifies as canonical, and the signature derived for a compact constructor, the rules of constructor signatures (8.8.2) mean it is a compile-time error if a record declaration has both a normal constructor that qualifies as canonical and a compact constructor.

Either way, an explicitly declared canonical constructor must provide at least as much access as the record class, as follows:

• If the record class is public, then the canonical constructor must be public; otherwise, a compile-time error occurs.

• If the record class is protected, then the canonical constructor must be protected or public; otherwise, a compile-time error occurs.

• If the record class has package access, then the canonical constructor must not be private; otherwise, a compile-time error occurs.

• If the record class is private, then the canonical constructor may be declared with any accessibility.

An explicitly declared canonical constructor may be a fixed arity constructor or a variable arity constructor (8.8.1).

If a canonical constructor is not explicitly declared in the declaration of a record class R, then a canonical constructor r is implicitly declared in R with the following properties:

• The signature of r has no type parameters, and has formal parameters given by the derived formal parameter list of R, defined below.

• r has the same access modifier as R, unless R lacks an access modifier, in which case r has package access.

• r has no throws clause.

• The body of r initializes each component field of the record class with the corresponding formal parameter of r, in the order that record components (corresponding to the component fields) appear in the record header.

The derived formal parameter list of a record class is formed by deriving a formal parameter from each record component in the record header, in order, as follows:

• If the record component is not a variable arity record component, then the derived formal parameter has the same name and declared type as the record component.

  If the record component is a variable arity record component, then the derived formal parameter is a variable arity parameter (8.4.1) with the same name and declared type as the record component.

• The derived formal parameter is annotated with the annotations, if any, that appear on the record component and whose annotation interfaces are applicable in the formal parameter context, or in type contexts, or both (9.7.4).

A record declaration may contain declarations of constructors that are not canonical constructors. The body of every non-canonical constructor in a record declaration must start with contain an alternate constructor invocation (8.8.7.1), or a compile-time error occurs.

Chapter 11: Exceptions

11.2 Compile-Time Checking of Exceptions

11.2.2 Exception Analysis of Statements and Explicit Constructor Invocations

A throw statement (14.18) whose thrown expression has static type E and is not a final or effectively final exception parameter can throw E or any exception class that the thrown expression can throw.

For example, the statement throw new java.io.FileNotFoundException(); can throw java.io.FileNotFoundException only. Formally, it is not the case that it "can throw" a subclass or superclass of java.io.FileNotFoundException.

A throw statement whose thrown expression is a final or effectively final exception parameter of a catch clause C can throw an exception class E iff:

• E is an exception class that the try block of the try statement which declares C can throw; and

• E is assignment compatible with any of C's catchable exception classes; and

• E is not assignment compatible with any of the catchable exception classes of the catch clauses declared to the left of C in the same try statement.

A try statement (14.20) can throw an exception class E iff either:

• The try block can throw E, or an expression used to initialize a resource (in a try-with-resources statement) can throw E, or the automatic invocation of the close() method of a resource (in a try-with-resources statement) can throw E, and E is not assignment compatible with any catchable exception class of any catch clause of the try statement, and either no finally block is present or the finally block can complete normally; or

• Some catch block of the try statement can throw E and either no finally block is present or the finally block can complete normally; or

• A finally block is present and can throw E.

A switch statement (14.11) can throw an exception class E iff either:

• The selector expression can throw E; or

• Some switch rule expression, switch rule block, switch rule throw statement, or switch labeled statement group in the switch block can throw E.

Any other statement S can throw an exception class E iff an expression or statement immediately contained in S can throw E.

Chapter 12: Execution

12.5 Creation of New Class Instances

A new class instance is explicitly created when evaluation of a class instance creation expression (15.9) causes a class to be instantiated.

A new class instance may be implicitly created in the following situations:

• Loading of a class or interface that contains a string literal (3.10.5) or a text block (3.10.6) may create a new String object to denote the string represented by the string literal or text block. (This object creation will not occur if an instance of String denoting the same sequence of Unicode code points as the string represented by the string literal or text block has previously been interned.)

• Execution of an operation that causes boxing conversion (5.1.7). Boxing conversion may create a new object of a wrapper class (Boolean, Byte, Short, Character, Integer, Long, Float, Double) associated with one of the primitive types.

• Execution of a string concatenation operator + (15.18.1) that is not part of a constant expression (15.29) always creates a new String object to represent the result. String concatenation operators may also create temporary wrapper objects for a value of a primitive type.

• Evaluation of a method reference expression (15.13.3) or a lambda expression (15.27.4) may require that a new instance be created of a class that implements a functional interface type (9.8).

Each of these situations identifies a particular constructor (8.8) to be called with specified arguments (possibly none) as part of the class instance creation process.

Whenever a new class instance is created, memory space is allocated for it with room for all the instance variables declared in the class and all the instance variables declared in each superclass of the class, including all the instance variables that may be hidden (8.3).

If there is not sufficient space available to allocate memory for the object, then creation of the class instance completes abruptly with an OutOfMemoryError. Otherwise, all the instance variables in the new object, including those declared in superclasses, are initialized to their default values (4.12.5).

Just before a reference to the newly created object is returned as the result, the indicated constructor is processed to initialize the new object using the following procedure:

Unlike C++, the Java programming language does not specify altered rules for method dispatch during the creation of a new class instance. If methods are invoked that are overridden in subclasses in the object being initialized, then these overriding methods are used, even before the new object is completely initialized. Classes can avoid unwanted exposure of uninitialized state by assigning to their fields in the prologue of the constructor body.

class Point {
    int x, y;
    Point() { x = 1; y = 1; }
}
class ColoredPoint extends Point {
    int color = 0xFF00FF;
}
class Test {
    public static void main(String[] args) {
        ColoredPoint cp = new ColoredPoint();
        System.out.println(cp.color);
    }
}

ColoredPoint() { super(); }

Point() { super(); x = 1; y = 1; }

Object() { }

class Super {
    Super() { printThree(); }
    void printThree() { System.out.println("three"); }
}
class Test extends Super {
    int three = (int)Math.PI;  // That is, 3
    void printThree() { System.out.println(three); }

    public static void main(String[] args) {
        Test t = new Test();
        t.printThree();
    }
}

0
3

class Super {
    Super() { printThree(); }
    void printThree() { System.out.println("three"); }
}
class Test extends Super {
    int three;

    public Test() {
        three = (int)Math.PI;  // That is, 3
        super();
    }

    void printThree() { System.out.println(three); }

    public static void main(String[] args) {
        Test t = new Test();
        t.printThree();
    }
}

3
3

Chapter 14: Blocks, Statements, and Patterns

14.17 The return Statement

A return statement returns control to the invoker of a method (8.4, 15.12) or constructor (8.8, 15.9).

ReturnStatement:

return [Expression] ;

There are two kinds of return statement:

• A return statement with no value.

• A return statement with value Expression.

A return statement attempts to transfer control to the invoker of the innermost enclosing constructor, method, or lambda expression; this enclosing declaration or expression is called the return target. In the case of a return statement with value Expression, the value of the Expression becomes the value of the invocation.

It is a compile-time error if a return 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 the return statement, or (ii) a switch expression that encloses the return statement.

It is a compile-time error if the return target of a return statement with no value is a method, and that method is not declared void.

It is a compile-time error if the return target of a return statement is a constructor, and the return statement appears in the prologue of this constructor (8.8.7).

It is a compile-time error if the return target of a return statement with value Expression is either a constructor, or a method that is declared void.

It is a compile-time error if the return target of a return statement with value Expression is a method with declared return type T, and the type of Expression is not assignable compatible (5.2) with T.

Execution of a return statement with no value always completes abruptly, the reason being a return with no value.

Execution of a return statement with value Expression first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the return statement completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the return statement completes abruptly, the reason being a return with value V.

It can be seen, then, that a return statement always completes abruptly.

The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are any try statements (14.20) within the method or constructor whose try blocks or catch clauses contain the return statement, then any finally clauses of those try statements will be executed, in order, innermost to outermost, before control is transferred to the invoker of the method or constructor. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a return statement.

14.22 Unreachable Statements

It is a compile-time error if a statement cannot be executed because it is unreachable.

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 of while, do, and for statements whose condition expression has the constant value true, 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 of n is known at compile time and in principle it can be known at compile time that the assignment to k can never be executed.

The rules in this section define two technical terms:

• whether a statement is reachable

• whether a statement can complete normally

The rules allow a statement to complete normally only if it is reachable.

Two further technical terms are used:

• A reachable break statement exits a statement if, within the break target, either there are no try statements whose try blocks contain the break statement, or there are try statements whose try blocks contain the break statement and all finally clauses of those try statements can complete normally.

  This definition is based on the logic around "attempts to transfer control" in [14.15].

• A continue statement continues a do statement if, within the do statement, either there are no try statements whose try blocks contain the continue statement, or there are try statements whose try blocks contain the continue statement and all finally clauses of those try statements can complete normally.

The rules are as follows:

• The block that is the body of a constructor, method, instance initializer, static initializer, lambda expression, or switch 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 or a constructor body containing an explicit constructor invocation 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 or a constructor body containing an explicit constructor invocation is reachable iff the block is reachable.

  Every other statement S in a non-empty block that is not a switch block or a constructor body containing an explicit constructor invocation is reachable iff the statement preceding S can complete normally.

Chapter 15: Expressions

15.8 Primary Expressions

15.8.3 this

The keyword this may be used as an expression in the following contexts:

• in the body of an instance method of a class (8.4.3.2)

• in the body of a constructor of a class (8.8.7)

• in an instance initializer of a class (8.6)

• in the initializer of an instance variable of a class (8.3.2)

• in the body of an instance method of an interface, that is, a default method or a non-static private interface method (9.4)

When used as an expression, the keyword this denotes a value that is a reference either to the object for which the instance method was invoked (15.12), or to the object being constructed. The value denoted by this in a lambda body (15.27.2) is the same as the value denoted by this in the surrounding context.

The keyword this is also used in explicit constructor invocation statements invocations (8.8.7.1), and to denote the receiver parameter of a method or constructor (8.4).

It is a compile-time error if a this expression occurs in a static context (8.1.3).

Let C by the innermost enclosing class or interface declaration of a this expression.

If C is generic, with type parameters F₁,...,F_n, the type of this is C<F₁,...,F_n>. Otherwise, the type of this is C.

At run time, the class of the actual object referred to may be C or a subclass of C (8.1.5).

class IntVector {
    int[] v;
    boolean equals(IntVector other) {
        if (this == other)
            return true;
        if (v.length != other.v.length)
            return false;
        for (int i = 0; i < v.length; i++) {
            if (v[i] != other.v[i]) return false;
        }
        return true;
    }
}

15.8.4 Qualified this

Any lexically enclosing instance (8.1.3) can be referred to by explicitly qualifying the keyword this.

Let n be an integer such that TypeName denotes the n'th lexically enclosing class or interface declaration of the class or interface whose declaration immediately encloses the qualified this expression.

The value of a qualified this expression TypeName.this is the n'th lexically enclosing instance of this.

If TypeName denotes a generic class, with type parameters F₁,...,F_n, the type of the qualified this expression is TypeName<F₁,...,F_n>. Otherwise, the type of the qualified this expression is TypeName.

It is a compile-time error if a qualified this expression occurs in a static context (8.1.3).

It is a compile-time error if the class or interface whose declaration immediately encloses a qualified this expression is not an inner class of TypeName or TypeName itself.

15.9 Class Instance Creation Expressions

15.9.2 Determining Enclosing Instances

Let C be the class being instantiated, and let i be the instance being created. If C is an inner class, then i may have an immediately enclosing instance (8.1.3), determined as follows:

• If C is an anonymous class, then:

  • If the class instance creation expression occurs in a static context, then i has no immediately enclosing instance. Let S be the nearest static method declaration, static field declaration, or static initializer that encloses the declaration of C. If the nearest static method declaration, static field declaration, or static initializer that encloses the class instance creation expression is not S, then a compile-time error occurs.

    This missing condition is a bugfix for extensions introduced in JEP 395.

  • Otherwise, the immediately enclosing instance of i is this.

• If C is an inner local class, then:

  • If C occurs in a static context, then i has no immediately enclosing instance. Let S be the nearest static method declaration, static field declaration, or static initializer that encloses the declaration of C. If the nearest static method declaration, static field declaration, or static initializer that encloses the class instance creation expression is not S, then a compile-time error occurs.

    This missing condition is a bugfix for extensions introduced in JEP 395.

  • Otherwise, if the class instance creation expression occurs in a static context, then a compile-time error occurs.

  • Otherwise, let O be the immediately enclosing class or interface declaration of C, and let U be the immediately enclosing class or interface declaration of the class instance creation expression.

    If U is not an inner class of O or O itself, then a compile-time error occurs.

    Let n be an integer such that O is the n'th lexically enclosing class or interface declaration of U.

    The immediately enclosing instance of i is the n'th lexically enclosing instance of this.

• If C is an inner member class, then:

  • If the class instance creation expression is unqualified, then:

    • If the class instance creation expression occurs in a static context, then a compile-time error occurs.

    • Otherwise, if C is not a member of any class whose declaration lexically encloses the class instance creation expression, then a compile-time error occurs.

    • Otherwise, let O be the innermost enclosing class declaration of which C is a member, and let U be the immediately enclosing class or interface declaration of the class instance creation expression.

      If U is not an inner class of O or O itself, then a compile-time error occurs.

      If the class instance creation expression occurs in the early construction context (8.8.7) of O, then a compile-time error occurs.

      Let n be an integer such that O is the n'th lexically enclosing class or interface declaration of U

      The immediately enclosing instance of i is the n'th lexically enclosing instance of this.

  • If the class instance creation expression is qualified, then the immediately enclosing instance of i is the object that is the value of the Primary expression or the ExpressionName.

If C is an anonymous class, and its direct superclass S is an inner class, then i may have an immediately enclosing instance with respect to S, determined as follows:

• If S is an inner local class, then:

  • If S occurs in a static context, then i has no immediately enclosing instance with respect to S.

  • Otherwise, if the class instance creation expression occurs in a static context, then a compile-time error occurs.

  • Otherwise, let O be the immediately enclosing class or interface declaration of S, and let U be the immediately enclosing class or interface declaration of the class instance creation expression.

    If U is not an inner class of O or O itself, then a compile-time error occurs.

    Let n be an integer such that O is the n'th lexically enclosing class or interface declaration of U.

    The immediately enclosing instance of i with respect to S is the n'th lexically enclosing instance of this.

• If S is an inner member class, then:

  • If the class instance creation expression is unqualified, then:

    • If the class instance creation expression occurs in a static context, then a compile-time error occurs.

    • Otherwise, if S is not a member of any class whose declaration encloses the class instance creation expression, then a compile-time error occurs.

    • Otherwise, let O be the innermost enclosing class declaration of which S is a member, and let U be the immediately enclosing class or interface declaration of the class instance creation expression.

      If U is not an inner class of O or O itself, then a compile-time error occurs.

      If the class instance creation expression occurs in the early construction context of O, then a compile-time error occurs.

      Let n be an integer such that O is the n'th lexically enclosing class or interface declaration of U.

      The immediately enclosing instance of i with respect to S is the n'th lexically enclosing instance of this.

    • Otherwise, a compile-time error occurs.

  • If the class instance creation expression is qualified, then the immediately enclosing instance of i with respect to S is the object that is the value of the Primary expression or the ExpressionName.

15.11 Field Access Expressions

15.11.2 Accessing Superclass Members using super

The form super.Identifier refers to the field named Identifier of the current object, but with the current object viewed as an instance of the superclass of the current class.

The form T.super.Identifier refers to the field named Identifier of the lexically enclosing instance corresponding to T, but with that instance viewed as an instance of the superclass of T.

The forms using the keyword super may be used in the locations within a class declaration that allow the keyword this as an expression (15.8.3).

It is a compile-time error if a field access expression using the keyword super appears occurs in a static context (8.1.3) or in an early construction context (8.8.7) of the current class.

For a field access expression of the form super.Identifier:

• It is a compile-time error if the immediately enclosing class or interface declaration of the field access expression is the class Object or an interface.

For a field access expression of the form T.super.Identifier:

• It is a compile-time error if T is the class Object or an interface.

• Let U be the immediately enclosing class or interface declaration of the field access expression. It is a compile-time error if U is not an inner class of T or T itself.

Suppose that a field access expression super.f appears within class C, and the immediate superclass of C is class S. If f in S is accessible from class C (6.6), then super.f is treated as if it had been the expression this.f in the body of class S. Otherwise, a compile-time error occurs.

Thus, super.f can access the field f that is accessible in class S, even if that field is hidden by a declaration of a field f in class C.

Suppose that a field access expression T.super.f appears within class C, and the immediate superclass of the class denoted by T is a class whose fully qualified name is S. If f in S is accessible from C, then T.super.f is treated as if it had been the expression this.f in the body of class S. Otherwise, a compile-time error occurs.

Thus, T.super.f can access the field f that is accessible in class S, even if that field is hidden by a declaration of a field f in class T.

interface I           { int x = 0; }
class T1 implements I { int x = 1; }
class T2 extends T1   { int x = 2; }
class T3 extends T2 {
    int x = 3;
    void test() {
        System.out.println("x=\t\t"          + x);
        System.out.println("super.x=\t\t"    + super.x);
        System.out.println("((T2)this).x=\t" + ((T2)this).x);
        System.out.println("((T1)this).x=\t" + ((T1)this).x);
        System.out.println("((I)this).x=\t"  + ((I)this).x);
    }
}
class Test {
    public static void main(String[] args) {
        new T3().test();
    }
}

x=              3
super.x=        2
((T2)this).x=   2
((T1)this).x=   1
((I)this).x=    0

15.12 Method Invocation Expressions

15.12.3 Compile-Time Step 3: Is the Chosen Method Appropriate?

If there is a most specific method declaration for a method invocation, it is called the compile-time declaration for the method invocation.

It is a compile-time error if an argument to a method invocation is not compatible with its target type, as derived from the invocation type of the compile-time declaration.

If the compile-time declaration is applicable by variable arity invocation, then where the last formal parameter type of the invocation type of the method is F_n[], it is a compile-time error if the type which is the erasure of F_n is not accessible (6.6) at the point of invocation.

If the compile-time declaration is void, then the method invocation must be a top level expression (that is, the Expression in an expression statement or in the ForInit or ForUpdate part of a for statement), or a compile-time error occurs. Such a method invocation produces no value and so must be used only in a situation where a value is not needed.

In addition, whether the compile-time declaration is appropriate may depend on the form of the method invocation expression before the left parenthesis, as follows:

• If the form is MethodName - that is, just an Identifier - and the compile-time declaration is an instance method, then:

  • It is a compile-time error if the method invocation occurs in a static context (8.1.3).

  • Otherwise, let T be the class or interface to search (15.12.1). It is a compile-time error if either the method invocation occurs in an early construction context (8.8.7) of class T, or the innermost enclosing class or interface declaration of the method invocation is neither T nor an inner class of T.

• If the form is TypeName . [TypeArguments] Identifier, then the compile-time declaration must be static, or a compile-time error occurs.

• If the form is ExpressionName . [TypeArguments] Identifier or Primary . [TypeArguments] Identifier, then the compile-time declaration must not be a static method declared in an interface, or a compile-time error occurs.

• If the form is super . [TypeArguments] Identifier, then:

  • It is a compile-time error if the compile-time declaration is abstract.

  • It is a compile-time error if the method invocation occurs in a static context or in an early construction context of the current class.

• If the form is TypeName . super . [TypeArguments] Identifier, then:

  • It is a compile-time error if the compile-time declaration is abstract.

  • It is a compile-time error if the method invocation occurs in a static context or in an early construction context of the current class.

  • If TypeName denotes a class C, then if the class or interface declaration immediately enclosing the method invocation is not C or an inner class of C, a compile-time error occurs.

  • If TypeName denotes an interface, let E be the class or interface declaration immediately enclosing the method invocation. A compile-time error occurs if there exists a method, distinct from the compile-time declaration, that overrides (9.4.1) the compile-time declaration from a direct superclass or direct superinterface of E.

    In the case that a superinterface overrides a method declared in a grandparent interface, this rule prevents the child interface from "skipping" the override by simply adding the grandparent to its list of direct superinterfaces. The appropriate way to access functionality of a grandparent is through the direct superinterface, and only if that interface chooses to expose the desired behavior. (Alternately, the programmer is free to define an additional superinterface that exposes the desired behavior with a super method invocation.)

The compile-time parameter types and compile-time result are determined as follows:

• If the compile-time declaration for the method invocation is not a signature polymorphic method, then:

  • The compile-time parameter types are the types of the formal parameters of the compile-time declaration.

  • The compile-time result is the result of the invocation type of the compile-time declaration (15.12.2.6).

• If the compile-time declaration for the method invocation is a signature polymorphic method, then:

  • The compile-time parameter types are the types of the actual argument expressions. An argument expression which is the null literal null (3.10.8) is treated as having the type Void.

  • The compile-time result is determined as follows:

    • If the signature polymorphic method is either void or has a return type other than Object, the compile-time result is the result of the invocation type of the compile-time declaration (15.12.2.6).

    • Otherwise, if the method invocation expression is an expression statement, the compile-time result is void.

    • Otherwise, if the method invocation expression is the operand of a cast expression (15.16), the compile-time result is the erasure of the type of the cast expression (4.6).

    • Otherwise, the compile-time result is the signature polymorphic method's return type, Object.

A method is signature polymorphic if all of the following are true:

• It is declared in the java.lang.invoke.MethodHandle class or the java.lang.invoke.VarHandle class.

• It has a single variable arity parameter (8.4.1) whose declared type is Object[].

• It is native.

The following compile-time information is then associated with the method invocation for use at run time:

• The name of the method.

• The qualifying class or interface of the method invocation (13.1).

• The number of parameters and the compile-time parameter types, in order.

• The compile-time result.

• The invocation mode, computed as follows:

  • If the compile-time declaration has the static modifier, then the invocation mode is static.

  • Otherwise, if the part of the method invocation before the left parenthesis is of the form super . Identifier or of the form TypeName . super . Identifier, then the invocation mode is super.

  • Otherwise, if the qualifying class or interface of the method invocation is in fact an interface, then the invocation mode is interface.

  • Otherwise, the invocation mode is virtual.

If the result of the invocation type of the compile-time declaration is not void, then the type of the method invocation expression is obtained by applying capture conversion (5.1.10) to the return type of the invocation type of the compile-time declaration.

15.13 Method Reference Expressions

A method reference expression is used to refer to the invocation of a method without actually performing the invocation. Certain forms of method reference expression also allow class instance creation (15.9) or array creation (15.10) to be treated as if it were a method invocation.

MethodReference:

ExpressionName :: [TypeArguments] Identifier

Primary :: [TypeArguments] Identifier

ReferenceType :: [TypeArguments] Identifier

super :: [TypeArguments] Identifier

TypeName . super :: [TypeArguments] Identifier

ClassType :: [TypeArguments] new

ArrayType :: new

If TypeArguments is present to the right of ::, then it is a compile-time error if any of the type arguments are wildcards (4.5.1).

If a method reference expression has the form ExpressionName :: [TypeArguments] Identifier or Primary :: [TypeArguments] Identifier, it is a compile-time error if the type of the ExpressionName or Primary is not a reference type.

If a method reference expression has the form super :: [TypeArguments] Identifier, let E be the class or interface declaration immediately enclosing the method reference expression. It is a compile-time error if E is the class Object or if E is an interface.

If a method reference expression has the form TypeName . super :: [TypeArguments] Identifier, then:

• If TypeName denotes a class, C, then it is a compile-time error if C is not a lexically enclosing class of the current class, or if C is the class Object.

• If TypeName denotes an interface, I, then let E be the class or interface declaration immediately enclosing the method reference expression. It is a compile-time error if I is not a direct superinterface of E, or if there exists some other direct superclass or direct superinterface of E, J, such that J is a subclass or subinterface of I.

• If TypeName denotes a type variable, then a compile-time error occurs.

If a method reference expression has the form super :: [TypeArguments] Identifier or TypeName . super :: [TypeArguments] Identifier, it is a compile-time error if the expression occurs in a static context (8.1.3) or in an early construction context (8.8.7) of the current class.

If a method reference expression has the form ClassType :: [TypeArguments] new, then:

• ClassType must name a class that is accessible (6.6), non-abstract, and not an enum class, or a compile-time error occurs.

• If ClassType denotes a parameterized type (4.5), then it is a compile-time error if any of its type arguments are wildcards.

• If ClassType denotes a raw type (4.8), then it is a compile-time error if TypeArguments is present after the ::.

If a method reference expression has the form ArrayType :: new, then ArrayType must denote a type that is reifiable (4.7), or a compile-time error occurs.

The target reference of an instance method (15.12.4.1) may be provided by the method reference expression using an ExpressionName, a Primary, or super, or it may be provided later when the method is invoked. The immediately enclosing instance of a new inner class instance (15.9.2) is provided by a lexically enclosing instance of this (8.1.3).

When more than one member method of a type has the same name, or when a class has more than one constructor, the appropriate method or constructor is selected based on the functional interface type targeted by the method reference expression, as specified in 15.13.1.

If a method or constructor is generic, the appropriate type arguments may either be inferred or provided explicitly. Similarly, the type arguments of a generic type mentioned by the method reference expression may be provided explicitly or inferred.

Method reference expressions are always poly expressions (15.2).

It is a compile-time error if a method reference expression occurs in a program in someplace other than an assignment context (5.2), an invocation context (5.3), or a casting context (5.5).

Evaluation of a method reference expression produces an instance of a functional interface type (9.8). This does not cause the execution of the corresponding method; instead, the execution may occur at a later time when an appropriate method of the functional interface is invoked.

Here are some method reference expressions, first with no target reference and then with a target reference:

String::length             // instance method
System::currentTimeMillis  // static method
List<String>::size  // explicit type arguments for generic type
List::size          // inferred type arguments for generic type
int[]::clone
T::tvarMember

System.out::println
"abc"::length
foo[x]::bar
(test ? list.replaceAll(String::trim) : list) :: iterator
super::toString

Here are some more method reference expressions:

String::valueOf       // overload resolution needed
Arrays::sort          // type arguments inferred from context
Arrays::<String>sort  // explicit type arguments

Here are some method reference expressions that represent a deferred creation of an object or an array:

ArrayList<String>::new     // constructor for parameterized type
ArrayList::new             // inferred type arguments
                           // for generic class
Foo::<Integer>new          // explicit type arguments
                           // for generic constructor
Bar<String>::<Integer>new  // generic class, generic constructor
Outer.Inner::new           // inner class constructor
int[]::new                 // array creation

It is not possible to specify a particular signature to be matched, for example, Arrays::sort(int[]). Instead, the functional interface provides argument types that are used as input to the overload resolution algorithm (15.12.2). This should satisfy the vast majority of use cases; when the rare need arises for more precise control, a lambda expression can be used.

The use of type argument syntax in the class name before a delimiter (List<String>::size) raises the parsing problem of distinguishing between < as a type argument bracket and < as a less-than operator. In theory, this is no worse than allowing type arguments in cast expressions; however, the difference is that the cast case only comes up when a ( token is encountered; with the addition of method reference expressions, the start of every expression is potentially a parameterized type.

15.13.1 Compile-Time Declaration of a Method Reference

The compile-time declaration of a method reference expression is the method to which the expression refers. In special cases, the compile-time declaration does not actually exist, but is a notional method that represents a class instance creation or an array creation. The choice of compile-time declaration depends on a function type targeted by the expression, just as the compile-time declaration of a method invocation depends on the invocation's arguments (15.12.3).

The search for a compile-time declaration mirrors the process for method invocations in 15.12.1 and 15.12.2, as follows:

• First, a type to search is determined:

  • If the method reference expression has the form ExpressionName :: [TypeArguments] Identifier or Primary :: [TypeArguments] Identifier, the type to search is the type of the expression preceding the :: token.

  • If the method reference expression has the form ReferenceType :: [TypeArguments] Identifier, the type to search is the result of capture conversion (5.1.10) applied to ReferenceType.

  • If the method reference expression has the form super :: [TypeArguments] Identifier, the type to search is the superclass type of the immediately enclosing class or interface declaration of the method reference expression.

    Let T be the class or interface declaration immediately enclosing the method reference expression. It is a compile-time error if T is the class Object or an interface.

  • If the method reference expression has the form TypeName . super :: [TypeArguments] Identifier, then if TypeName denotes a class, the type to search is the superclass type of the named class; otherwise, TypeName denotes an interface to search.

    It is a compile-time error if TypeName is neither a lexically enclosing class or interface declaration of the method reference expression, nor a direct superinterface of the immediately enclosing class or interface declaration of the method reference expression.

    It is a compile-time error if TypeName is the class Object.

    It is a compile-time error if TypeName is an interface, and there exists some other direct superclass or direct superinterface of the immediately enclosing class or interface declaration of the method reference expression, J, such that J is a subclass or subinterface of TypeName.

  • For the two other forms (involving :: new), the referenced method is notional and there is no type to search.

• Second, given a targeted function type with n parameters, a set of potentially applicable methods is identified:

  • If the method reference expression has the form ReferenceType :: [TypeArguments] Identifier, then the potentially applicable methods are:

    • the member methods of the type to search that would be potentially applicable (15.12.2.1) for a method invocation which names Identifier, has arity n, has type arguments TypeArguments, and appears in the same class as the method reference expression; plus

    • the member methods of the type to search that would be potentially applicable for a method invocation which names Identifier, has arity n-1, has type arguments TypeArguments, and appears in the same class as the method reference expression.

    Two different arities, n and n-1, are considered, to account for the possibility that this form refers to either a static method or an instance method.

  • If the method reference expression has the form ClassType :: [TypeArguments] new, then the potentially applicable methods are a set of notional methods corresponding to the constructors of ClassType.

    If ClassType is a raw type, but is not a non-static member type of a raw type, the candidate notional member methods are those specified in 15.9.3 for a class instance creation expression that uses <> to elide the type arguments to a class. Otherwise, the candidate notional member methods are the constructors of ClassType, treated as if they were methods with return type ClassType.

    Among these candidates, the potentially applicable methods are the notional methods that would be potentially applicable for a method invocation which has arity n, has type arguments TypeArguments, and appears in the same class as the method reference expression.

  • If the method reference expression has the form ArrayType :: new, a single notional method is considered. The method has a single parameter of type int, returns the ArrayType, and has no throws clause. If n = 1, this is the only potentially applicable method; otherwise, there are no potentially applicable methods.

  • For all other forms, the potentially applicable methods are the member methods of the type to search that would be potentially applicable for a method invocation which names Identifier, has arity n, has type argument TypeArguments, and appears in the same class as the method reference expression.

• Finally, if there are no potentially applicable methods, then there is no compile-time declaration.

  Otherwise, given a targeted function type with parameter types P₁, ..., P_n and a set of potentially applicable methods, the compile-time declaration is selected as follows:

  • If the method reference expression has the form ReferenceType :: [TypeArguments] Identifier, then two searches for a most specific applicable method are performed. Each search is as specified in 15.12.2.2 through 15.12.2.5, with the clarifications below. Each search produces a set of applicable methods and, possibly, designates a most specific method of the set. In the case of an error as specified in 15.12.2.4, the set of applicable methods is empty. In the case of an error as specified in 15.12.2.5, there is no most specific method.

    In the first search, the method reference is treated as if it were an invocation with argument expressions of types P₁, ..., P_n. Type arguments, if any, are given by the method reference expression.

    In the second search, if P₁, ..., P_n is not empty and P₁ is a subtype of ReferenceType, then the method reference expression is treated as if it were a method invocation expression with argument expressions of types P₂, ..., P_n. If ReferenceType is a raw type, and there exists a parameterization of this type, G<...>, that is a supertype of P₁, the type to search is the result of capture conversion (5.1.10) applied to G<...>; otherwise, the type to search is the same as the type of the first search. Type arguments, if any, are given by the method reference expression.

    If the first search produces a most specific method that is static, and the set of applicable methods produced by the second search contains no non-static methods, then the compile-time declaration is the most specific method of the first search.

    Otherwise, if the set of applicable methods produced by the first search contains no static methods, and the second search produces a most specific method that is non-static, then the compile-time declaration is the most specific method of the second search.

    Otherwise, there is no compile-time declaration.

  • For all other forms of method reference expression, one search for a most specific applicable method is performed. The search is as specified in 15.12.2.2 through 15.12.2.5, with the clarifications below.

    The method reference is treated as if it were an invocation with argument expressions of types P₁, ..., P_n; the type arguments, if any, are given by the method reference expression.

    If the search results in an error as specified in 15.12.2.2 through 15.12.2.5, or if the most specific applicable method is static, there is no compile-time declaration.

    Otherwise, the compile-time declaration is the most specific applicable method.

It is a compile-time error if a method reference expression has the form ReferenceType :: [TypeArguments] Identifier, and the compile-time declaration is static, and ReferenceType is not a simple or qualified name (6.2).

It is a compile-time error if the method reference expression has the form super :: [TypeArguments] Identifier or TypeName . super :: [TypeArguments] Identifier, and the compile-time declaration is abstract.

It is a compile-time error if the method reference expression has the form super :: [TypeArguments] Identifier or TypeName . super :: [TypeArguments] Identifier, and the method reference expression occurs in a static context (8.1.3) or in an early construction context (8.8.7) of the current class.

It is a compile-time error if the method reference expression has the form TypeName . super :: [TypeArguments] Identifier, and TypeName denotes a class C, and the immediately enclosing class or interface declaration of the method reference expression is not C or an inner class of C.

It is a compile-time error if the method reference expression has the form TypeName . super :: [TypeArguments] Identifier, and TypeName denotes an interface, and there exists a method, distinct from the compile-time declaration, that overrides the compile-time declaration from a direct superclass or direct superinterface of the class or interface whose declaration immediately encloses the method reference expression (8.4.8, 9.4.1).

It is a compile-time error if the method reference expression is of the form ClassType :: [TypeArguments] new and a compile-time error would occur when determining an enclosing instance for ClassType as specified in 15.9.2 (treating the method reference expression as if it were an unqualified class instance creation expression).

A method reference expression of the form ReferenceType :: [TypeArguments] Identifier can be interpreted in different ways. If Identifier refers to an instance method, then the implicit lambda expression has an extra parameter compared to if Identifier refers to a static method. It is possible for ReferenceType to have both kinds of applicable methods, so the search algorithm described above identifies them separately, since there are different parameter types for each case.

An example of ambiguity is:

interface Fun<T,R> { R apply(T arg); }

class C {
    int size() { return 0; }
    static int size(Object arg) { return 0; }

    void test() {
        Fun<C, Integer> f1 = C::size;
          // Error: instance method size()
          // or static method size(Object)?
    }
}

This ambiguity cannot be resolved by providing an applicable instance method which is more specific than an applicable static method:

interface Fun<T,R> { R apply(T arg); }

class C {
    int size() { return 0; }
    static int size(Object arg) { return 0; }
    int size(C arg) { return 0; }

    void test() {
        Fun<C, Integer> f1 = C::size;
          // Error: instance method size()
          // or static method size(Object)?
    }
}

The search is smart enough to ignore ambiguities in which all the applicable methods (from both searches) are instance methods:

interface Fun<T,R> { R apply(T arg); }

class C {
    int size() { return 0; }
    int size(Object arg) { return 0; }
    int size(C arg) { return 0; }

    void test() {
        Fun<C, Integer> f1 = C::size;
          // OK: reference is to instance method size()
    }
}

For convenience, when the name of a generic type is used to refer to an instance method (where the receiver becomes the first parameter), the target type is used to determine the type arguments. This facilitates usage like Pair::first in place of Pair<String,Integer>::first. Similarly, a method reference like Pair::new is treated like a "diamond" instance creation (new Pair<>()). Because the "diamond" is implicit, this form does not instantiate a raw type; in fact, there is no way to express a reference to the constructor of a raw type.

For some method reference expressions, there is only one possible compile-time declaration with only one possible invocation type (15.12.2.6), regardless of the targeted function type. Such method reference expressions are said to be exact. A method reference expression that is not exact is said to be inexact.

A method reference expression ending with Identifier is exact if it satisfies all of the following:

• If the method reference expression has the form ReferenceType :: [TypeArguments] Identifier, then ReferenceType does not denote a raw type.

• The type to search has exactly one member method with the name Identifier that is accessible to the class or interface in which the method reference expression appears.

• This method is not variable arity (8.4.1).

• If this method is generic (8.4.4), then the method reference expression provides TypeArguments.

A method reference expression of the form ClassType :: [TypeArguments] new is exact if it satisfies all of the following:

• The type denoted by ClassType is not raw, or is a non-static member type of a raw type.

• The type denoted by ClassType has exactly one constructor that is accessible to the class or interface in which the method reference expression appears.

• This constructor is not variable arity.

• If this constructor is generic, then the method reference expression provides TypeArguments.

A method reference expression of the form ArrayType :: new is always exact.

Chapter 16: Definite Assignment

Every local variable declared by a statement (14.4.2, 14.14.1, 14.14.2, 14.20.3) and every blank final field (4.12.4, 8.3.1.2) must have a definitely assigned value when any access of its value occurs.

An access to its value consists of the simple name of the variable (or, for a field, the simple name of the field qualified by this) occurring anywhere in an expression except as the left-hand operand of the simple assignment operator = (15.26.1).

For every access of a local variable declared by a statement x, or blank final field x, x must be definitely assigned before the access, or a compile-time error occurs.

Similarly, every blank final variable must be assigned at most once; it must be definitely unassigned when an assignment to it occurs.

Such an assignment is defined to occur if and only if either the simple name of the variable (or, for a field, its simple name qualified by this) occurs on the left hand side of an assignment operator.

For every assignment to a blank final variable, the variable must be definitely unassigned before the assignment, or a compile-time error occurs.

Similarly, for every alternate constructor invocation (8.8.7.1) occurring in a constructor of a class C, every blank final instance variable of C declared in C must be definitely unassigned after the argument list of the alternate constructor invocation, or a compile-time error occurs.

Note that local variables declared by a pattern (14.30) are not subject to the rules of definite assignment. Every local variable declared by a pattern is initialized by the process of pattern matching and so always has a value when accessed.

The remainder of this chapter is devoted to a precise explanation of the words "definitely assigned before" and "definitely unassigned before".

...

16.2 Definite Assignment and Statements

16.2.2 Blocks

• A blank final member field V is definitely assigned (and moreover is not definitely unassigned) before the block (14.2) that is the body of any method in the scope of V and before the declaration of any class declared within the scope of V.

• A local variable V declared by a statement S is definitely unassigned (and moreover is not definitely assigned) before the block that is the body of the constructor, method, instance initializer or static initializer which contains S.

• Let C be a class declared within the scope of V. Then V is definitely assigned before the block that is the body of any constructor, method, instance initializer, or static initializer declared in C iff V is definitely assigned before the declaration of C.

  Note that there are no rules that would allow us to conclude that V is definitely unassigned before the block that is the body of any constructor, method, instance initializer, or static initializer declared in C. We can informally conclude that V is not definitely unassigned before the block that is the body of any constructor, method, instance initializer, or static initializer declared in C, but there is no need for such a rule to be stated explicitly.

• V is [un]assigned after an empty block iff V is [un]assigned before the empty block.

• V is [un]assigned after a non-empty block iff V is [un]assigned after the last statement in the block.

• V is [un]assigned before the first statement of the block iff V is [un]assigned before the block.

• V is [un]assigned before any other statement S of the block iff V is [un]assigned after the statement immediately preceding S in the block.

We say that V is definitely unassigned everywhere in a block B iff:

• V is definitely unassigned before B.

• V is definitely assigned after e in every assignment expression V = e, V += e, V -= e, V *= e, V /= e, V %= e, V <<= e, V >>= e, V >>>= e, V &= e, V |= e, or V ^= e that occurs in B.

• V is definitely assigned before every expression ++V, --V, V++, or V-- that occurs in B.

These conditions are counterintuitive and require some explanation. Consider a simple assignment V = e. If V is definitely assigned after e, then either:

• The assignment occurs in dead code, and V is vacuously definitely assigned. In this case, the assignment will not actually take place, and we can assume that V is not being assigned by the assignment expression. Or:

• V was already assigned by an earlier expression prior to e. In this case the current assignment will cause a compile-time error.

So, we can conclude that if the conditions are met by a program that causes no compile time error, then any assignments to V in B will not actually take place at run time.

16.9 Definite Assignment, Constructors, and Instance Initializers

Let C be a class declared within the scope of V. Then:

• V is definitely assigned before a constructor declaration (8.8.7) or an instance variable initializer (8.3.2) of C iff V is definitely assigned before the declaration of C.

  Note that there are no rules that would allow us to conclude that V is definitely unassigned before an the constructor declaration or instance variable initializer. We can informally conclude that V is not definitely unassigned before any constructor declaration or instance variable initializer of C, but there is no need for such a rule to be stated explicitly.

Let C be a class, and let V be a blank final non-static member field of C, declared in C. Then:

• V is definitely unassigned (and moreover is not definitely assigned) before the declaration of any constructor in C.

• V is definitely unassigned (and moreover is not definitely assigned) before the leftmost instance initializer (8.6) or instance variable initializer of C iff V is definitely unassigned after every superclass constructor invocation (8.8.7.1) in the constructors of C.

• V is definitely assigned (and moreover is not definitely unassigned) before the leftmost instance initializer (8.6) or instance variable initializer of C iff C declares at least one constructor, every constructor of C has an explicit constructor invocation, and V is definitely assigned after every superclass constructor invocation in these constructors.

• V is [un]assigned before an instance initializer or instance variable initializer of C other than the leftmost iff V is [un]assigned after the preceding instance initializer or instance variable initializer of C.

The following rules hold within the constructors (8.8.7) of class C: