Deploy MATLAB Function to Java Application Using MATLAB Data API for Java

This example shows how to package a MATLAB^® function and deploy it within a Java^® application. The workflow is supported on Windows^®, Linux^®, and macOS systems. This example uses a workflow based on Windows.

Prerequisites

• Create a new work folder that is visible to the MATLAB search path. This example uses a folder named work.

• Verify that you have set up a Java development environment. For details, see Set Up Java Development Environment.

• Verify that you have met all of the MATLAB Compiler SDK™ Java target requirements. For details, see MATLAB Compiler SDK Java Target Requirements.

• End users must have an installation of MATLAB Runtime to run the application. For details, see Download and Install MATLAB Runtime.

  For testing purposes, you can use an installation of MATLAB instead of MATLAB Runtime.

Data Management

To exchange data between the deployed MATLAB code and the Java application, use the MATLAB Data API for Java. This API is also used by MATLAB Engine. For details, see Java Data Type Conversions.

Create MATLAB Function

Create a MATLAB file named calculateDistance.m with the following code:

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

Create Java Package Using compiler.build.javaPackage

Use the compiler.build.javaPackage function to generate a code archive (.ctf file) from the MATLAB function.

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

Although specifying a PackageName in the compiler.build.javaPackage function is not mandatory, it is strongly recommended. Providing a package name results in a cleaner, more predictable Java namespace for the generated code. If omitted, a default root package named example is used, which can lead to a cluttered or confusing package structure in your Java application.

When you package your MATLAB function for Java integration, the process generates several files in your chosen output directory. Of these, the only key file required for Java integration is the code archive (.ctf file), which contains your packaged MATLAB code and resources. For details on the other files, see Files Generated After Packaging MATLAB Functions.

P:\MATLAB\WORK\OUTPUT
    mccExcludedFiles.log
    unresolvedSymbols.txt
    matlabfunction.ctf
    readme.txt
    includedSupportPackages.txt
    requiredMCRProducts.txt
    buildresult.json
    GettingStarted.html

No subfolders exist

When using the MATLAB Data API for Java, the compiler.build.javaPackage function generates a .ctf file, but does not produce a JAR file containing Java wrapper classes. For details, see MATLAB Data API for Java Workflow.

Integrate MATLAB Code into Java Application

You can finalize the integration process in your preferred Java development environment, including a text editor together with the Java Development Kit (JDK) command line tools, or alternatives such as IntelliJ IDEA and Visual Studio Code on Windows, macOS, and Linux. For details, see Set Up Java Development Environment.

Use Java Command Line API to Build Application

1. Create a Java driver application named Distance.java with the following code:

    Distance.java

   import com.mathworks.runtime.*;
   import com.mathworks.matlab.types.*;
   import java.util.Arrays;
   
   public class Distance {
       public static void main(String[] args) {
           // Specify the path to your .ctf file here
           String ctfPath = "matlabfunction.ctf";
   
           try (MatlabRuntime runtime = MatlabRuntime.startMatlab(ctfPath)) {
               long [] p1 = new long [] { 0, 0 };
               long [] p2 = new long [] { 3, 4 };
   
               double distance = runtime.feval(1, "calculateDistance", null, null, p1, p2);
               System.out.println("Euclidean Distance between " 
                   + Arrays.toString(p1) 
                   + " and " 
                   + Arrays.toString(p2) 
                   + " is " 
                   + distance);
   
           } catch (Exception e) {
               e.printStackTrace();
           } finally {
               MatlabRuntime.terminateMatlabClient();
           }
       }
   }

   The resulting directory structure after creating this file is as follows:

   work/
   ├── Distance.java
   └── output/
       ├── matlabfunction.ctf
       └── ...
   

2. Compile your Java code by setting the classpath to include matlabruntime.jar.

   set MATLABROOT=C:\Program Files\MATLAB\R2026a
   
   javac -classpath ".;%MATLABROOT%\toolbox\javabuilder\jar\matlabruntime.jar" Distance.java

3. Run your Java application by setting the classpath to include matlabruntime.jar and by configuring access to the native runtime libraries. For details, see Set MATLAB Library Paths for Testing Deployed Applications.

   java -classpath ".;%MATLABROOT%\toolbox\javabuilder\jar\matlabruntime.jar" Distance
   

   Euclidean Distance between [0, 0] and [3, 4] is 5.0

   Running a Java application without setting the environment variables to provide access to the native runtime libraries from MATLAB or MATLAB Runtime results in a java.lang.UnsatisfiedLinkError.

   Note

   When testing applications on a machine with a full MATLAB installation, you can set up native library access using the MATLAB installation.

   In a deployment scenario where MATLAB Runtime is used, you must explicitly specify the location of the native libraries within an installation of MATLAB Runtime. This distinction ensures that deployed applications run independently of a full MATLAB installation.

   For details, see:

   • Set MATLAB Library Paths for Testing Deployed Applications

   • Set MATLAB Runtime Library Paths for Deployment