Choose Java Deployment Option

MATLAB® Compiler SDK™ provides two ways to deploy MATLAB functions within Java® applications:

  • Deploy to Java Applications using MATLAB Data API for Java (since R2026a)

  • Deploy to Java Applications using MWArray API

Since MATLAB Compiler SDK provides two Java application APIs to interact with deployed MATLAB functions, the two deployment options are distinguished based on the APIs used for exchanging data between the Java application and the deployed MATLAB functions.

Choosing a Java deployment option comes down to understanding the capabilities of each option and recognizing how those capabilities line up with your development requirements. Both options provide a comprehensive set of APIs for handling both application management and data manipulation.

Advantages of MATLAB Data API for Java Over MWArray API

MathWorks® recommends deploying to Java applications using the more modern MATLAB Data API for Java over the MWArray API. The advantages of using the MATLAB Data API for Java over the MWArray API are:

  • The MATLAB Runtime instance can run either in-process or out-of-process with respect to the Java application, and deployed MATLAB functions can be executed either synchronously or asynchronously.

  • Thread-safe design facilitates concurrent data creation and consumption across multiple threads without the need for locking. This leads to improved performance, particularly when there's extensive manipulation of MATLAB data in multiple threads.

  • Transitioning between Java based MATLAB Engine applications and deployed MATLAB applications can now be accomplished with minimal effort.

  • Support for cross-platform development and deployment.

Difference in Generated Artifacts

When you feed a MATLAB function or class to the compiler.build.javaPackage function or the Java Package Compiler app, the main products generated are different for the two deployment options.

Assuming you have a MATLAB function called calculateDistance stored in a file named calculateDistance.m, and you want to integrate it into a Java application, let's examine the resulting outcomes of the two deployment alternatives:

function distance = calculateDistance(p1, p2)
% This function calculates the Euclidean distance between two points
% Inputs:
%   p1 - a two-element vector [x, y]
%   p2 - a two-element vector [x, y]
% Output:
%   distance - the Euclidean distance between p1 and p2

% Calculte Euclidean distance
diff = p1 - p2;
diffSq = diff.^2;
sumSq = sum(diffSq);
distance = sqrt(sumSq);
end

When you pass the calculateDistance.m file as a parameter to the compiler.build.javaPackage function, the MWArray API is the default choice. To use the MATLAB Data API for Java, you need to explicitly specify the interface type using the name-value pair Interface="matlab-data".

buildResults = compiler.build.javaPackage( ...
    "calculateDistance.m",...
    Verbose="on", OutputDir=".\output_mwa",...
    PackageName="com.example.matlabfunction")
 
buildResults = compiler.build.javaPackage( ...
    "calculateDistance.m",...
    Interface="matlab-data",...
    Verbose="on", OutputDir=".\output_mda",....
    PackageName="com.example.matlabfunction")

The function generates corresponding files for the two APIs in the specified folder:

P:\MATLAB\WORK\OUTPUT_MWA
│   mccExcludedFiles.log
│   includedSupportPackages.txt
│   matlabfunction.jar
│   requiredMCRProducts.txt
│   unresolvedSymbols.txt
│   GettingStarted.html
│   buildresult.json
│   readme.txt
│
├───doc
│
├───com
│   └───example
│       └───matlabfunction
│               package-info.java
│               MatlabfunctionMCRFactory.java
│               calculateDistanceClassRemote.java
│               calculateDistanceClass.java
│
└───classes
    └───com
        └───example
            └───matlabfunction
                    matlabfunction.ctf
                    calculateDistanceClassRemote.class
                    calculateDistanceClass.class
                    MatlabfunctionMCRFactory.class
 
P:\MATLAB\WORK\OUTPUT_MDA
    includedSupportPackages.txt
    matlabfunction.ctf
    mccExcludedFiles.log
    unresolvedSymbols.txt
    readme.txt
    GettingStarted.html
    buildresult.json
    requiredMCRProducts.txt

No subfolders exist

MWArray API Workflow

In the MWArray API workflow, when you run the compiler.build.javaPackage command in MATLAB, one of the main outputs is the matlabfunction.jar file. The file name is taken from the last part of the package name, such as com.example.matlabfunction, and it serves as the main deliverable for using MATLAB functions in Java applications. The contents of this JAR reflect the structure of the classes folder created during the build process. Both include the compiled Java classes and the matlabfunction.ctf archive, organized under the specified package.

The original MATLAB file, such as calculateDistance.m, defines the computational logic. This logic is packaged into a .ctf file, which is then bundled into the JAR along with the automatically generated Java classes. These classes are responsible for loading the .ctf archive, managing the MATLAB Runtime, and providing Java friendly methods that make the MATLAB functions available to Java code.

MATLAB Data API for Java Workflow

In the MATLAB Data API for Java workflow, the compiler.build.javaPackage function generates a matlabfunction.ctf file, but does not produce a JAR file containing Java wrapper classes. Instead, this workflow relies on matlabruntime.jar, a Java archive provided by MathWorks as part of MATLAB Compiler SDK.

matlabruntime.jar provides the core Java APIs that enable Java applications to load and interact with packaged MATLAB code encapsulated in a .ctf file.

The file name matlabfunction.ctf is derived from the last segment of the specified package name, such as com.example.matlabfunction.

In contrast to the MWArray workflow, where a project-specific JAR is generated containing both the packaged MATLAB code and Java wrapper classes for direct use, the MATLAB Data API for Java workflow separates the packaged code (.ctf file) from the API specified in matlabruntime.jar, offering a more modern approach to integrating MATLAB with Java.

See Also

Topics