When you call a Java^{®} method, MATLAB^{®} types you pass in the call are converted to types native to the Java language. MATLAB performs this conversion on each argument that is passed, except for those arguments that are already Java objects. This section describes the conversion that is performed on specific MATLAB types and, at the end, also looks at how argument types affect calls made to overloaded methods.
If the method returns data, MATLAB converts the data to the appropriate MATLAB format. This process is covered in Handle Data Returned from Java Methods.
MATLAB converts MATLAB data, passed as arguments to Java methods,
into types that best represent the data to the Java language.
The following table shows all of the MATLAB base types for passed
arguments and the Java types defined for the parameters. Each
row 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 all be scalar (1
by1
)
arrays or matrices. All of the Java types can be scalar values
or arrays.
Conversion of MATLAB Types to Java Types
MATLAB Argument  Java Parameter Type (Scalar or Array)  

Closest Type <———————————————————————> Least Close Type  


















 


 


 

 






 





 




 



 
cell array of character vectors 
 
Java object 
 
cell array of 
 
MATLAB object  Unsupported 
For more information about type conversion of arguments passed to Java code, see:
The Java language has eight types that are intrinsic to
the language and are not represented as Java objects. These are
often referred to as built in, or elemental,
types and they include boolean
, byte
, short
, long
, int
, double
, float
,
and char
. MATLAB converts its own types to
these Java builtin types according to the table, Conversion of MATLAB Types to Java Types.
Builtin types are in the first 10 rows of the table.
When a Java method you are calling expects one of these types, you can pass it the type of MATLAB argument shown in the leftmost column of the table. If the method takes an array of one of these types, you can pass a MATLAB array of the type. MATLAB converts the type of the argument to the type assigned in the method declaration.
The following MATLAB code creates a toplevel window frame
and sets its dimensions. The call to setBounds
passes
four MATLAB scalars of the double
type to
the inherited Java Frame method, setBounds
,
that takes four arguments of the int
type. MATLAB converts
each 64bit double type to a 32bit integer before calling the method.
The setBounds
method declaration:
public void setBounds(int x, int y, int width, int height)
The MATLAB code that calls the method:
frame = java.awt.Frame; setBounds(frame,200,200,800,400) setVisible(frame,1)
To call a Java method with an argument defined as an array of
a builtin type, you can create and pass a MATLAB matrix with
a compatible base type. The following code defines a polygon by sending
four x
and y
coordinates to
the Polygon constructor. Two 1
by4
MATLAB arrays
of double
are passed to java.awt.Polygon
,
which expects integer
arrays in the first two arguments.
Shown here is the Java method declaration followed by MATLAB code
that calls the method, and then verifies the set coordinates.
public Polygon(int xpoints[], int ypoints[], int npoints) poly = java.awt.Polygon([14 42 98 124], [55 12 2 62], 4); [poly.xpoints poly.ypoints] % Verify the coordinates ans = 14 55 42 12 98 2 124 62
Since MATLAB arrays are passed by value, any changes that a Java method makes to them are not visible to your MATLAB code. To access changes that a Java method makes to an array, then, rather than passing a MATLAB array, create and pass a Java array, which is a reference. For a description of using Java arrays in MATLAB, see Java Arrays.
Note: Generally, it is preferable to have methods return data that has been modified using the return argument mechanism as opposed to passing a reference to that data in an argument list. 
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 outofrange (does not fit into the number of bits
of the parameter type), MATLAB discards all lowest n
bits,
where n
is the number of bits in the parameter
type. This is unlike conversion between MATLAB integer types,
where outofrange integers are converted to the maximum or minimum
value represented by the destination type.
If the argument is floating point, MATLAB does not convert
to an integer in the same manner as Java. A floating point number
is first converted to a 64bit signed integer with the fractional
part truncated and then processed as if it were an int64
argument.
When a floating point number is too large to be represented in a 64bit integer (outside the range from 2^{63}–2^{63}), MATLAB converts the value as follows:
Convert int
, short
,
and byte
parameter values to 0
.
Convert long
parameter values to java.lang.Long.MIN_VALUE
.
Convert Inf
and Inf
values
to 1
.
Convert NaN
values to 0
.
To call a Java method that has an argument defined as an
object of class java.lang.String
, you can pass
either a String
object that was returned from an
earlier Java call or a MATLAB 1
byn
character vector. If you pass the
character vector, MATLAB converts it to a Java object
of java.lang.String
for you.
For a programming example, see Read URL Using java.net.URL
. This example shows
a MATLAB character array that holds a URL being passed to the Java URL
class
constructor. The following constructor expects a Java String
argument.
public URL(String spec) throws MalformedURLException
In the MATLAB call to
this constructor, a character array specifying the URL is passed. MATLAB converts
this array to a Java String
object before
calling the constructor.
url = java.net.URL('http://archive.ncsa.uiuc.edu/demoweb/')
When the method you are calling expects an argument of an array
of type String
, you can create such an array by
packaging the character vectors together
in a MATLAB cell array. The character vectors can be of varying
lengths since you are storing them in different cells of the array.
As part of the method call, MATLAB converts the cell array to
a Java array of String
objects.
In the following example, the echoPrompts
method
of a userwritten class accepts a string array argument that MATLAB converted
from its original format as a cell array of character vectors. The parameter list
in the Java method appears as follows:
public String[] echoPrompts(String s[])
You create the input argument by storing both character vectors in
a MATLAB cell array. MATLAB converts this cell array to a Java array
of String
.
myaccount.echoPrompts({'Username: ','Password: '}) ans = 'Username: ' 'Password: '
When
calling a method that has a parameter 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 automatically
convert MATLAB types to Java Object
types.
Unlike Java, MATLAB does not do autoboxing for numbers,
such as converting double
to Double
.
In
the example below, the add
method belonging to
the java.awt.Menu
class requires, as an argument,
an object of the java.awt.MenuItem
class. The method
declaration is:
public MenuItem add(MenuItem mi)
The example operates on the frame created in the previous example
in Passing BuiltIn Types. The
second, third, and fourth lines of code shown here add items to a
menu to be attached to the existing window frame. In each of these
calls to menu1.add
, an object that is an instance
of the java.awt.MenuItem
Java class is passed.
menu1 = java.awt.Menu('File Options'); menu1.add(java.awt.MenuItem('New')); menu1.add(java.awt.MenuItem('Open')); menu1.add(java.awt.MenuItem('Save')); menuBar=java.awt.MenuBar; menuBar.add(menu1); frame.setMenuBar(menuBar);
A special case exists when the method being called 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. When passing a MATLAB argument,
the argument is automatically converted to the closest Java Object
type,
which might include Javastyle autoboxing, as shown in the following
table.
MATLAB Argument  Java 



















cell array of character vectors 

Java object 

cell array of 

MATLAB object  Unsupported 
The only types of object arrays that you can pass to Java methods
are Java arrays and MATLAB cell arrays. MATLAB automatically
converts the cell array elements to java.lang.Object
class
objects. In order for a cell array to be passed from MATLAB,
the corresponding argument in the Java method signature must
specify java.lang.Object
or an array of java.lang.Object
.
If the objects are already in a Java array, either an array
returned from a Java constructor or constructed in MATLAB by
the javaArray
function, then
you simply pass it as the argument to the method being called. MATLAB does
not convert the argument, because the argument is already a Java array.
The following example shows the mapPoints
method
of a userwritten class accepting an array of java.awt.Point
objects.
The declaration for this method is:
public Object mapPoints(java.awt.Point p[])
The following MATLAB code creates a 4
by1
array
containing four Java Point
objects. When the
array is passed to the mapPoints
method, no conversion
is necessary because the javaArray
function created
a Java array of java.awt.Point
objects.
pointObj = javaArray('java.awt.Point',4); pointObj(1) = java.awt.Point(25,143); pointObj(2) = java.awt.Point(31,147); pointObj(3) = java.awt.Point(49,151); pointObj(4) = java.awt.Point(52,176); testData.mapPoints(pointObj);
You create a cell array of Java objects by using the MATLAB syntax {a1,a2,...}
.
You index into a cell array of Java objects in the usual way,
with the syntax a{m,n,...}
.
The following example creates a cell array of two Frame
objects, frame1
and frame2
,
and assigns it to variable frameArray
.
frame1 = java.awt.Frame('Frame A'); frame2 = java.awt.Frame('Frame B'); frameArray = {frame1, frame2}
frameArray = [1x1 java.awt.Frame] [1x1 java.awt.Frame]
The next statement assigns element {1,2}
of
the cell array frameArray
to variable f
.
f = frameArray {1,2}
f = java.awt.Frame[frame2,0,0,0x0,invalid,hidden,layout = java.awt.BorderLayout,resizable,title=Frame B]
There are several remaining items of interest regarding the way MATLAB converts its data to a compatible Java type. This includes how MATLAB matches array dimensions, and how it handles empty matrices and empty character vectors.
The term dimension refers to the number
of subscripts required to address the elements of an array. For example,
a 5
by1
array has one dimension,
because you can index individual elements using only one array subscript.
In converting MATLAB to Java arrays, MATLAB handles
dimension in a special manner. For a MATLAB array, dimension
can be considered as the number of nonsingleton dimensions in the
array. For example, a 10
by1
array
has dimension 1, and a 1
by1
array
has dimension 0. In Java code, dimension is determined solely
by the number of nested arrays. For example, double[][]
has
dimension 2, and double
has dimension 0.
If the number of dimensions of the Java array exactly matches
the MATLAB array's number of dimensions n
,
the conversion results in a Java array with n
dimensions.
If the Java array has fewer than n
dimensions,
the conversion drops singleton dimensions, starting with the first
one, until the number of remaining dimensions matches the number of
dimensions in the Java array.
An empty matrix is converted to a Java null
.
The empty character (''
)
in MATLAB translates into an empty (not null
) String
object
in Java code. Empty (0
length) Java arrays
remain unchanged.
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. 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.
When your MATLAB function calls a Java method, MATLAB:
Checks to make sure that the object (or class, for a static method) has a method by that name.
Determines whether the invocation passes the same number of arguments of at least one method with that name.
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
type).
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.
Suppose that 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.