Handling Data Returned from a Java Method

On this page…
Introduction Conversion of Java Return Types Built-In Types Java Objects Converting Objects to MATLAB Types

Introduction

In many cases, data returned from a Java method is incompatible with the types operated on in the MATLAB environment. When this is the case, MATLAB converts the returned value to a type native to the MATLAB language. This section describes the conversion performed on the various types that can be returned from a call to a Java method.

Back to Top

Conversion of Java Return Types

The following table lists Java return types and the resulting MATLAB types. For some Java base return types, MATLAB treats scalar and array returns differently, as described following the table.

Conversion of Java Types to MATLAB Types

Java Return Type	If Scalar Return, Resulting MATLAB Type	If Array Return, Resulting MATLAB Type
boolean	logical	logical
byte	double	int8
short	double	int16
int	double	int32
long	double	int64
float	double	single
double	double	double
char	char	char

Note   MATLAB converts rectangular Java arrays to arrays of the resulting type. When Java returns a nonrectangular (jagged) array, MATLAB converts it to a cell array. For more information, see How MATLAB Software Represents the Java Array.

Back to Top

Built-In Types

Java built-in types are described in Passing Built-In Types. This type includes boolean, byte, short, long, int, double, float, and char. When the value returned from a method call is one of these types, MATLAB software converts it according to the table Conversion of Java Types to MATLAB Types.

A single numeric or boolean value converts to a 1-by-1 matrix of double, which is convenient for use in MATLAB. An array of a numeric or boolean return values converts to an array of the closest base type to minimize the required storage space. Array conversions are listed in the right-hand column of the table.

A return value of Java type char converts to a 1-by-1 matrix of char. An array of Java char converts to a MATLAB array of that type.

Back to Top

Java Objects

When a method call returns Java objects, the MATLAB software leaves them in their original form. They remain as Java objects so you can continue to use them to interact with other Java methods.

The only exception to this is when the method returns data of type java.lang.Object. This class is the root of the Java class hierarchy and is frequently used as a catchall for objects and arrays of various types. When the method being called returns a value of the Object class, MATLAB converts its value according to the table Conversion of Java Types to MATLAB Types. That is, numeric and boolean objects such as java.lang.Integer or java.lang.Boolean convert to a 1-by-1 MATLAB matrix of double. Object arrays of these types convert to the MATLAB types listed in the right-hand column of the table. Other object types are not converted.

Back to Top

Converting Objects to MATLAB Types

With the exception of objects of class Object, MATLAB does not convert Java objects returned from method calls to a native MATLAB type. If you want to convert Java object data to a form more readily usable in MATLAB, there are a few MATLAB functions that enable you to do this. These are described in the following sections.

• Converting to the MATLAB double Type

• Converting to the MATLAB char Type

• Converting to a MATLAB Structure

• Converting to a MATLAB Cell Array

Converting to the MATLAB double Type

Using the double function in MATLAB, you can convert any Java object or array of objects to the MATLAB double type. The action taken by the double function depends on the class of the object you specify:

• If the object is an instance of a numeric class (java.lang.Number or one of the classes that inherit from that class), MATLAB uses a preset conversion algorithm to convert the object to a MATLAB double.

• If the object is not an instance of a numeric class, MATLAB checks the class definition to see if it implements a method called toDouble. MATLAB uses toDouble to perform its conversion of Java objects to the MATLAB double type. If such a method is implemented for this class, MATLAB executes it to perform the conversion.

• If you are using a class of your own design, you can write your own toDouble method to perform conversions on objects of that class to a MATLAB double. This enables you to specify your own means of type conversion for objects belonging to your own classes.

  Note   If the class of the specified object is not java.lang.Number, does not inherit from that java.lang.Number, and does not implement a toDouble method, then an attempt to convert the object using the double function results in a MATLAB error message.

The syntax for the double command is as follows, where object is a Java object or Java array of objects:

double(object);

Converting to the MATLAB char Type

With the MATLAB char function, you can convert java.lang.String objects and arrays to MATLAB character arrays.

The syntax for the char command is as follows, where object is a Java object or Java array of objects:

char(object);

If the object specified in the char command is not an instance of the java.lang.String class, MATLAB checks its class to see if it implements a method named toChar. If this is the case, MATLAB executes the toChar method of the class to perform the conversion. If you write your own class definitions, you can make use of this feature by writing a toChar method that performs the conversion according to your own needs.

Note   If the class of the specified object is not java.lang.String and it does not implement a toChar method, an attempt to convert the object using the char function results in a MATLAB error message.

Converting to a MATLAB Structure

Java objects are similar to the MATLAB structure in that many of an object's characteristics are accessible via field names defined within the object. You might want to convert a Java object into a MATLAB structure to facilitate the handling of its data in MATLAB. Use the MATLAB struct function to do this.

The syntax for the struct command is as follows, where object is a Java object or a Java array of objects:

struct(object);

The following example converts a java.awt.Polygon object into a MATLAB structure. You can access the fields of the object directly using MATLAB structure operations. The last line indexes into the array, pstruct.xpoints, to deposit a new value into the third array element.

polygon = java.awt.Polygon([14 42 98 124], [55 12 -2 62], 4);

pstruct = struct(polygon)
pstruct = 
    npoints: 4
    xpoints: [4x1 int32]
    ypoints: [4x1 int32]

pstruct.xpoints
ans =
    14
    42
    98
   124

pstruct.xpoints(3) = 101;

Converting to a MATLAB Cell Array

Use the cell function to convert a Java array or Java object into a MATLAB cell array. Elements of the resulting cell array are of the MATLAB type (if any) closest to the Java array elements or Java object.

The syntax for the cell command is as follows, where object is a Java object or a Java array of objects.

cell(object);

The following example uses the cell command to create a MATLAB cell array in which each cell holds an array of a different type.

import java.lang.* java.awt.*;

% Create a Java array of double
dblArray = javaArray('java.lang.Double', 1, 10);
for m = 1:10
   dblArray(1, m) = Double(m * 7);
end

% Create a Java array of points
ptArray = javaArray('java.awt.Point', 3);
ptArray(1) = Point(7.1, 22);
ptArray(2) = Point(5.2, 35);
ptArray(3) = Point(3.1, 49);

% Create a Java array of strings
strArray = javaArray('java.lang.String', 2, 2);
strArray(1,1) = String('one');    strArray(1,2) = String('two');
strArray(2,1) = String('three');  strArray(2,2) = String('four');

% Convert each to cell arrays
cellArray = {cell(dblArray), cell(ptArray), cell(strArray)}
cellArray = 
    {1x10 cell}    {3x1 cell}    {2x2 cell}

cellArray{1,1}       % Array of type double
ans = 

   [7]   [14]   [21]   [28]   [35]   [42]   [49]   [56]   [63]   [70]

cellArray{1,2}       % Array of type Java.awt.Point

ans = 
    [1x1 java.awt.Point]
    [1x1 java.awt.Point]
    [1x1 java.awt.Point]

cellArray{1,3}       % Array of type char array

ans = 
    'one'      'two' 
    'three'    'four'

Back to Top

Passing Data to a Java Method

Introduction to Programming Examples

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS