How MATLAB Compiler SDK Java Integration Works

When you create Java^® packages using MATLAB^® Compiler SDK™, the compiler encrypts your MATLAB functions and generates one or more Java classes that wrap your MATLAB functions. The classes provide methods that allow you to call the functions as you would any other Java method.

In addition, the javabuilder package that is provided with MATLAB and MATLAB Runtime contains the MWArray classes that manage data that passes between Java and MATLAB.

`MWArray` Data Conversion Classes

When writing your Java application, you can represent your data using objects of any of the MWArray data conversion classes. Alternatively, you can use standard Java data types and objects.

The MWArray data conversion classes are built as a class hierarchy that represents the major MATLAB array types.

`MWArray` Hierarchy

The root of the data conversion class hierarchy is the MWArray abstract class. The MWArray class has the following subclasses representing the major MATLAB types: MWNumericArray, MWLogicalArray, MWCharArray, MWCellArray, and MWStructArray. Each subclass stores a reference to a native MATLAB array of that type.

The MWArray classes provide the following:

Constructors and finalizers to instantiate and dispose of MATLAB arrays
get and set methods to read and write the array data
Methods to identify properties of the array
Comparison methods to test the equality or order of the array
Conversion methods to convert to other data types

Note

For complete reference information about the MWArray class hierarchy, see com.mathworks.toolbox.javabuilder.MWArray, which is in the matlabroot/help/toolbox/javabuilder/MWArrayAPI/ folder.

Automatic and Manual Conversion to MATLAB Types

If your Java code uses a native Java primitive or array as an input parameter, the compiler automatically converts it to an instance of the appropriate MWArray class before it is passed to the method. The compiler can convert any Java string, numeric type, or a multidimensional array of these types to an appropriate MWArray type.

In contrast, you can manually convert Java data types to one of the standard MATLAB data types using the MWArray data conversion classes. When you pass an MWArray instance as an input argument, the encapsulated MATLAB array is passed directly to the method being called. For more details and examples, see Convert Data Between Java and MATLAB.

For a list of all the data types that are supported along with their equivalent types in MATLAB, see Rules for Data Conversion Between Java and MATLAB.

Advantage of Using Data Conversion Classes

The MWArray data conversion classes let you pass native type parameters directly without using explicit data conversion. If you pass the same array frequently, you might improve the performance of your program by storing the array in an instance of one of the MWArray subclasses.

When you pass an argument only a few times, it is usually just as efficient to pass a primitive Java type or object, which the calling mechanism automatically converts into an equivalent MATLAB type.

Function Signatures Generated by MATLAB Compiler SDK

The Java programming language supports optional function arguments in the way that MATLAB does with varargin and varargout. To support this MATLAB feature, the compiler generates a single overloaded Java method that accommodates any number of input arguments.

MATLAB Function Signatures

A generic MATLAB function has the following structure:

function [Out1, Out2, ..., varargout]=
           foo(In1, In2, ..., varargin)

To the left of the equal sign, the function specifies a set of explicit and optional return arguments.

To the right of the equal sign, the function lists explicit input arguments followed by one or more optional arguments.

Each argument represents a MATLAB type. When you include the varargin or varargout argument, you can specify any number of inputs or outputs beyond the ones that are explicitly declared.

Overloaded Methods in Java That Encapsulate MATLAB Code

When MATLAB Compiler SDK encapsulates your MATLAB code, it creates an overloaded method that implements the MATLAB functions. This overloaded method corresponds to a call to the generic MATLAB function for each combination of the possible number and type of input arguments.

In addition to encapsulating input arguments, the compiler creates another method which represents the output arguments of the MATLAB function. This method of encapsulating the information about return values resembles the mlx interface generated for the C/C++ MATLAB Compiler SDK target.

These overloaded methods are called the standard interface and the mlx interface. For details, see Programming Interfaces Generated by MATLAB Compiler SDK.

Note

When adding fields to data structures and data structure arrays, do so using standard programming techniques. Do not use the set command as a shortcut.

Interaction Between MATLAB Compiler SDK and JVM

Packages produced by MATLAB Compiler SDK use Java Native Interface (JNI) to interact with MATLAB Runtime.

When the first MATLAB Compiler SDK object is instantiated:

Dependent MATLAB Compiler SDK classes are loaded.
A series of shared libraries forming the JNI bridge from the generated package to MATLAB Runtime are loaded.
MATLAB Runtime is initialized by creating an instance of a C++ class called mcrInstance.
The MATLAB-Java interface establishes a connection to the JVM^® by calling the JNI method AttachCurrentThread.
AttachCurrentThread creates a class loader that loads all classes needed by MATLAB code utilizing the MATLAB-Java interface.
The MATLAB Runtime C++ core allocates resources for the arrays created by the Java API.

As you create MWArray objects to interact with MATLAB Runtime, the JVM creates a wrapper object for the MATLAB mxArray object. The MATLAB Runtime C++ core allocates the actual resources to store the mxArray object. This has an impact on how the JVM frees up resources used by your application. Most of the resources used when interacting with MATLAB are created by the MATLAB Runtime C++ core. The JVM only knows about the MATLAB resources through the JNI wrappers created for them. Because of this, the JVM does not know the size of the resources being consumed and cannot effectively manage them using its built in garbage collector. The JVM also does not manage the threads used by MATLAB Runtime and cannot clean them up.

All of the MATLAB Compiler SDK classes have static methods to properly dispose of their resources. The disposal methods trigger the freeing of the underlying resources in the MATLAB Runtime C++ core. Not properly disposing of MATLAB Compiler SDK objects can result in unpredictable behavior and may look like your application has a memory leak.