com.mathworks.toolbox.javabuilder

Interface Summary
Interface	Description
Disposable	The `Disposable` interface is implemented by all classes that contain native resources that need to be freed.
MWComponentOption	An option that can be applied to a component initialization option set (MWComponentOptions).

Class Summary
Class	Description
Images	Utility methods for manipulating MWArrays that contain image data.
MWApplication	The `MWApplication` class can be used to initialize the global state of MATLAB Runtime.
MWArray	The `MWArray` class is the base class for all MATLAB array types.
MWCellArray	The `MWCellArray` class manages a native MATLAB cell array.
MWCharArray	The `MWCharArray` class manages a native MATLAB char array.
MWClassID	The `MWClassID` class enumerates all MATLAB array types.
MWComplexity	The `MWComplexity` class enumerates the MATLAB real/complex array property.
MWComponentOptions	Options per component instance.
MWCtfClassLoaderSource	CTF from class loader source.
MWCtfDirectorySource	CTF from directory where CTF file is located.
MWCtfExtractLocation	This class is used to represent the location to which the CTF will be extracted.
MWCtfFileSource	CTF from file source.
MWCtfSource	Interface for CTF source objects.
MWCtfStreamSource	CTF from InputStream source.
MWFunctionHandle	The `MWFunctionHandle` class represents a MATLAB function handle.
MWJavaObjectRef	`MWJavaObjectRef`, a special subclass of MWArray, can be used to create a MATLAB array that references a Java object.
MWLogicalArray	The `MWLogicalArray` class manages a native MATLAB logical array.
MWMatrixRef	The `MWMatrixRef` class represents a MATLAB Matrix Reference.
MWMCROption	This class represents the options that can be passed while initializing the MATLAB Runtime
MWNumericArray	The `MWNumericArray` class is the base class for all numeric MATLAB array types.
MWStringArray	The `MWStringArray` class manages a native MATLAB string array.
MWStructArray	The `MWStructArray` class manages a native MATLAB struct array.

Exception Summary
Exception Description

MWException
The MWException class is used to raise an exception during a method call on a MATLAB compiler generated object.

Exception Summary
Exception	Description
MWException	The `MWException` class is used to raise an exception during a method call on a MATLAB compiler generated object.

Package com.mathworks.toolbox.javabuilder Description

This package provides classes that define the rules for data conversion between Java and the MATLAB programming environment. It also has a few utility classes that allow you to change the MATLAB (MATLAB Runtime) environment that executes the underlying MATLAB code.

MATLAB data types

In the MATLAB environment, an array is the basic building block for all the data types. There are scalars (1-by-1 matrices), vectors (matrices with only one row or column), matrices (with two dimensions), and multi dimensional arrays with more than two dimensions. MATLAB has other ways of storing both numeric and nonnumeric data, but it is usually best to think of everything as an array.

The main data types offered by MATLAB include logical (boolean), char, numeric, cell, struct (structure), function handles, and Java objects. The numeric data type has subtypes to represent signed and unsigned, integer and floating-point data. Cell and struct are MATLAB specific data types that act as containers for different types of data. Each of the MATLAB data types is in the form of an array that can be a minimum of 0-by-0 in size but can grow to an n-dimensional array of any size. For more information on MATLAB data types, please visit the MathWorks support Web site and refer to the section "Programming Fundamentals".

MATLAB Compiler SDK and MATLAB data types

For Java programmers, MATLAB Compiler SDK provides an interface to MATLAB data types through a class hierarchy provided by this package. At the top of this class hierarchy lies MWArray, which is an abstract class. The concrete subclasses of MWArray represent one or more MATLAB data types. The MWArray class has the following subclasses representing the major MATLAB types: MWNumericArray, MWLogicalArray, MWCharArray, MWCellArray, MWStructArray, MWFunctionHandle and MWJavaObjectRef. An instance of one of these subclasses can represent either scalar, vector or multi dimensional underlying MATLAB data. Each class has functions that can be used to query the various attributes such as dimensionality, size, and the type of actual MATLAB data that it is representing. There are also functions that can be used to get and set the underlying MATLAB data.

Data conversion rules

The following table lists the data conversion rules for converting Java data types to MATLAB types using the MWArray class hierarchy:

Java type	MWArray type	MATLAB type
double, java.lang.Double	MWNumericArray	double
java.lang.Number	MWNumericArray	double
float, java.lang.Float	MWNumericArray	single
byte, java.lang.Byte	MWNumericArray	int8
short, java.lang.Short	MWNumericArray	int16
int, java.lang.Integer	MWNumericArray	int32
long, java.lang.Long	MWNumericArray	int64
char, java.lang.Character	MWCharArray	char
java.lang.String	MWCharArray	char
boolean, java.lang.Boolean	MWLogicalArray	logical
N/A	MWCellArray	cell
N/A	MWStructArray	structure

Note: Java has no unsigned types to represent the uint8, uint16, uint32, and uint64 types used in MATLAB. Construction of and access to MATLAB arrays of an unsigned type requires conversion to appropriate types. Java does not have any built-in data type that can represent MATLAB specific cell and struct data types.

Java-MATLAB data conversion

When you invoke a method corresponding to a MATLAB function on an instance of a Java class generated by MATLAB Compiler SDK, you can either explicitly convert the input parameters to the MATLAB internal array format using the MWArray class hierarchy, or pass them as native Java data types, in which case they wil be converted automatically.

All data returned from the method call is received by the client Java application as an instance of the appropriate MWArray subclass. For example, a MATLAB cell array is returned to the Java application as an MWCellArray object. Return data is not automatically converted to a native Java type. If you wish to perform such a conversion, use the toArray method of the MWArray subclass to which the return data belongs.

Memory management

Instances of MWArray subtypes should be disposed of when no longer needed. Special attention to memory management is necessary due to the dependency of these classes on MATLAB Runtime. Following is a snippet of code from one of the examples shipped with MATLAB Compiler SDK that demonstrates how to perform memory management for the MWArray types.

        // magic is a class generated using MATLAB Compiler SDK that exposes
        // the MATLAB function makesqr  
 
        MWNumericArray n = null;   // Stores input value 
        Object[] result = null;    // Stores the result 
        magic theMagic = null;     // Stores magic class instance
 
        try
        {         
            n = new MWNumericArray(Double.valueOf(args[0]),MWClassID.DOUBLE);        

            // Create new magic object
            theMagic = new magic();

            // Compute magic square 
            result = theMagic.makesqr(1, n);         
        }
        catch (Exception e)
        {
            System.out.println("Exception: " + e.toString());
        }
        finally
        {
            // Free native resources 
            MWArray.disposeArray(n);
            MWArray.disposeArray(result);
            if (theMagic != null)
               theMagic.dispose();
        }

See Also:: com.mathworks.toolbox.javabuilder.remoting