Pass Data to Java Methods

MATLAB Type to Java Type Mapping

When you pass MATLAB^® data as arguments to Java^® methods, MATLAB converts the data into types that best represent the data to the Java language. For information about type mapping when passing data to arguments of type java.lang, see Pass Java Objects.

Each row in the following table shows a MATLAB type followed by the possible Java argument matches, from left to right in order of closeness of the match. The MATLAB types (except cell arrays) can be scalar (1-by-1) arrays or matrices. The Java types can be scalar values or arrays.

MATLAB Argument	Java Parameter Type (Scalar or Array) Types Other Than Object Closest Type <———————————————————————> Least Close Type
`logical`	`boolean`	`byte`	`short`	`int`	`long`	`float`	`double`
`double`	`double`	`float`	`long`	`int`	`short`	`byte`	`boolean`
`single`	`float`	`double`
`uint8` `int8`	`byte`	`short`	`int`	`long`	`float`	`double`
`uint16` `int16`	`short`	`int`	`long`	`float`	`double`
`uint32` `int32`	`int`	`long`	`float`	`double`
`uint64` `int64`	`long`	`float`	`double`
`string` scalar, character vector, `char` scalar	`String`
`string` array, cell array of character vectors See Pass String Arguments.	`String[]`
Java object of type `jClass`	Java `Object` of type `jClass`	any superclass of `jClass`
cell array of object	`Object[]`
MATLAB object	Unsupported

How Array Dimensions Affect Conversion

The term dimension means the number of subscripts required to address the elements of an array. For example, a 5-by-1 array has one dimension, because you index individual elements using one array subscript.

In converting MATLAB to Java arrays, MATLAB handles dimension in a special manner. For a MATLAB array, dimension is the number of nonsingleton dimensions in the array. For example, a 10-by-1 array has dimension 1. Whereas, a 1-by-1 array has dimension 0 because you cannot index into a scalar value. In Java code, the number of nested arrays determines the dimension. For example, double[][] has dimension 2, and double has dimension 0.

If the number of dimensions of the Java array matches the number of dimensions in MATLAB array n, then the converted Java array has n dimensions. If the Java array has fewer than n dimensions, then the conversion drops singleton dimensions, starting with the first one. The conversion stops when the number of remaining dimensions matches the number of dimensions in the Java array. If the Java array has more than n dimensions, then MATLAB adds trailing singleton dimensions.

Convert Numbers to Integer Arguments

When passing an integer type to a Java method that takes a Java integer parameter, the MATLAB conversion is the same as the Java conversion between integer types. In particular, if the integer is out-of-range, it does not fit into the number of bits of the parameter type. For out-of-range integers, MATLAB discards all lowest n bits. The value n is the number of bits in the parameter type. This conversion is unlike the conversion between MATLAB integer types, where out-of-range integers are converted to the maximum or minimum value represented by the destination type.

If the argument is a floating-point number, then MATLAB does not convert it to an integer in the same manner as Java. MATLAB first converts a floating-point number to a 64-bit signed integer with the fractional part truncated. Then the number is processed as if it were an int64 argument.

A floating-point number is too large to be represented in a 64-bit integer when it is (outside the range from -2⁶³–2⁶³. In which case, MATLAB uses the following conversions:

int, short, and byte parameter values to 0.
long parameter values to java.lang.Long.MIN_VALUE.
Inf and -Inf values to -1.
NaN values to 0.

Pass String Arguments

To call a Java method with an argument defined as java.lang.String, pass a MATLAB string or character vector. MATLAB converts the argument to a Java String object. You also can pass a String object returned by a Java method.

If the method argument is an array of type String, then pass a string array or a cell array of character vectors. MATLAB converts the input to a Java array of String objects, with dimensions adjusted as described in How Array Dimensions Affect Conversion.

Pass Java Objects

To call a method that has an argument belonging to a Java class (other than java.lang.Object), you must pass a Java object that is an instance of that class. MATLAB does not support Java autoboxing, the automatic conversion of MATLAB types to Java Object types. For example, MATLAB does not convert double to java.lang.Double for a parameter of type Double.

Pass `java.lang.Object`

A special case exists when the method takes an argument of the java.lang.Object class. Since this class is the root of the Java class hierarchy, you can pass objects of any class in the argument. MATLAB automatically converts the argument to the closest Java Object type, which might include Java-style autoboxing. This table shows the conversion.

MATLAB Argument	Java `Object` in Package `java.lang`
`logical`	`Boolean`
`double`	`Double`
`single`	`Float`
`char` scalar	`Character`
`string` scalar nonempty `char` vector	`String`
`uint8` `int8`	`Byte`
`uint16` `int16`	`Short`
`uint32` `int32`	`Integer`
`uint64` `int64`	`Long`
`string` array (nonscalar) cell array of character vectors	`String[]`
Java object	Argument unchanged
cell array	`Object[]`
MATLAB object	Unsupported

Pass Array of Objects

To call a method with an argument defined as java.lang.Object or an array of java.lang.Object, pass either a Java array or a MATLAB cell array. MATLAB automatically converts the cell array elements to their Java types as described in the Pass java.lang.Object table. A Java array is an array returned from a Java constructor. You also can construct a Java array in MATLAB using the javaArray function.

Pass Cell Array of Java Objects

To create a cell array of Java objects, use the MATLAB syntax {a1,a2,...}. You index into a cell array of Java objects in the usual way, with the syntax a{m,n,...}. For example, create cell array A:

a1 = java.lang.Double(100);
a2 = java.lang.Float(200);
A = {a1,a2}

A =

  1×2 cell array

    [1×1 java.lang.Double]    [1×1 java.lang.Float]

Pass Empty Matrices, Nulls, and Missing Values

MATLAB converts an empty matrix as follows.

If the argument is an empty character vector and the parameter is declared as String, then MATLAB passes in an empty (not null) Java String object.
For all other cases, MATLAB converts an empty array to a Java null.

Empty (0-length) Java arrays remain unchanged.

MATLAB converts <missing> values in strings to null.

Overloaded Methods

When calling an overloaded method on a Java object, MATLAB compares the arguments you pass to the arguments defined for the methods. In this context, the term method includes constructors. MATLAB determines the method to call and converts the arguments to Java types according to the Java conversion rules. For more information, see Pass Array of Objects.

When you call a Java method, MATLAB ensures that:

The object or class (for a static method) has a method by that name.
The invocation passes the same number of arguments of at least one method with that name.
Each passed argument is converted to the Java type defined for the method.

If all these conditions are satisfied, then 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 methods that have argument types incompatible with the passed arguments. For example, if the method has a double argument, a char argument is incompatible.

MATLAB then selects the method 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. For information about array dimensionality, see How Array Dimensions Affect Conversion. If two methods have the same fitness, then the first one defined in the Java class is chosen.