Dynamically Specify Options to MATLAB Runtime for Java Applications

Note

Setting runtime options using the MWApplication and MWMCROption classes applies only to Java^® packages created using the legacy MWArray API. If you are developing with the MATLAB^® Data API for Java, these initialization options and classes are not applicable.

Java applications using packages built using the MWArray API in MATLAB Compiler SDK™ can programmatically configure MATLAB Runtime during initialization. This is useful for server-side deployments, headless environments, or systems where binary library conflicts occur between the Java Virtual Machine (JVM) and the MATLAB environment.

To specify options, use these classes in javabuilder.jar:

com.mathworks.toolbox.javabuilder.MWApplication
com.mathworks.toolbox.javabuilder.MWMCROption

Options You Can Specify

Specify the following options by passing MWMCROption values to MWApplication.initialize.

MATLAB Runtime Option	Java Option	Description
`-nojvm`	`MWMCROption.NOJVM`	Start the runtime without a JVM.
`-nodisplay`	`MWMCROption.NODISPLAY`	Start without display functionality. Use on Linux^® systems only.
`-logfile <file>`	`MWMCROption.logFile("file")`	Write runtime output to the specified log file.
`-outproc`	`MWMCROption.OUTPROC`	Launch the runtime in a separate process from the Java application to resolve binary library conflicts.

Note

MATLAB Runtime supports additional startup options that are not configurable through MWMCROption, such as -softwareopengl. Use those options through the supported startup mechanisms for your deployment instead of this Java API.

Initialize MATLAB Runtime with Options

Call MWApplication.initialize before you create instances of generated classes. You can pass multiple options to a single initialization call.

import com.mathworks.toolbox.javabuilder.MWApplication;
import com.mathworks.toolbox.javabuilder.MWMCROption;

public class InitRuntime {
    public static void main(String[] args) throws Exception {

        // Initialize with multiple options: Process Isolation, No JVM, and Logging
        MWApplication.initialize(
            MWMCROption.OUTPROC,             // Resolve library conflicts
            MWMCROption.NOJVM,               // Disable internal JVM
            MWMCROption.logFile("mcr.log")   // Redirect output
        );

        // Create and use generated classes after initialization
        // MyComponentClass obj = new MyComponentClass();
        // obj.someMethod();
    }
}

Query Initialization State and Option Values

Use MWApplication methods to query whether the runtime is initialized and to retrieve active option values.

MWApplication Method	Description
`MWApplication.isMCRInitialized()`	Returns `true` if the runtime is initialized.
`MWApplication.isMCRJVMEnabled()`	Returns `true` if the runtime is running with the JVM enabled.
`MWApplication.isMCRNoDisplaySet()`	Returns `true` if `MWMCROption.NODISPLAY` was specified.
`MWApplication.getMCRLogfileName()`	Returns the log file name specified by `MWMCROption.logFile`.

Default Values

If you call MWApplication.initialize() with no inputs, the runtime starts with these default values for configurable options:

Option	Default Value
`-nojvm`	`false`
`-nodisplay`	`false`
`-logfile`	`none`
`-outproc`	`false`

Implementation Considerations

Execution Frequency: Call MWApplication.initialize once per process. Options apply for the lifetime of the process and cannot be changed after the runtime starts.
Automatic Initialization: If you do not call MWApplication.initialize, the runtime initializes automatically using default values the first time you create an instance of a generated class.
Library Conflict Resolution: Use MWMCROption.OUTPROC if your application encounters segmentation faults or linkage errors caused by conflicting versions of shared libraries used by both the host environment and MATLAB Runtime.
Operating System Constraints: The MWMCROption.NODISPLAY option is not supported on Windows^® systems.