This document proposes changes to the Java Language Specification to improve the usability of the lambda expression language feature. See JEP 302 for an overview.

6.1 Declarations

A declaration introduces an entity into a program and usually includes an identifier (3.8) that can be used in a name to refer to this entity.

This unqualified statement was already incorrect (anonymous classes, for example, are declared but have no name), and will be even more dubious with the introduction of unnamed parameters.

...

6.3 Scope of a Declaration

...

The scope of a named 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 named 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.

...

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) 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, 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 the formal parameter would no longer be visible—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 or lambda expression 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 a class declaration or lambda expression contained by 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 or lambda expression 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 another class declaration or a lambda expression contained by the scope of C.

These rules allow redeclaration of a variable or local class in nested class declarations (local classes (14.3) and anonymous classes (15.9)) and lambda expressions that occur in the scope of the variable or local class. Thus, the declaration of a formal parameter, local variable, or local class may be shadowed in a class declaration or lambda expression nested within a method, constructor, or lambda expression; and the declaration of an exception parameter may be shadowed inside a class declaration or lambda expression 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 restrict the declaration of a member 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).

...

8.4.1 Formal Parameters

The formal parameters of a method or constructor, if any, are specified by a list of comma-separated parameter specifiers. Each parameter specifier consists of a type (optionally preceded by the final modifier and/or one or more annotations) and an identifier (optionally followed by brackets) that specifies the name of the parameter declares a type for the variable and, optionally, a name.

If a method or constructor has no formal parameters, only an empty pair of parentheses appears in the declaration of the method or constructor.

FormalParameterList:

FormalParameters [ , VariableArityParameter ]
VariableArityParameter
ReceiverParameter [ , FormalParameters ] [ , VariableArityParameter ]

FormalParameters:

FormalParameter { , FormalParameter }
ReceiverParameter { , FormalParameter }

FormalParameter:

{ VariableModifier } UnannType VariableDeclaratorId ParameterName [ Dims ]

VariableModifier:

(one of)
Annotation final

ParameterName:

Identifier
_

ReceiverParameter:

{ Annotation } UnannType [ Identifier . ] this

LastFormalParameter: VariableArityParameter:

{ VariableModifier } UnannType { Annotation } ... ParameterName
FormalParameter

This attempts to clean up the somewhat convoluted treatment of receiver parameters and variable-arity parameters in the old grammar. In this presentation, a parameter is always exactly one of a (standard) FormalParameter, a ReceiverParameter, or a VariableArityParameter. The rules for how they are arranged are managed solely by FormalParameterList.

The following production from 4.3 and 8.3 is shown here for convenience:

VariableDeclaratorId:

Identifier [ Dims ]

Dims:

{ Annotation } [ ] { { Annotation } [ ] }

A formal parameter's ParameterName may be an Identifier that names the parameter. If the ParameterName is instead the keyword _, the parameter is an unnamed parameter.

It is a compile-time error if the ParameterName _ is followed by Dims.

The scope and shadowing of a named formal parameter is specified in 6.3 and 6.4. The Identifier that appears as the ParameterName may be used as a simple name in the body of the method or constructor to refer to the formal parameter.

An unnamed parameter has no name or scope (6.3).

This means that the variable cannot be referenced (6.5.6.1). It also means that multiple unnamed parameters can be declared in the same formal parameter list.

Note that an unnamed parameter is still a variable. So, for example, any necessary conversions required by method invocation in order to initialize the variable (5.3) must occur.

For compilation, note that the MethodParameters attribute of the class file already supports unnamed parameters via a zero constant pool pointer (JVMS 4.7.24).

The last formal parameter of a method or constructor is special: it may be a variable arity parameter, indicated by an ellipsis following the type.

Note that the ellipsis (...) is a token unto itself (3.11). It is possible to put whitespace between it and the type, but this is discouraged as a matter of style.

If the last formal parameter is a variable arity parameter, the method is a variable arity method. Otherwise, it is a fixed arity method.

The receiver parameter is an optional syntactic device for an instance method or an inner class's constructor. For an instance method, the receiver parameter represents the object for which the method is invoked. For an inner class's constructor, the receiver parameter represents the immediately enclosing instance of the newly constructed object. Either way, the receiver parameter exists solely to allow the type of the represented object to be denoted in source code, so that the type may be annotated. The receiver parameter is not a formal parameter; more precisely, it is not a declaration of any kind of variable (4.12.3), it is never bound to any value passed as an argument in a method invocation expression or qualified class instance creation expression, and it has no effect whatsoever at run time.

The rules for annotation modifiers on a formal parameter declaration and on a receiver parameter are specified in 9.7.4 and 9.7.5.

It is a compile-time error if final appears more than once as a modifier for a formal parameter declaration.

It is a compile-time error to use mixed array notation (10.2) for a variable arity parameter.

The revised grammar makes this impossible.

The scope and shadowing of a formal parameter is specified in 6.3 and 6.4.

This assertion was moved to an earlier point in this section.

It is a compile-time error for a method or constructor to declare two formal parameters with the same name. (That is, their declarations mention the same Identifier.)

It is a compile-time error if a formal parameter that is declared final is assigned to within the body of the method or constructor.

The declaration final int _ is legal per the FormalParameter grammar rule, even though it's impossible to assign to an unnamed parameter, final or not. We could flag this as an error, but the modifier is harmless and might be relevant in certain use cases involving reflection or debugging.

A receiver parameter may appear only in the FormalParameterList of an instance method or an inner class's constructor; otherwise, a compile-time error occurs.

Where a receiver parameter is allowed, its type and name are specified as follows:

The declared type of a formal parameter depends on whether it is a variable arity parameter:

If the declared type of a variable arity parameter has a non-reifiable element type (4.7), then a compile-time unchecked warning occurs for the declaration of the variable arity method, unless the method is annotated with @SafeVarargs (9.6.4.7) or the unchecked warning is suppressed by @SuppressWarnings (9.6.4.5).

When the method or constructor is invoked (15.12), the values of the actual argument expressions initialize newly created parameter variables, each of the declared type, before execution of the body of the method or constructor. The Identifier that appears in the DeclaratorId may be used as a simple name in the body of the method or constructor to refer to the formal parameter.

This assertion was moved to an earlier point in this section.

Invocations of a variable arity method may contain more actual argument expressions than formal parameters. All the actual argument expressions that do not correspond to the formal parameters preceding the variable arity parameter will be evaluated and the results stored into an array that will be passed to the method invocation (15.12.4.2).

A method or constructor parameter of type float always contains an element of the float value set (4.2.3); similarly, a method or constructor parameter of type double always contains an element of the double value set. It is not permitted for a method or constructor parameter of type float to contain an element of the float-extended-exponent value set that is not also an element of the float value set, nor for a method parameter of type double to contain an element of the double-extended-exponent value set that is not also an element of the double value set.

Where an actual argument expression corresponding to a parameter variable is not FP-strict (15.4), evaluation of that actual argument expression is permitted to use intermediate values drawn from the appropriate extended-exponent value sets. Prior to being stored in the parameter variable, the result of such an expression is mapped to the nearest value in the corresponding standard value set by being subjected to invocation conversion (5.3).

...

10.2 Array Variables

...

The array type of a variable depends on the bracket pairs that may appear as part of the type at the beginning of a variable declaration, or as part of the declarator for the variable following the Identifier naming the variable, or both. Specifically, in the declaration of a field, formal parameter, or local variable (8.3, 8.4.1, 9.3, 9.4, 14.4.1, 14.14.2, 15.27.1), the array type of the variable is denoted by:

...

14.20 The try Statement

A try statement executes a block. If a value is thrown and the try statement has one or more catch clauses that can catch it, then control will be transferred to the first such catch clause. If the try statement has a finally clause, then another block of code is executed, no matter whether the try block completes normally or abruptly, and no matter whether a catch clause is first given control.

TryStatement:

try Block Catches try Block [ Catches ] Finally
TryWithResourcesStatement

Catches:

CatchClause { CatchClause }

CatchClause:

catch ( CatchFormalParameter ) Block

CatchFormalParameter:

{ VariableModifier } CatchType ParameterName

CatchType:

UnannClassType { | ClassType }

Finally:

finally Block

See 8.3 for UnannClassType. The following productions from 4.3, 8.3, and 8.4.1 are shown here for convenience:

VariableModifier:

(one of) Annotation final

VariableDeclaratorId:

Identifier [ Dims ]

Dims:

{ Annotation } [ ] { { Annotation } [ ] }

ParameterName:

Identifier
_

The Block immediately after the keyword try is called the try block of the try statement.

The Block immediately after the keyword finally is called the finally block of the try statement.

A try statement may have catch clauses, also called exception handlers.

A catch clause declares exactly one parameter, which is called an exception parameter.

An exception parameter's ParameterName may be an Identifier that names the parameter. If the ParameterName is instead the keyword _, the parameter is an unnamed parameter.

The scope and shadowing of a named exception parameter is specified in 6.3 and 6.4. The Identifier that appears as the ParameterName may be used as a simple name in the body of the catch clause to refer to the exception parameter.

An unnamed parameter has no name or scope (6.3).

It is a compile-time error if final appears more than once as a modifier for an exception parameter declaration.

The scope and shadowing of an exception parameter is specified in 6.3 and 6.4.

...

15.27.1 Lambda Parameters

The formal parameters of a lambda expression may have either declared types or inferred types. These styles cannot be mixed: it is not possible for a lambda expression to declare the types of some of its parameters but leave others to be inferred. Only parameters with declared types can have modifiers.

LambdaParameters:

Identifier ParameterName
( [ FormalParameterList ] )
( InferredFormalParameterList )

InferredFormalParameterList:

ParameterName { , ParameterName }

The following productions from 4.3 8.3, and 8.4.1 are shown here for convenience:

FormalParameterList:

FormalParameters [ , VariableArityParameter ]
VariableArityParameter
ReceiverParameter [ , FormalParameters ] [ , VariableArityParameter ]

FormalParameters:

FormalParameter { , FormalParameter }
ReceiverParameter { , FormalParameter }

FormalParameter:

{ VariableModifier } UnannType VariableDeclaratorId ParameterName [ Dims ]

LastFormalParameter: VariableArityParameter:

{ VariableModifier } UnannType { Annotation } ... ParameterName
FormalParameter

VariableModifier:

(one of)
Annotation final

ParameterName:

Identifier
_

Dims:

{ Annotation } [ ] { { Annotation } [ ] }

Receiver parameters are not permitted in the FormalParameters of a lambda expression, as specified in 8.4.1.

A lambda expression whose formal parameters have declared types is said to be explicitly typed, while a lambda expression whose formal parameters have inferred types is said to be implicitly typed. A lambda expression with zero parameters is explicitly typed.

If the formal parameters have inferred types, then these types are derived (15.27.3) from the functional interface type targeted by the lambda expression.

The syntax for formal parameters with declared types is the same as the syntax for the parameters of a method declaration (8.4.1).

The declared type of a formal parameter depends on whether it is a variable arity parameter:

No distinction is made between the following lambda parameter lists:

(int... x) -> ..
(int[] x) -> ..

Consistent with the rules for overriding, either can be used, whether the functional interface's abstract method is fixed arity or variable arity. Since lambda expressions are never directly invoked, introducing int... where the functional interface uses int[] can have no impact on the surrounding program. In a lambda body, a variable arity parameter is treated just like an array-typed parameter.

The rules for annotation modifiers on a formal parameter declaration are specified in 9.7.4 and 9.7.5.

It is a compile-time error if final appears more than once as a modifier for a formal parameter declaration.

It is a compile-time error to use mixed array notation (10.2) for a variable arity parameter.

A lambda parameter's ParameterName may be an Identifier that names the parameter. If the ParameterName is instead the keyword _, the parameter is an unnamed parameter.

The scope and shadowing of a formal parameter declaration named lambda parameter is specified in 6.3 and 6.4. The Identifier that appears as the ParameterName may be used as a simple name in the lambda body to refer to the lambda parameter.

An unnamed parameter has no name or scope (6.3).

It is a compile-time error for a lambda expression to declare two formal parameters with the same name. (That is, their declarations mention the same Identifier.)

It is a compile-time error if a receiver parameter (8.4.1) appears in the FormalParameters of a lambda expression.

This is redundant: it was already covered in the note following the grammar rules.

It is a compile-time error if a formal parameter that is declared final is assigned to within the body of the lambda expression.

When the lambda expression is invoked (via a method invocation expression (15.12)), the values of the actual argument expressions initialize newly created parameter variables, each of the declared or inferred type, before execution of the lambda body. The Identifier that appears in the VariableDeclaratorId or the InferredFormalParameterList may be used as a simple name in the lambda body to refer to the formal parameter.

...