Java Method Overloading
and LiveConnect 3

1 Motivation

The Netscape JVM always enumerated methods using the order in which they appeared in their classfile, so rearrangement of methods in the Java source files was often required to invoke the desired method.  This behavior was sometimes painful to developers, both because source was not always available and because the static nature of this method resolution algorithm sometimes made it impossible to choose a different method resolution at each invocation site.  Most importantly, the willingness of LiveConnect to convert method arguments from JavaScript types to wildly different Java types sometimes lead to unexpected method resolutions.  A more serious problem has cropped up recently with Netscape's migration to 3rd-party JVM's: the enumeration order of methods is not defined by the Java specification, so overloaded method resolution can occur differently depending on which vendor's JVM is being used in conjunction with LiveConnect.  It is these latter two difficulties which are addressed by this proposal for LiveConnect version 3 (LC3).

2 Introduction

First, Java method signatures distinguish between a variety of numeric types, i.e. byte, char, short, int, long, float, double.  JavaScript collapses all numeric types, whether integral or floating point, into a single number type.  Given this Java class declaration:

class Ambiguous {
   static public int numericArg(int x)   { return 1; }
   static public int numericArg(byte x)  { return 2; }
   static public int numericArg(float x) { return 3; }
}

Packages.Ambiguous.numericArg(3);

3 Resolution of Java Methods from JavaScript

Although the the choice of method to be invoked may be different in LC3 compared to earlier versions of LiveConnect, the permitted conversions of JavaScript arguments to Java types has not been changed.  Hence, backward compatibility is preserved for invocations of non-overloaded methods or in cases where only a single method is compatible with the argument types used.

3.1 Method Accessibility and Applicability

• The method is public.

• If the invocation is a static invocation, the method must be a static method. If the invocation is an instance invocation, the method must not be static.

• The number of parameters in the method declaration equals the number of argument expressions in the method invocation.

• The type of each actual argument can be converted by LiveConnect method invocation conversion (See Section 3.3).

3.2 Choose the Preferred Method

Suppose that U and S are both applicable methods for an invocation, each having n parameters.  Suppose, moreover, that the Java types of the parameters for method U are u₁,...,u_n and the Java types of  the parameters for method S are s₁,...,s_n. Finally, the runtime JavaScript types of the actual arguments are t₁,...,t_n. Then the method U is preferred over method S iff

• u_j and s_j are the same type, or

• conversion to type u_j is preferred to the conversion to type s_j when converting from t_j

for all j from 1 to n.

3.3 Allowed Method Argument Conversions

3.3.1 undefined

¹There is some ambiguity to the result because the JS string literal "undefined" and the undefined JS value are both converted to the same Java string, but this wart is necessary to maintain backward compatibility with LC1.  Really, it would be best if conversion from JS undefined to all Java types caused an error.

3.3.2 Boolean

²Each argument conversion must result in a new java.lang.Boolean instance.  For example, it is not permitted to always use java.lang.Boolean.TRUE and java.lang.Boolean.FALSE.

3.3.3 Number

³In pre-LC3 versions of LiveConnect, conversion from either NaN's or numbers with a magnitude too large to be represented in the target integral type was ill-defined and had platform-dependent behavior.

3.3.4 Strings

⁵Conversion added in LiveConnect version 2.

3.3.5 Null

3.3.6 Object

3.3.6.1 JavaObject (A Java object wrapped inside a JS object)

3.3.6.2 JavaArray (A Java array wrapped inside a JS object)

3.3.6.3 JavaClass

3.3.6.4 JavaScript Array

3.3.6.5 Other JavaScript Objects

3.4 Preferred Argument Conversions

3.4.1 undefined

3.4.2 Boolean

3.4.3 Number

Rationale: The preference for floating-point types over integral types is likely to be the largest culprit in exposing incompatibilities with earlier versions of LiveConnect.  However, double is the only primitive Java type guaranteed not to overflow or lose precision when converting from a JS number, so it should be preferred to the other Java numeric types.

3.4.4 Strings

3.4.5 Null

3.4.6 Object

3.4.6.1 JavaObject (A Java object wrapped inside a JS object)

⁶Among Java reference types, further processing is required.  Intuitively, the rule for preference among Java types when converting from a Java object that is wrapped in a JS object is that the most specific class or interface is preferred.  More formally, let T be the  Java class of an unwrapped JavaObject. Let S and U be class or interface types.  S is preferred to U iff

• An instance of T is assignable to a variable of type S, i.e. T instanceof S is true

• An instance of S is assignable to a variable of type U, i.e. S instanceof U is true

• S and U are not the same types

3.4.6.2 JavaArray (A Java array wrapped inside a JS object)

3.4.6.2 JavaClass

3.4.6.3 JavaScript Array

3.4.6.4 Other JavaScript Objects

4 Explicit Method Specification

class Ambiguous {
   static public int numericArg(int x, byte y) { return 1; }
   static public int numericArg(byte x, char y) { return 2; }
   static public int numericArg(float x, int y) { return 3; }
}

intNumericArg = Packages.Ambiguous["numericArg(int,byte)"];
intNumericArg(5); // returns 1

The same effect can be achieved without using a temporary value to hold the method:

Packages.Ambiguous["numericArg(int,byte)"](5); // returns 1

new java.lang.String["(char[])"](c);