Passing Data to a Java Method :: Using Sun Java Classes in MATLAB Software (MATLAB®)

Learn more about MATLAB

Passing Data to a Java Method

On this page…
Introduction Conversion of MATLAB Argument Data Passing Built-In Types Passing String Arguments Passing Java Objects Other Data Conversion Topics Passing Data to Overloaded Methods

On this page…

Introduction

Conversion of MATLAB Argument Data

Passing Built-In Types

Passing String Arguments

Passing Java Objects

Introduction

When you make a call in the MATLAB software to Sun Java code, any 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 takes a look at how argument types affect calls made to overloaded methods.

If data is to be returned by the method being called, MATLAB receives this data and converts it to the appropriate MATLAB format wherever necessary. This process is covered in Handling Data Returned from a Java Method.

Conversion of MATLAB Argument Data

MATLAB data, passed as arguments to Java methods, are converted by MATLAB into types that best represent the data to the Java language. The table below shows all of the MATLAB base types for passed arguments and the Java base types defined for input arguments. 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-by-1) arrays or matrices. All of the Java types can be scalar values or arrays.

Conversion of MATLAB Types to Java Types

MATLAB Argument	Closest Type (7)	Java Input Argument (Scalar or Array)					Least Close Type (1)
`logical`	`boolean`	`byte`	`short`	`int`	`long`	`float`	`double`
`double`	`double`	`float`	`long`	`int`	`short`	`byte`	`boolean`
`single`	`float`	`double`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`
`char`	`String`	`char`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`
`uint8`	`byte`	`short`	`int`	`long`	`float`	`double`	`N/A`
`uint16`	`short`	`int`	`long`	`float`	`double`	`N/A`	`N/A`
`uint32`	`int`	`long`	`float`	`double`	`N/A`	`N/A`	`N/A`
`int8`	`byte`	`short`	`int`	`long`	`float`	`double`	`N/A`
`int16`	`short`	`int`	`long`	`float`	`double`	`N/A`	`N/A`
`int32`	`int`	`long`	`float`	`double`	`N/A`	`N/A`	`N/A`
cell array of `strings`	array of `String`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`
Java object	`Object`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`
cell array of `object`	array of `Object`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`
MATLAB object	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`	`N/A`

Type conversion of arguments passed to Java code are discussed in the following three categories. MATLAB handles each category differently.

Passing Built-In Types

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 software converts its own types to these Java built-in types according to the table, Conversion of MATLAB Types to Java Types. Built-in 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 left-most 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 MATLAB code shown below creates a top-level 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 64-bit double type to a 32-bit integer prior to making the call. Shown here is the setBounds method declaration followed by the MATLAB code that calls the method.

public void setBounds(int x, int y, int width, int height)

frame=java.awt.Frame;
frame.setBounds(200,200,800,400);
frame.setVisible(1);

Passing Built-In Types in an Array

To call a Java method with an argument defined as an array of a built-in 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-by-4 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

MATLAB Arrays Are Passed by Value

Since MATLAB arrays are passed by value, any changes that a Java method makes to them are not visible to your MATLAB code. If you need to access changes that a Java method makes to an array, then, rather than passing a MATLAB array, you should create and pass a Java array, which is a reference. For a description of using Java arrays in MATLAB, see Working with 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.

Passing String Arguments

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-by-n character array. If you pass the character array, MATLAB converts the array to a Java object of java.lang.String for you.

For a programming example, see Example — Reading a URL. This shows a MATLAB character array that holds a URL being passed to the Java URL class constructor. The constructor, shown below, 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 prior to calling the constructor.

url = java.net.URL(... 
     'http://archive.ncsa.uiuc.edu/demoweb/')

Passing Strings in an Array

When the method you are calling expects an argument of an array of type String, you can create such an array by packaging the strings together in a MATLAB cell array. The strings 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 user-written class accepts a string array argument that MATLAB converted from its original format as a cell array of strings. The parameter list in the Java method appears as follows:

public String[] echoPrompts(String s[])

You create the input argument by storing both strings in a MATLAB cell array. MATLAB converts this structure to a Java array of String.

myaccount.echoPrompts({'Username: ','Password: '})
ans = 
'Username: '
'Password: '

Passing Java Objects

When calling a method that has an argument belonging to a particular Java class, you must pass an object that is an instance of that class. 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 for this is:

public MenuItem add(MenuItem mi)

The example operates on the frame created in the previous example in Passing Built-In 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);

Handling Objects of Class java.lang.Object

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. The following hash table example passes objects belonging to different classes to a common method, put, which expects an argument of java.lang.Object. The method declaration for put is:

public synchronized Object put(Object key, Object value)

The following MATLAB code passes objects of different types (boolean, float, and string) to the put method.

hTable = java.util.Hashtable;
hTable.put(0, java.lang.Boolean('TRUE'));
hTable.put(1, java.lang.Float(41.287));
hTable.put(2, java.lang.String('test string'));

hTable                  % Verify hash table contents
hTable =
{1.0=41.287, 2.0=test string, 0.0=true}

When passing arguments to a method that takes java.lang.Object, it is not necessary to specify the class name for objects of a built-in type. Line 3, in the example above, specifies that 41.287 is an instance of class java.lang.Float. You can omit this and simply say, 41.287, as shown in the following example. Thus, MATLAB creates each object for you, choosing the closest matching Java object representation for each argument.

The three calls to put from the preceding example can be rewritten as:

hTable.put(0, 1);
hTable.put(1, 41.287);
hTable.put(2, 'test string');

Passing Objects in an Array

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. Note that 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. No conversion is done by MATLAB, because the argument is already a Java array.

The following example shows the mapPoints method of a user-written class accepting an array of java.awt.Point objects. The declaration for this method is:

public Object mapPoints(java.awt.Point p[])

The MATLAB code shown below creates a 4-by-1 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);

Handling a Cell Array of Java Objects

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]

Passing Data to Overloaded Methods

When you invoke an overloaded method on a Java object, the MATLAB software 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:

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

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.