How MATLAB Compiler SDK Java Integration Works - MATLAB & Simulink - MathWorks Australia

HowMATLABCompiler SDKJavaIntegration Works

When you create Java^®packages usingMATLAB^®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, thejavabuilderpackage that is provided with MATLAB andMATLAB Runtimecontains theMWArrayclasses 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 theMWArraydata conversion classes. Alternatively, you can use standard Java data types and objects.

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

`MWArray`Hierarchy

数据转换类层次结构的根theMWArrayabstract class. TheMWArrayclass has the following subclasses representing the major MATLAB types:MWNumericArray,MWLogicalArray,MWCharArray,MWCellArray, andMWStructArray. Each subclass stores a reference to a native MATLAB array of that type.

TheMWArrayclasses provide the following:

Constructors and finalizers to instantiate and dispose of MATLAB arrays
getandsetmethods 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 theMWArrayclass hierarchy, seecom.mathworks.toolbox.javabuilder.MWArray, which is in thematlabroot/help/toolbox/javabuilder/MWArrayAPI/folder.

Automatic and Manual Conversion toMATLABTypes

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 appropriateMWArrayclass 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 appropriateMWArraytype.

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

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

Advantage of Using Data Conversion Classes

TheMWArraydata 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 theMWArraysubclasses.

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 byMATLABCompiler SDK

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

MATLABFunction Signatures

A generic MATLAB function has the following structure:

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

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

To therightof the equal sign, the function lists explicitinput参数一个或多个可选的argumen紧随其后ts.

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

Overloaded Methods inJavaThat EncapsulateMATLABCode

WhenMATLAB Compiler SDKencapsulates 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 themlxinterface generated for the C/C++MATLAB Compiler SDKtarget.

These overloaded methods are called the standard interface and themlxinterface. For details, seeProgramming 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 thesetcommand as a shortcut.

Interaction BetweenMATLABCompiler SDKand JVM

Packages produced byMATLAB Compiler SDKuse Java Native Interface (JNI) to interact withMATLAB Runtime.

When the firstMATLAB Compiler SDKobject is instantiated:

DependentMATLAB Compiler SDKclasses are loaded.
A series of shared libraries forming the JNI bridge from the generated package toMATLAB Runtimeare loaded.
MATLAB Runtimeis initialized by creating an instance of a C++ class calledmcrInstance.
The MATLAB-Java interface establishes a connection to the JVM™ by calling the JNI methodAttachCurrentThread.
AttachCurrentThreadcreates a class loader that loads all classes needed by MATLAB code utilizing the MATLAB-Java interface.
TheMATLAB RuntimeC++ core allocates resources for the arrays created by the Java API.

As you createMWArrayobjects to interact withMATLAB Runtime, the JVM creates a wrapper object for the MATLABmxArrayobject. TheMATLAB RuntimeC++ core allocates the actual resources to store themxArrayobject. 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 theMATLAB RuntimeC++ 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 byMATLAB Runtimeand cannot clean them up.

All of theMATLAB Compiler SDKclasses have static methods to properly dispose of their resources. The disposal methods trigger the freeing of the underlying resources in theMATLAB RuntimeC++ core. Not properly disposing ofMATLAB Compiler SDKobjects can result in unpredictable behavior and may look like your application has a memory leak.