Package com.mathworks.toolbox.javabuilder

This package provides classes that define the rules for data conversion between Java and MATLAB programming environment.

See: Description

Package com.mathworks.toolbox.javabuilder Description

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

MATLAB data types

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

The data types offered by MATLAB mainly include logical, char, numeric, cell, structure, function handles and java classes. The numeric data type has subtypes to represent signed and unsigned, integer and floating-point data. Cell and structure are MATLAB specific data types that act as the containers for different types of data. Each of the MATLAB data types is in the form of a matrix or array and is a minimum of 0-by-0 in size and 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 the section "Programming Fundamentals"

MATLAB Builder JA and MATLAB data types

For Java programmers, MATLAB Builder JA provides 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 like dimensionality, size, the type of actual MATLAB data that it is representing, etc. There are also functions that can be used to get and set the underlying MATLAB data.

Data conversion rules

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

Java typeMWArray typeMATLAB type
double, java.lang.DoubleMWNumericArraydouble
java.lang.NumberMWNumericArraydouble
float, java.lang.FloatMWNumericArraysingle
byte, java.lang.ByteMWNumericArrayint8
short, java.lang.ShortMWNumericArrayint16
int, java.lang.IntegerMWNumericArrayint32
long, java.lang.LongMWNumericArrayint64
char, java.lang.CharacterMWCharArraychar
java.lang.StringMWCharArraychar
boolean, java.lang.BooleanMWLogicalArraylogical
N/AMWCellArraycell
N/AMWStructArraystructure

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 structure data types.

Java-MATLAB data conversion

When you invoke a method, corresponding to an M functions, on a MATLAB Builder JA generated Java class instance, the input parameters received by the method must be in the MATLAB internal array format. You can either (manually) convert them yourself within the calling program, or pass the parameters as Java data types.

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 converted to a Java type. If you choose to use a Java type, you must convert to that type using 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 more needed. The special attention to the Memory Management is necessary due to the dependency of these classes on MCR. Following is a snippet of code from one of the examples shipped with MATLAB Builder JA that demonstrates how the memory management is performed for the MWArray types. 

        // magic is a class generated using MATLAB Builder JA that exposes
        // M 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, com.mathworks.toolbox.javabuilder.web, com.mathworks.toolbox.javabuilder.webfigures

© 1994-2008 The MathWorks, Inc. • Terms of Use • Patents • Trademarks