Data Conversion with Java and MATLAB Types

Working with MATLAB Data Types

There are many data types that you can work with in MATLAB^®. Each of these data types is in the form of a matrix or array. You can build matrices and arrays of floating-point and integer data, characters and strings, and logical true and false states. Structures and cell arrays provide a way to store dissimilar types of data in the same array.

All of the fundamental MATLAB classes are circled in the diagram Fundamental MATLAB Data Types.

The Java^® client follows Java-MATLAB-Interface (JMI) rules for data marshaling. It expands those rules for scalar Java boxed types, allowing auto-boxing and un-boxing, which JMI does not support.

Note

Function Handles are not supported by MATLAB Production Server™.

Fundamental MATLAB Data Types

The expected conversion results for Java to MATLAB types are listed in Conversion of Java Types to MATLAB Types. The expected conversion results for MATLAB to Java types are listed in Conversion of MATLAB Types to Java Types.

Scalar Numeric Type Coercion

Scalar numeric MATLAB types can be assigned to multiple Java numeric types as long as there is no loss of data or precision.

The main exception to this rule is that MATLAB double scalar data can be mapped into any Java numeric type. Because double is the default numeric type in MATLAB, this exception provides more flexibility to the users of MATLAB Production Server Java client API.

MATLAB to Java Numeric Type Compatibility describes the type compatibility for scalar numeric coercion.

MATLAB to Java Numeric Type Compatibility

MATLAB Type	Java Types
uint8	short, int, long, float, double
int8	short, int, long, float, double
uint16	int, long, float, double
int16	int, long, float, double
uint32	long, float, double
int32	long, float, double
uint64	float, double
int64	float, double
single	double
double	byte, short, int, long, float

Dimensionality in Java and MATLAB Data Types

In MATLAB, dimensionality is an attribute of the fundamental types and does not add to the number of types as it does in Java.

In Java, double, double[] and double[][][] are three different data types. In MATLAB, there is only a double data type and possibly a scalar instance, a vector instance, or a multi-dimensional instance.

Java Signature	Value Returned from MATLAB
double[][][] foo()	ones(1,2,3)

Dimension Coercion

How you define your MATLAB function and corresponding Java method signature determines if your output data will be coerced, using padding or truncation.

This coercion is automatically performed for you. This section describes the rules followed for padding and truncation.

 Padding

When a Java method's return type has more dimensions than a MATLAB method's return type, MATLAB dimensions are be padded with ones (1s) to match the required number of output dimensions in Java.

You, as a developer, do not have to do anything to pad dimensions.

The following tables provide examples of how padding is performed for you:

How MATLAB Pads Your Java Method Return Type

When Dimensions in MATLAB are:	And Dimensions in Java are:	This Type in Java:	Returns this Type in MATLAB:
size(a) is[2,3]	Array will be returned as size 2,3,1,1	double [][][][] foo()	function a = foo a = ones(2,3);

Padding Dimensions in MATLAB and Java Data Conversion

MATLAB Array Dimensions	Declared Output Java Type	Output Java Dimensions
2 x 3	double[][][]	2 x 3 x 1
2 x 3	double[][][][]	2 x 3 x 1 x 1

 Truncation

When a Java method's return type has fewer dimensions than a MATLAB method's return type, MATLAB dimensions are truncated to match the required number of output dimensions in Java. This is only possible when extra dimensions for MATLAB array have values of ones (1s) only.

To compute appropriate number of dimensions in Java, excess ones are truncated, in this order:

1. From the end of the array

2. From the array’s beginning

3. From the middle of the array (scanning front-to-back).

You, as a developer, do not have to do anything to truncate dimensions.

The following tables provide examples of how truncation is performed for you:

How MATLAB Truncates Your Java Method Return Type

When Dimensions in MATLAB are:	And Dimensions in Java are:	This Type in Java:	Returns this Type in MATLAB
size(a) is [1,2,1,1,3,1]	Array will be returned as size 2,3	double [][] foo()	function a = foo a = ones(1,2,1,1,3,1);

Following are some examples of dimension shortening using the double numeric type:

Truncating Dimensions in MATLAB and Java Data Conversion

MATLAB Array Dimensions	Declared Output Java Type	Output Java Dimensions
1 x 1	double	0
2 x 1	double[]	2
1 x 2	double[]	2
2 x 3 x 1	double[][]	2 x 3
1 x 3 x 4	double[][]	3 x 4
1 x 3 x 4 x 1 x 1	double[][][]	1 x 3 x 4
1 x 3 x 1 x 1 x 2 x 1 x 4 x 1	double[][][][]	3 x 2 x 1 x 4

Empty (Zero) Dimensions

Passing arrays of zero (0) dimensions (sometimes called empties) results in an empty matrix from MATLAB.

Java Signature	Value Returned from MATLAB
double[] foo()	[]

 Passing Java Empties to MATLAB

When a null is passed from Java to MATLAB, it will always be marshaled into [] in MATLAB as a zero by zero (0 x 0) double. This is independent of the declared input type used in Java. For example, all the following methods can accept null as an input value:

void foo(String input);
void foo(double[] input);
void foo(double[][] input);
void foo(Double input);

And in MATLAB, null will be received as:

[] i.e. 0x0 double

 Passing MATLAB Empties to Java

An empty array in MATLAB has at least one zero (0) assigned in at least one dimension. For function a = foo, for example, any one of the following values is acceptable:

 a = []; 
 a = ones(0);
 a = ones(0,0);
 a = ones(1,2,0,3); 

Empty MATLAB data will be returned to Java as null for all the above cases.

For example, in Java, the following signatures return null when a MATLAB function returns an empty array:

double[] foo();
double[][] foo();
Double foo();

However, when MATLAB returns an empty array and the return type in Java is a scalar primitive (as with double foo();, for example) an exception is thrown . :

IllegalArgumentException
("An empty MATLAB array cannot be represented by a 
  primitive scalar Java type")

Boxed Types

Boxed Types are used to wrap opaque C structures.

Java client will perform primitive to boxed type conversion if boxed types are used as return types in the Java method signature.

Java Signature	Value Returned from MATLAB
Double foo()	1.0

For example, the following method signatures work interchangeably:

double[] foo();         Double[] foo();
double[][][] foo();     Double[][][] foo();

Signed and Unsigned Types in Java and MATLAB Data Types

Numeric classes in MATLAB include signed and unsigned integers. Java does not have unsigned types.