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.
MWArray data conversion classes are built as a class hierarchy
that represents the major MATLAB array types.
The root of the data conversion class hierarchy is the
abstract class. The
MWArray class has the following subclasses
representing the major MATLAB types:
subclass stores a reference to a native MATLAB array of that type.
MWArray classes provide the following:
Constructors and finalizers to instantiate and dispose of MATLAB arrays
setmethods 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
For complete reference information about the
is in the
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
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
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
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
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
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++
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.
When adding fields to data structures and data structure arrays, do so using
standard programming techniques. Do not use the
set command as
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
The MATLAB-Java interface establishes a connection to the JVM™ by calling the JNI method
AttachCurrentThreadcreates 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.