Package MATLAB Function Using Java Package Compiler App with MATLAB Data API

Prerequisites

Create MATLAB Functions

In MATLAB, examine the MATLAB code that you want to package. For this example, create a MATLAB function named magicsquare.m in a new folder named MagicProject.

function y = magicsquare(x)
y = magic(x);

At the MATLAB command prompt, enter magicsquare(5).

The output is a 5-by-5 matrix.

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

Create Project and Compiler Task

Create a compiler task for your Java package using the Java Package Compiler. Compiler tasks allow you to compile files in a project for a specific deployment target.

To open the app, on the Apps tab, expand the Apps gallery. In the Application Deployment section, click Java Package Compiler.

You can also open the app using the javaPackageCompiler function at the MATLAB Command Window.

After you open the app, the Create Compiler Task dialog box prompts you to add a task to a new or an existing MATLAB project. For this example, select Start a new project and create a compiler task and create a new project named MagicProject in the MagicProject folder. For more information on creating and using MATLAB projects, see Create Projects.

A new compiler task named JavaPackage1 opens in the Editor.

You can create more Java compiler tasks or package code for other deployment targets by opening the Compiler Task Manager or going to the Manage Tasks tab and creating a new compiler task.

Specify Build Options

You can specify options for the Java package and its installer before packaging to customize the building and packaging process. For instance, you can obfuscate the MATLAB code or specify the method of including MATLAB Runtime in the generated installer.

Add the MATLAB function to the Java package. All files must be located in the project root folder to be added to the project. For this example, in the Exported Functions section of the compiler task, click Add Exported Function and select magicsquare.m. In the Project panel, the file now has the labels Design and Exported Function File.

In the Java Package Info section, replace the string My Java Package with the name for your Java package, magicjava.

To choose a different output location for the generated files, update the paths in the Output Locations section.

In the Java API Selection section, choose the API to use for exchanging data between the Java application and the MATLAB code. For this example, select the MATLAB Data API. For more information, see Choose Java Deployment Option.

Create Sample Code (Optional)

MATLAB Compiler SDK can generate sample Java code that demonstrates how to call your MATLAB exported function. You can use samples to implement your own application or to test the compiled artifact. If you write your own Java application code, you can move it to the appropriate directory after the MATLAB functions are packaged. For more information, see Create Sample Code to Call Exported Function.

To create a sample MATLAB file, click Create new sample in the Samples section. Select the file magicsquare.m. A MATLAB live script opens for you to edit. Under Edit Sample Inputs, enter the value 5 and save the file. The file sampleFiles\magicsquareSample.mlx is added to the Samples section of the task.

View Code and Package Java Package

To view code that contains instructions on building and packaging your component, click the arrow next to Export Build Script and select Show Code. On the right, a window displays a deployment script with the compiler.build.javaPackage and compiler.package.installer functions that corresponds to your build options. You can convert this code to a MATLAB script file by clicking the Export Build Script button. Running the generated build script is equivalent to clicking the Build and Package button.

To create the Java package and an installer, click Build and Package. To create only the Java package, click the arrow next to Build and Package and select Build.

The compiler generates files in the <compiler_task_name>/output folder in your project folder. The key files utilized during the integration process are the code archive (.ctf file) containing the MATLAB code. For information on the other files, see Files Generated After Packaging MATLAB Functions.

If you created an installer, the package subfolder contains the installer for your shared library files along with MATLAB Runtime.

Integrate MATLAB Code Archive into Java Application

After creating the Java package, write source code for a Java application in your preferred Java development environment. For details, see Set Up Java Development Environment.

If you created sample code before packaging, MATLAB Compiler SDK generates a sample Java application named magicsquareSample.java in the samples folder.

 magicsquareSample.java

/**
 * magicsquareSample
 * Sample driver code that is integrated with a compiled MATLAB function
 * generated by MATLAB Compiler SDK.
 *
 * Refer to the MATLAB Compiler SDK documentation for more information.
 *
 */

import com.mathworks.runtime.*;
import java.util.Arrays;

public class magicsquareSample
{
    public static void main(String[] args){
        try {
            try (MatlabRuntime rt = MatlabRuntime.startMatlab("magicjava.ctf")) {
                double xIn = 5.0;
                double[][] yOut = rt.feval(1, "magicsquare", xIn);
                System.out.println(Arrays.deepToString(yOut));
            }
            MatlabRuntime.terminateMatlabClient();
        } catch (Exception e) {
            e.printStackTrace();
        }
   }
}

After you write source code, build and run your Java application.

At the system command prompt, navigate to the samples folder that contains your Java application. Compile your Java code by setting the classpath to include matlabruntime.jar, which is located in your MATLAB or MATLAB Runtime installation.

set MATLABROOT=<MATLAB_INSTALL_DIR>

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

Run your Java application by setting the classpath to include matlabruntime.jar and by configuring access to the native runtime libraries.

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

The application returns the same output as the sample MATLAB code you created during packaging.

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

To run the application outside of MATLAB, you must install MATLAB Runtime. For details, see Download and Install MATLAB Runtime. If you created an installer using Build and Package, the installer contains a version of MATLAB Runtime that matches the version of MATLAB used to compile the Java package.