Lambda Specification, Part F: Overload Resolution

Navigation: Overview - Part A - Part B - Part C - Part D - Part E - Part F - Part G - Part H - Part J
Sections: 15.12.2 - 15.12.2.1 - 15.12.2.2 - 15.12.2.3 - 15.12.2.4 - 15.12.2.5 - 15.12.2.6 - 15.12.3 - 15.9.3
Version 0.9.3. Copyright © 2014 Oracle America, Inc. Legal Notice.

Summary

Method and constructor declarations can be overloaded, meaning multiple matching declarations with different parameter types can co-exist in a type. In order to interpret a method invocation or a class instance creation expression, the compiler performs "overload resolution," inferring the declaration intended by the user at a particular invocation site. This occurs in three steps: i) identifying potentially applicable methods, that is, methods of the appropriate shape; ii) performing type analysis to identify applicable methods for the given arguments; iii) among the applicable methods, choosing one that is most specific.

To accomodate lambda expressions, the definition of potential applicability is expanded to take into account both the arity of the candidate methods and the presence and "shape" of functional interface target types.

To check for applicability, the types of an invocation's arguments can no longer, in general, be inputs to the analysis. This is because:

• The arguments to a method invocation may be poly expressions
• Poly expressions cannot be typed in the absence of a target type
• Overload resolution has to be completed before the arguments' target types will be known

Instead, the input to the applicability check is a list of argument expressions, which can be checked for compatibility with potential target types, even if the ultimate types of the expressions are unknown.

The meaning of an implicitly-typed lambda expression or an inexact method reference is sufficiently vague prior to resolving a target type that arguments containing these expressions are not considered pertinent to applicability; they are simply ignored (except for their expected arity) until overload resolution is finished.

The Java 7 most-specific analysis was defined as a pairwise comparison of method declarations via subtyping. Here, we augment the analysis so that, where the corresponding argument is an explicitly-typed lambda expression or an exact method reference, one functional interface type can be preferred over another if it has a "better" function type return type, by a variety of measures: subtyping, boxing, or void vs. non-void.

15.12.2 Compile-Time Step 2: Determine Method Signature [Modified]

Compare JLS 15.12.2

The second step searches the type determined in the previous step for member methods. This step uses the name of the method and the argument expressions to locate methods that are both accessible and applicable, that is, declarations that can be correctly invoked on the given arguments.

There may be more than one such method, in which case the most specific one is chosen. The descriptor (signature plus return type) of the most specific method is the one used at run time to perform the method dispatch.

A method is applicable if it is either applicable by one of strict invocation (15.12.2.2), applicable by loose invocation (15.12.2.3), or it is an applicable variable arity method invocation (15.12.2.4). [jls-15.12.2-120]

Certain argument expressions that contain implicitly-typed lambda expressions (15.27.1) or inexact method references (15.13.1) are ignored by the applicability tests, because their meaning cannot be determined until a target type is selected.

Although the method invocation may be a poly expression, only its argument expressions—not the invocation's target type—influence the selection of applicable methods.

...

Deciding whether a method is applicable will, in the case of generic methods (8.4.4), require an analysis of the type arguments. Type arguments may be passed explicitly or implicitly. If they are passed implicitly, bounds on the type arguments must be inferred (18) from the types of the argument expressions.

...

Discussion and motivation:

1. To check for applicability, the types of an invocation's arguments can no longer, in general, be inputs to the analysis. This is because:

   • The arguments to a method invocation may be poly expressions
   • Poly expressions cannot be typed in the absence of a target type
   • Overload resolution has to be completed before the arguments' target types will be known

   Instead, the input to the applicability check is a list of argument expressions, which can be checked for compatibility with potential target types, even if the ultimate types of the expressions are unknown.

2. Overload resolution is independent of a target type for two reasons:

   • First, it makes the user model more accessible and less error-prone. The meaning of a method name (i.e., the declaration corresponding to the name) is too fundamental to the meaning of a program to depend on subtle contextual hints. (In contrast, other poly expressions may have different behavior depending on a target type; but the variation in behavior is always limited and essentially equivalent, while no such guarantees can be made about the behavior of an arbitrary set of methods that share a name and arity.)
   • Second, it allows other properties—such as whether or not the method is a poly expression (15.12) or how to categorize a conditional (15.25)—to depend on the meaning of the method name, even before a target type is known.

15.12.2.1 Identify Potentially Applicable Methods [Modified]

Compare JLS 15.12.2.1

...

A member method is potentially applicable to a method invocation if and only if all of the following are true: [jls-15.12.2.1-200]

• The name of the member is identical to the name of the method in the method invocation. [jls-15.12.2.1-200-A]
• The member is accessible (6.6) to the class or interface in which the method invocation appears. [jls-15.12.2.1-200-B]

  Whether a member method is accessible at a method invocation depends on the access modifier (public, none, protected, or private) in the member's declaration and on where the method invocation appears.

• If the member is a fixed arity method with arity n, the arity of the method invocation is equal to n, and for all i, 1 ≤ i ≤ n, the ith argument of the method invocation is potentially compatible, as defined below, with the type of the ith parameter of the method. [jls-15.12.2.1-200-D]
• If the member is a variable arity method with arity n, then for all i, 1 ≤ i ≤ n-1, the ith argument of the method invocation is potentially compatible with the type of the ith parameter of the method; and, where the nth parameter of the method has type T[], one of the following is true: [jls-15.12.2.1-200-C]
  • The arity of the method invocation is equal to n-1. [jsr335-15.12.2.1-200-C1]
  • The arity of the method invocation is equal to n, and the nth argument of the method invocation is potentially compatible with either T or T[]. [jsr335-15.12.2.1-200-C2]
  • The arity of the method invocation is m, where m > n, and for all i, n ≤ i ≤ m, the ith argument of the method invocation is potentially compatible with T. [jsr335-15.12.2.1-200-C3]
• If the method invocation includes explicit type arguments, and the member is a generic method, then the number of type arguments is equal to the number of type parameters of the method. [jls-15.12.2.1-200-E]

...

An expression is potentially compatible with a target type according to the following rules: [jsr335-15.12.2.1-10]

• A lambda expression (15.27) is potentially compatible with a functional interface type (9.8) if all of the following are true: [jsr335-15.12.2.1-10-A]
  • The arity of the targeted type's function type is the same as the arity of the lambda expression. [jsr335-15.12.2.1-10-A1]
  • If the targeted type's function type has a void return, then the lambda body is either a statement expression (14.8) or a void-compatible block (15.27.2). [jsr335-15.12.2.1-10-A2]
  • If the targeted type's function type has a (non-void) return type, then the lambda body is either an expression or a value-compatible block (15.27.2). [jsr335-15.12.2.1-10-A3]
• A method reference (15.13) is potentially compatible with a functional interface type if, where the type's function type arity is n, there exists at least one potentially-applicable method for the method reference at arity n (15.13.1), and one of the following is true: [jsr335-15.12.2.1-10-B]
  • The method reference has the form ReferenceType :: NonWildTypeArguments_opt Identifier and at least one potentially-applicable method either i) is declared static and supports arity n, or ii) is not declared static and supports arity n-1. [jsr335-15.12.2.1-10-B1]
  • The method reference has some other form and at least one potentially-applicable method is not declared static. [jsr335-15.12.2.1-10-B2]
• A lambda expression or a method reference is potentially compatible with a type variable if the type variable is a type parameter of the candidate method. [jsr335-15.12.2.1-10-C]
• A parenthesized expression (15.8.5) is potentially compatible with a type if its contained expression is potentially compatible with that type. [jsr335-15.12.2.1-10-D]
• A conditional expression (15.25) is potentially compatible with a type if each of its second and third operand expressions are potentially compatible with that type. [jsr335-15.12.2.1-10-E]
• A class instance creation expression (15.9), a method invocation expression, or an expression of a standalone form (15.2) is potentially compatible with any type. [jsr335-15.12.2.1-10-F]

If the search does not yield at least one method that is potentially applicable, then a compile-time error occurs. [jls-15.12.2.1-210]

Discussion and motivation:

This definition of potential applicability expands the previous arity check to also take into account the presence and "shape" of functional interface target types.

In some cases involving type argument inference, a lambda expression appearing as a method invocation argument cannot be properly typed until after overload resolution. These rules allow the form of the lambda expression to still be taken into account, discarding obviously incorrect target types that might otherwise cause ambiguity errors.

15.12.2.2 Phase 1: Identify Matching Arity Methods Applicable by Subtyping Strict Invocation [Modified]

Compare JLS 15.12.2.2

An argument expression is considered pertinent to applicability for a potentially-applicable method m unless it has one of the following forms: [jsr335-15.12.2.2-5]

• An implicitly-typed lambda expression (15.27.1). [jsr335-15.12.2.2-5-A]
• An inexact method reference (15.13.1). [jsr335-15.12.2.2-5-B]
• If m is a generic method and the method invocation does not provide explicit type arguments, an explicitly-typed lambda expression or an exact method reference for which the corresponding target type (as derived from the signature of m) is a type parameter of m. [jsr335-15.12.2.2-5-C]
• An explicitly-typed lambda expression whose body is an expression that is not pertinent to applicability. [jsr335-15.12.2.2-5-D]
• An explicitly-typed lambda expression whose body is a block, where at least one result expression is not pertinent to applicability. [jsr335-15.12.2.2-5-E]
• A parenthesized expression (15.8.5) whose contained expression is not pertinent to applicability. [jsr335-15.12.2.2-5-F]
• A conditional expression (15.25) whose second or third operand is not pertinent to applicability. [jsr335-15.12.2.2-5-G]

Let m be a potentially applicable method (15.12.2.1) with arity n, let e₁, ..., e_n be the actual argument expressions of the method invocation, and let A_i be the type of e_i (1 ≤ i ≤ n) F₁, ..., F_n be the types of the formal parameters of m. Then: [jls-15.12.2.2-100]

• If m is a generic method and the method invocation does not provide explicit type arguments, then the applicability of the method is inferred as described in 18.5.1. [jsr335-15.12.2.2-10-A]
• Otherwise, if m is a generic method, then let R₁, ..., R_p (p ≥ 1) be the type parameters of m, and let B_l be the declared bound of R_l (1 ≤ l ≤ p), and let U₁, ..., U_p be the explicit type arguments given in the method invocation. Then m is applicable by strict invocation if: [jsr335-15.12.2.2-10-B]
  • For 1 ≤ i ≤ n, if e_i is pertinent to applicability then e_i is compatible in a strict invocation context with F_i[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.2-10-B1]
  • For 1 ≤ l ≤ p, U_l <: B_l[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.2-10-B2]
• Otherwise, m is applicable by strict invocation if, for 1 ≤ i ≤ n, either e_i is compatible in a strict invocation context with F_i or e_i is not pertinent to applicability. [jsr335-15.12.2.2-10-C]

If no method applicable by strict invocation is found, the search for applicable methods continues with phase 2 (15.12.2.3). [jls-15.12.2.2-120]

Otherwise, the most specific method (15.12.2.5) is chosen among the methods that are applicable by strict invocation. [jls-15.12.2.2-130]

Discussion and motivation:

1. The rules for handling generic method type argument inference, and associated terminology, have become too unwieldy to simply inline in the applicability rules. Instead, in this and the subsequent applicability sections, the inference problem has been factored out to 18.5.1.
2. The meaning of an implicitly-typed lambda expression or an inexact method reference is sufficiently vague prior to resolving a target type that arguments containing these expressions are not considered pertinent to applicability; they are simply ignored (except for their expected arity) until overload resolution is finished.

15.12.2.3 Phase 2: Identify Matching Arity Methods Applicable by Invocation Conversion Loose Invocation [Modified]

Compare JLS 15.12.2.3

Let m be a potentially applicable method (15.12.2.1) with arity n, let e₁, ..., e_n be the actual argument expressions of the method invocation, and let A_i be the type of e_i (1 ≤ i ≤ n) F₁, ..., F_n be the types of the formal parameters of m. Then: [jls-15.12.2.3-100]

• If m is a generic method and the method invocation does not provide explicit type arguments, then the applicability of the method is inferred as described in 18.5.1. [jsr335-15.12.2.3-10-A]
• Otherwise, if m is a generic method, then let R₁, ..., R_p (p ≥ 1) be the type parameters of m, and let B_l be the declared bound of R_l (1 ≤ l ≤ p), and let U₁, ..., U_p be the explicit type arguments given in the method invocation. Then m is applicable by loose invocation if: [jsr335-15.12.2.3-10-B]
  • For 1 ≤ i ≤ n, if e_i is pertinent to applicability (15.12.2.2) then e_i is compatible in a loose invocation context with F_i[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.3-10-B1]
  • For 1 ≤ l ≤ p, U_l <: B_l[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.3-10-B2]
• Otherwise, m is applicable by loose invocation if, for 1 ≤ i ≤ n, either e_i is compatible in a loose invocation context with F_i or e_i is not pertinent to applicability (15.12.2.2). [jsr335-15.12.2.3-10-C]

If no method applicable by loose invocation is found, the search for applicable methods continues with phase 3 (15.12.2.4). [jls-15.12.2.3-120]

Otherwise, the most specific method (15.12.2.5) is chosen among the methods that are applicable by loose invocation. [jls-15.12.2.3-130]

15.12.2.4 Phase 3: Identify Methods Applicable by Variable Arity Methods Invocation [Modified]

Compare JLS 15.12.2.4

Where a variable-arity method has formal parameter types F₁, ..., F_n-1, F_n[], define the ith variable-arity parameter type of the method as follows: [jsr335-15.12.2.4-5]

• For i ≤ n-1, the ith variable-arity parameter type is F_i. [jsr335-15.12.2.4-5-A]
• For i ≥ n, the ith variable-arity parameter type is F_n. [jsr335-15.12.2.4-5-B]

Let m be a potentially applicable method (15.12.2.1) with variable arity, let e₁, ..., e_k be the actual argument expressions of the method invocation and let A_i be the type of e_i (1 ≤ i ≤ k) T₁, ..., T_k be first k variable-arity parameter types of m. Then: [jls-15.12.2.4-100]

• If m is a generic method and the method invocation does not provide explicit type arguments, then the applicability of the method is inferred as described in 18.5.1. [jsr335-15.12.2.4-10-A]
• Otherwise, if m is a generic method, then let R₁, ..., R_p (p ≥ 1) be the type parameters of m, and let B_l be the declared bound of R_l (1 ≤ l ≤ p), and let U₁, ..., U_p be the explicit type arguments given in the method invocation. Then m is an applicable variable-arity method if: [jsr335-15.12.2.4-10-B]
  • For 1 ≤ i ≤ k, if e_i is pertinent to applicability (15.12.2.2) then e_i is compatible in a loose invocation context with T_i[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.4-10-B1]
  • For 1 ≤ l ≤ p, U_l <: B_l[R₁:=U₁, ..., R_p:=U_p]. [jsr335-15.12.2.4-10-B4]
• Otherwise, m is applicable by variable-arity invocation if for 1 ≤ i ≤ k, either e_i is compatible in a loose invocation context with T_i or e_i is not pertinent to applicability (15.12.2.2). [jsr335-15.12.2.4-10-C]

If no method applicable by variable-arity method invocation is found, a compile-time error occurs. [jls-15.12.2.4-120]

Otherwise, the most specific method (15.12.2.5) is chosen among the methods applicable by variable-arity methods invocation. [jls-15.12.2.4-130]

Discussion and motivation:

1. The previous "applicable variable arity method" terminology incorrectly hinted that, if a variable-arity method is applicable in any phase, it is applicable in and only in Phase 3. This overlooks the fact that variable arity methods can act as fixed-arity methods in Phases 1 and 2. What is relevant is the kinds of adaptations actually used to determine applicability, not the kinds of adaptations allowed by the method declaration.
2. The ith variable arity parameter type is a notational shorthand that simplifies the problem of describing all possible ways in which arguments might be matched up with parameter types. This is especially useful in the next section.
3. An access check on the type of the last parameter appeared here previously, but has been moved to 15.12.3.

15.12.2.5 Choosing the Most Specific Method [Modified]

Compare JLS 15.12.2.5

If more than one member method is both accessible and applicable to a method invocation, it is necessary to choose one to provide the descriptor for the run-time method dispatch. The Java programming language uses the rule that the most specific method is chosen.

The informal intuition is that one method is more specific than another if any invocation handled by the first method could be passed on to the other one without a compile-time error. In cases such as an explicitly-typed lambda expression argument (15.27.1) or a variable-arity invocation (15.12.2.4), some flexibility is allowed to adapt one signature to the other.

One fixed-arity member applicable method named m m₁ is more specific than another member applicable method of the same name and arity, m₂, for an invocation with argument expressions exp₁, ..., exp_k, if any of the following are true: [jls-15.12.2.5-200]

• m₂ is generic and m₁ is inferred to be more specific than m₂ for argument expressions exp₁, ..., exp_k by 18.5.4. [jsr335-15.12.2.5-200-B]
• m₂ is not generic, m₁ and m₂ are applicable by strict or loose invocation, and where m₁ has parameter types S₁, ..., S_n and m₂ has parameter types T₁, ..., T_n, for all i (1 ≤ i ≤ n), the type S_i is more specific than T_i for argument exp_i. [jsr335-15.12.2.5-200-C]
• m₂ is not generic, m₁ and m₂ are applicable by variable arity invocation, and where the first k variable-arity parameter types of m₁ are S₁, ..., S_k and the first k variable-arity parameter types of m₂ are T₁, ..., T_k, for all i (1 ≤ i ≤ k), the type S_i is more specific than T_i for argument exp_i; additionally, if m₂ has k+1 parameters, then the k+1th variable-arity parameter type of m₁ is a subtype of the k+1th variable-arity parameter type of m₂. [jsr335-15.12.2.5-300-C]

The above conditions are the only circumstances under which one method may be more specific than another. [jls-15.12.2.5-400]

A type S is more specific than a type T for any expression if S <: T. [jsr335-15.12.2.5-10-A]

In addition, a functional interface type S is more specific than a functional interface type T for an expression exp if T is not a subtype of S and one of the following conditions apply. Let U₁, ..., U_k and R₁ be the parameter types and return type, respectively, of the function type of the capture of S, and let V₁, ..., V_k and R₂ be the parameter types and return type, respectively, of the function type of T. [jsr335-15.12.2.5-10]

• exp is an explicitly-typed lambda expression (15.27.1) and one of the following is true (where result expression is defined in 15.27.2 for a block body, and refers to the body itself for an expression body): [jsr335-15.12.2.5-10-F]
  • R₂ is void. [jsr335-15.12.2.5-10-F5]
  • R₁ <: R₂. [jsr335-15.12.2.5-10-F6]
  • R₁ and R₂ are functional interface types, and R₁ is more specific than R₂ for each result expression. [jsr335-15.12.2.5-10-F7]
  • R₁ is a primitive type, R₂ is a reference type, and each result expression is a standalone expression (15.2) of a primitive type. [jsr335-15.12.2.5-10-F8]
  • R₁ is a reference type, R₂ is a primitive type, and each result expression is either a standalone expression of a reference type or a poly expression. [jsr335-15.12.2.5-10-F9]
• exp is an exact method reference (15.13.1); for all i, 1 ≤ i ≤ k, U_i is the same as V_i; and one of the following is true: [jsr335-15.12.2.5-10-G]
  • R₂ is void. [jsr335-15.12.2.5-10-G5]
  • R₁ <: R₂. [jsr335-15.12.2.5-10-G6]
  • R₁ is a primitive type, R₂ is a reference type, and the compile-time declaration for the method reference has a primitive return type. [jsr335-15.12.2.5-10-G8]
  • R₁ is a reference type, R₂ is a primitive type, and the compile-time declaration for the method reference has a reference return type. [jsr335-15.12.2.5-10-G9]
• exp is a parenthesized expression (15.8.5) and one of these conditions applies recursively to the wrapped expression. [jsr335-15.12.2.5-10-D]
• exp is a conditional expression (15.25.3) and for each of the second and third operands, one of these conditions applies recursively. [jsr335-15.12.2.5-10-E]

A method m₁ is strictly more specific than another method m₂ if and only if m₁ is more specific than m₂ and m₂ is not more specific than m₁. [jls-15.12.2.5-500]

...

Discussion and motivation:

1. The Java 7 most-specific analysis was defined as a pairwise comparison of method declarations via subtyping. Here, we augment the analysis so that, where the corresponding argument is an explicitly-typed lambda expression or an exact method reference, one functional interface type can be preferred over another if it has a "better" function type return type, by a variety of measures: subtyping, boxing, or void vs. non-void.

2. As above, the inference problem associated with the most-specific analysis has been factored out into its own section, 18.5.4.

15.12.2.6 Method Invocation Type Result and Throws Types [Modified]

Compare JLS 15.12.2.6

The invocation type of a most-specific accessible and applicable method is a method type (8.2) expressing the target types of the invocation arguments, the result type of the invocation, and the exception types of the invocation. It is determined as follows: [jsr335-15.12.2.6-10]

• If the chosen method is generic and the method invocation does not provide explicit type arguments, the invocation type is inferred as described in 18.5.2. [jsr335-15.12.2.6-10-A]
• Otherwise, if the chosen method is generic, then for 1 ≤ i ≤ p, let P_i be the formal type parameters of the method, and let T_i be the actual type arguments provided for the method invocation. Apply the substitution [P₁:=T₁, ..., P_p:=T_p] to the method's type. If unchecked conversion was not necessary for the method to be applicable, then this is the invocation type of m; if unchecked conversion was necessary, then this substitution provides the parameter types of the invocation type, while the return type and thrown types are given by the erasure of the method's type (without applying the substitution). [jsr335-15.12.2.6-10-C]
• Otherwise, if unchecked conversion was necessary for the method to be applicable, then the parameter types of the invocation type are the parameter types of the method's type; the result return type and thrown types is are given by the erasure (4.6) of the method's declared return type. [jsr335-15.12.2.6-10-B]
• Otherwise, if the chosen method is the getClass method of the class Object (4.3.2), the method's invocation type is the same as the method's type, except that the return type is Class<? extends T>, where T is the type that was searched, as determined by 15.12.1. [jsr335-15.12.2.6-10-E]
• Otherwise, the method's invocation type is the same as the method's type. [jsr335-15.12.2.6-10-D]

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 chosen method. [jls-15.12.2.6-100-C.1]

The exception types that a method invocation expression can throw are specified in 11.2.1. [jls-15.12.2.6-300]

Discussion and motivation:

1. We introduce invocation type here to group together the return type, exception types, and parameter types. Because poly expressions can appear as method arguments, we need to be more explicit than before about what the target type of a method argument is. This new abstraction also clarifies the interaction with inference (18.5.2), and simplifies the text for this section, which was needlessly concerned with the details of substitution and erasure on lists of types.
2. The return type of the getClass method was already defined in 4.3.2, but the definition was added here for clarity. (In particular, it should be clear that this special return type is also used for method reference compatibility testing (15.13.2).)

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

See JLS 15.12.3

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. [jsr335-15.12.3-10]

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 at the point of invocation. [jsr335-15.12.3-20]

Discussion and motivation:

The JLS 7 version of 15.12.2.4 performed this vararg access check during overload resolution. The check is necessary in order to guarantee that it is possible for the compiler to create an array of the given type. But it creates a soundness problem for inference (18.5.1): how can inference guarantee that an inferred type will be accessible? Thus, the access check is more appropriate as a post-resolution step.

15.9.3 Choosing the Constructor and its Arguments [Addendum]

See JLS 15.9.3

It is a compile-time error if an argument to a class instance creation expression is not compatible with its target type, as derived from the invocation type (15.12.2.6). [jsr335-15.9.3-10]

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

These rules are identical to those for 15.12.3. The same checks should be performed for both constructors and methods.