Skip navigation links

Package com.mathworks.toolbox.javabuilder

This package provides classes that define the rules for data conversion between Java and the MATLAB programming environment.

See: Description

Package com.mathworks.toolbox.javabuilder Description

This package provides classes that define the rules for data conversion between Java and the MATLAB programming environment. It also has a few utility classes that allow you to change the MATLAB (MATLAB Runtime) environment that executes the underlying MATLAB code.

MATLAB data types

In the MATLAB environment, an array is the basic building block for all the data types. There are scalars (1-by-1 matrices), vectors (matrices with only one row or column), matrices (with two dimensions), and multi dimensional arrays with more than two dimensions. MATLAB has other ways of storing both numeric and nonnumeric data, but it is usually best to think of everything as an array.

The main data types offered by MATLAB include logical (boolean), char, numeric, cell, struct (structure), function handles, and Java objects. The numeric data type has subtypes to represent signed and unsigned, integer and floating-point data. Cell and struct are MATLAB specific data types that act as containers for different types of data. Each of the MATLAB data types is in the form of an array that can be a minimum of 0-by-0 in size but can grow to an n-dimensional array of any size. For more information on MATLAB data types, please visit the MathWorks support Web site and refer to the section "Programming Fundamentals".

MATLAB Compiler SDK and MATLAB data types

For Java programmers, MATLAB Compiler SDK provides an interface to MATLAB data types through a class hierarchy provided by this package. At the top of this class hierarchy lies MWArray, which is an abstract class. The concrete subclasses of MWArray represent one or more MATLAB data types. The MWArray class has the following subclasses representing the major MATLAB types: MWNumericArray, MWLogicalArray, MWCharArray, MWCellArray, MWStructArray, MWFunctionHandle and MWJavaObjectRef. An instance of one of these subclasses can represent either scalar, vector or multi dimensional underlying MATLAB data. Each class has functions that can be used to query the various attributes such as dimensionality, size, and the type of actual MATLAB data that it is representing. There are also functions that can be used to get and set the underlying MATLAB data.

Data conversion rules

The following table lists the data conversion rules for converting Java data types to MATLAB types using the MWArray class hierarchy:

Java typeMWArray typeMATLAB type
double, java.lang.DoubleMWNumericArraydouble
java.lang.NumberMWNumericArraydouble
float, java.lang.FloatMWNumericArraysingle
byte, java.lang.ByteMWNumericArrayint8
short, java.lang.ShortMWNumericArrayint16
int, java.lang.IntegerMWNumericArrayint32
long, java.lang.LongMWNumericArrayint64
char, java.lang.CharacterMWCharArraychar
java.lang.StringMWCharArraychar
boolean, java.lang.BooleanMWLogicalArraylogical
N/AMWCellArraycell
N/AMWStructArraystructure

Note: Java has no unsigned types to represent the uint8, uint16, uint32, and uint64 types used in MATLAB. Construction of and access to MATLAB arrays of an unsigned type requires conversion to appropriate types. Java does not have any built-in data type that can represent MATLAB specific cell and struct data types.

Java-MATLAB data conversion

When you invoke a method corresponding to a MATLAB function on an instance of a Java class generated by MATLAB Compiler SDK, you can either explicitly convert the input parameters to the MATLAB internal array format using the MWArray class hierarchy, or pass them as native Java data types, in which case they wil be converted automatically.

All data returned from the method call is received by the client Java application as an instance of the appropriate MWArray subclass. For example, a MATLAB cell array is returned to the Java application as an MWCellArray object. Return data is not automatically converted to a native Java type. If you wish to perform such a conversion, use the toArray method of the MWArray subclass to which the return data belongs.

Memory management

Instances of MWArray subtypes should be disposed of when no longer needed. Special attention to memory management is necessary due to the dependency of these classes on MATLAB Runtime. Following is a snippet of code from one of the examples shipped with MATLAB Compiler SDK that demonstrates how to perform memory management for the MWArray types.

        // magic is a class generated using MATLAB Compiler SDK that exposes
        // the MATLAB function makesqr  
 
        MWNumericArray n = null;   // Stores input value 
        Object[] result = null;    // Stores the result 
        magic theMagic = null;     // Stores magic class instance
 
        try
        {         
            n = new MWNumericArray(Double.valueOf(args[0]),MWClassID.DOUBLE);        

            // Create new magic object
            theMagic = new magic();

            // Compute magic square 
            result = theMagic.makesqr(1, n);         
        }
        catch (Exception e)
        {
            System.out.println("Exception: " + e.toString());
        }
        finally
        {
            // Free native resources 
            MWArray.disposeArray(n);
            MWArray.disposeArray(result);
            if (theMagic != null)
               theMagic.dispose();
        }                     
 
See Also:
com.mathworks.toolbox.javabuilder.remoting, com.mathworks.toolbox.javabuilder.web
Skip navigation links

© 1994-2017 The MathWorks, Inc. Patents Trademarks