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
Version 0.6.2. Copyright © 2012 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 cannot, 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 Java 7 most-specific analysis was defined as a pairwise comparison of method declarations. Here, we augment the analysis to take into account certain information from the invocation site as well. Specifically:

• If an argument is a lambda expression or method reference that cannot yet be typed due to unfinished inference (thus, the method is considered provisionally applicable), we conservatively make no attempt to compare the two methods; typically, an ambiguity error would be the result.
• If an argument is a lambda expression or method reference, and if both target types are functional interfaces with matching descriptor parameter types, then the descriptor return types may be compared. For example, a descriptor returning String is considered better than a descriptor returning Object or void.
• If an argument produces a primitive value, a primitive type is considered better than a reference type; the opposite is true for arguments producing reference values.

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 expessions 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]

Although the method invocation may be a poly expression, only its argument expressions—not its 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 cannot, 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 function type (9.8) if all of the following are true: [jsr335-15.12.2.1-10-A]
  • The arity of the targeted functional interface's function descriptor is the same as the arity of the lambda expression. [jsr335-15.12.2.1-10-A1]
  • If the functional interface's function descriptor 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 functional interface's function descriptor 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.28) is potentially compatible with a function type if, based on the method searches described in 15.28.1, there exists at least one potentially-applicable compile-time declaration for the method reference. [jsr335-15.12.2.1-10-B]

  Where the method reference has the form ReferenceType :: NonWildTypeArguments_opt Identifier and the target functional interface has one or more parameters, two searches are performed, regardless of the type of the first parameter. [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 poly conditional expression (15.25.3) 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:

1. 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

Let m be a potentially applicable method (15.12.2.1), 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, 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, e_i is compatible in a strict invocation context with F_i. [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.

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), 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, 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, e_i is compatible in a loose invocation context with F_i. [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, 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]
  • Where the last formal parameter type of m is F_n[], the type which is the erasure of F_n[R₁:=U₁, ..., R_p:=U_p] is accessible at the point of invocation. [jsr335-15.12.2.4-10-B3]
  • 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: [jsr335-15.12.2.4-10-C]
  • For 1 ≤ i ≤ k, e_i is compatible in a loose invocation context with T_i. [jsr335-15.12.2.4-10-C1]
  • Where the last formal parameter type of m is F_n[], the type which is the erasure of F_n is accessible at the point of invocation. [jsr335-15.12.2.4-10-C3]

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.

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 a lambda expression argument (15.27) 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 both of the following are true: [jls-15.12.2.5-200]

• If the invocation does not provide type arguments, it is not the case that either m₁ or m₂ is generic and was determined to be only provisionally applicable by 18.5.1. [jsr335-15.12.2.5-200-A]
• Either: [jsr335-15.12.2.5-200-D]
  • 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 T₁, ..., T_n and m₂ has parameter types S₁, ..., S_n, for all i (1 ≤ i ≤ n), the type T_i is more specific than S_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 T₁, ..., T_k and the first k variable-arity parameter types of m₂ are S₁, ..., S_k, for all i (1 ≤ i ≤ k), the type T_i is more specific than S_i for argument exp_i. [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 T is more specific than a type S for an expression exp according to the following rules: [jsr335-15.12.2.5-10]

• T is more specific than S for any expression if T <: S. [jsr335-15.12.2.5-10-A]
• T is more specific than S for a standalone expression (15.2) of a primitive type if T is a primitive type and S is a reference type. [jsr335-15.12.2.5-10-B]
• T is more specific than S for a standalone expression of a reference type if T is a reference type and S is a primitive type. [jsr335-15.12.2.5-10-C]
• T is more specific than S for a parenthesized expression (15.8.5) if T is more specific than S for the contained expression. [jsr335-15.12.2.5-10-D]
• T is more specific than S for a poly conditional expression (15.25.3) if T is more specific than S for each of the second and third operand expressions. [jsr335-15.12.2.5-10-E]
• T is more specific than S for a lambda expression (15.27) if all of the following are true: [jsr335-15.12.2.5-10-F]
  • T and S are function types (9.8). [jsr335-15.12.2.5-10-F1]
  • The functional interface named by T is neither a subinterface nor a superinterface of S. [jsr335-15.12.2.5-10-F2]
  • If the lambda expression's parameters have inferred types, then the descriptor parameter types of T are the same as the descriptor parameter types of S. [jsr335-15.12.2.5-10-F3]
  • Either i) the descriptor return type of S is void, or ii) for all result expressions in the lambda body (or for the body itself if the body is an expression), the descriptor return type of the capture of T is more specific than the descriptor return type of S. [jsr335-15.12.2.5-10-F4]
• T is more specific than S for a method reference expression (15.28) if all of the following are true: [jsr335-15.12.2.5-10-G]
  • T and S are function types. [jsr335-15.12.2.5-10-G1]
  • The functional interface named by T is neither a subinterface nor a superinterface of S. [jsr335-15.12.2.5-10-G2]
  • The descriptor parameter types of T are the same as the descriptor parameter types of S. [jsr335-15.12.2.5-10-G3]
  • Either i) the descriptor return type of S is void, or ii) the descriptor return type of the capture of T is more specific than the descriptor return type of S for an invocation expression of the same form as the method reference. [jsr335-15.12.2.5-10-G4]
• T is more specific than S for a poly method invocation expression (15.12) or a poly class instance creation expression (15.9) if T is a reference type and S is a primitive type. [jsr335-15.12.2.5-10-H]

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. Here, we augment the analysis to take into account certain information from the invocation site as well. Specifically:

   • If an argument is a lambda expression that cannot yet be typed due to unfinished inference (thus, the method is considered provisionally applicable), we conservatively make no attempt to compare the two methods; typically, an ambiguity error would be the result.
   • If an argument is a lambda expression or method reference, and if both target types are functional interfaces with matching descriptor parameter types, then the descriptor return types may be compared. For example, a descriptor returning String is considered better than a descriptor returning Object or void.
   • If an argument produces a primitive value, a primitive type is considered better than a reference type; the opposite is true for arguments producing reference values.

2. While these enhancements are designed with lambda expressions and method references in mind, there are a few side effects that impact code that makes no use of these features:

   • Methods that require boxing or unboxing but that don't require as much of it as an alternative may be preferred.
   • The final parameter of variable-arity methods, if the invocation expression provides zero arguments for that parameter, is no longer used for comparison.

   If these changes raise sufficiently serious backwards-compatibility concerns, adjustments can be made to minimize them.

3. 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 unchecked conversion was necessary for the method to be applicable, then the invocation result type is the erasure (4.6) of the method's declared return type. [jsr335-15.12.2.6-10-B]
• 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. The invocation type is obtained by applying the substitution [P₁:=T₁, ..., P_p:=T_p] to the method's type. [jsr335-15.12.2.6-10-C]
• 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.