External Interfaces/API

Passing Data to Overloaded Methods

When you invoke an overloaded method on a Java object, MATLAB determines which method to invoke by comparing the arguments your call passes to the arguments defined for the methods. Note that in this discussion, the term method includes constructors. When it determines the method to call, MATLAB converts the calling arguments to Java method types according to Java conversion rules, except for conversions involving objects or cell arrays. See Passing Objects in an Array.

How MATLAB Determines the Method to Call

When your MATLAB function calls a Java method, MATLAB:

1. Checks to make sure that the object (or class, for a static method) has a method by that name
2. Determines whether the invocation passes the same number of arguments of at least one method with that name
3. Makes sure that each passed argument can be converted to the Java type defined for the method

If all of the preceding conditions are satisfied, MATLAB calls the method.

In a call to an overloaded method, if there is more than one candidate, MATLAB selects the one with arguments that best fit the calling arguments. First, MATLAB rejects all methods that have any argument types that are incompatible with the passed arguments (for example, if the method has a double argument and the passed argument is a char).

Among the remaining methods, MATLAB selects the one with the highest fitness value, which is the sum of the fitness values of all its arguments. The fitness value for each argument is the fitness of the base type minus the difference between the MATLAB array dimension and the Java array dimension. (Array dimensionality is explained in How Array Dimensions Affect Conversion.) If two methods have the same fitness, the first one defined in the Java class is chosen.

Example - Calling an Overloaded Method

Suppose a function constructs a java.io.OutputStreamWriter object, osw, and then invokes a method on the object.

• osw.write('Test data', 0, 9);
  

MATLAB finds that the class java.io.OutputStreamWriter defines three write methods.

• public void write(int c);
  public void write(char[] cbuf, int off, int len);
  public void write(String str, int off, int len);
  

MATLAB rejects the first write method, because it takes only one argument. Then, MATLAB assesses the fitness of the remaining two write methods. These differ only in their first argument, as explained below.

In the first of these two write methods, the first argument is defined with base type, char. The table, Conversion of MATLAB Types to Java Types, shows that for the type of the calling argument (MATLAB char), Java type, char, has a value of 6. There is no difference between the dimension of the calling argument and the Java argument. So the fitness value for the first argument is 6.

In the other write method, the first argument has Java type String, which has a fitness value of 7. The dimension of the Java argument is 0, so the difference between it and the calling argument dimension is 1. Therefore, the fitness value for the first argument is 6.

Because the fitness value of those two write methods is equal, MATLAB calls the one listed first in the class definition, with char[] first argument.

Other Data Conversion Topics

Handling Data Returned from a Java Method