Learn more about MATLAB Builder JA

About the MATLAB Builder JA API

On this page…
Understanding the MATLAB Builder JA API Data Conversion Classes Automatic Conversion to MATLAB Types Understanding Function Signatures Generated by the MATLAB Builder JA Product Adding Fields to Data Structures and Data Structure Arrays Returning Data from MATLAB to Java

Understanding the MATLAB Builder JA API Data Conversion Classes

When writing your Java application, you can represent your data using objects of any of the data conversion classes. Alternatively, you can use standard Java data types and objects.

The data conversion classes are built as a class hierarchy that represents the major MATLAB array types.

Note   This discussion provides conceptual information about the classes. For details, see com.mathworks.toolbox.javabuilder in the product Documentation Set. This discussion assumes you have a working knowledge of the Java programming language and the Java Software Developer's Kit (SDK). This is not intended to be a discussion on how to program in Java. Refer to the documentation that came with your Java SDK for general programming information.

Overview of Classes and Methods in the Data Conversion Class Hierarchy

The root of the data conversion class hierarchy is the MWArray abstract class. The MWArray class has the following subclasses representing the major MATLAB types: MWNumericArray, MWLogicalArray, MWCharArray, MWCellArray, and MWStructArray.

Each subclass stores a reference to a native MATLAB array of that type. Each class provides constructors and a basic set of methods for accessing the underlying array's properties and data. To be specific, MWArray and the classes derived from MWArray provide the following:

• Constructors and finalizers to instantiate and dispose of MATLAB arrays

• get and set methods to read and write the array data

• Methods to identify properties of the array

• Comparison methods to test the equality or order of the array

• Conversion methods to convert to other data types

Advantage of Using Data Conversion Classes

The MWArray data conversion classes let you pass native type parameters directly without using explicit data conversion. If you pass the same array frequently, you might improve the performance of your program by storing the array in an instance of one of the MWArray subclasses.

Back to Top

Automatic Conversion to MATLAB Types

Note   Because the conversion process is automatic (in most cases), you do not need to understand the conversion process to pass and return arguments with MATLAB Builder JA components.

When you pass an MWArray instance as an input argument, the encapsulated MATLAB array is passed directly to the method being called.

In contrast, if your code uses a native Java primitive or array as an input parameter, the builder converts it to an instance of the appropriate MWArray class before it is passed to the method. The builder can convert any Java string, numeric type, or any multidimensional array of these types to an appropriate MWArray type, using its data conversion rules. See Data Conversion Rules for a list of all the data types that are supported along with their equivalent types in MATLAB.

The conversion rules apply not only when calling your own methods, but also when calling constructors and factory methods belonging to the MWArray classes.

Note   There are some data types commonly used in MATLAB that are not available as native Java types. Examples are cell arrays and arrays of complex numbers. Represent these array types as instances of MWCellArray and MWNumericArray, respectively.

Back to Top

Understanding Function Signatures Generated by the MATLAB Builder JA Product

The Java programming language now supports optional function arguments in the way that MATLAB does with varargin and varargout. To support this feature of MATLAB, the builder generates a single overloaded Java method that accommodates any number of input arguments. This behavior is an enhancement over previous versions of varargin support that only handled a limited number of arguments.

Note   In addition to handling optional function arguments, the overloaded Java methods that wrap MATLAB functions handle data conversion. See Automatic Conversion to MATLAB Types for more details.

Understanding MATLAB Function Signatures

As background, recall that the generic MATLAB function has the following structure:

function [Out1, Out2, ..., varargout]=
           foo(In1, In2, ..., varargin)

To the left of the equal sign, the function specifies a set of explicit and optional return arguments.

To the right of the equal sign, the function lists explicit input arguments followed by one or more optional arguments.

Each argument represents a MATLAB type. When you include the varargin or varargout argument, you can specify any number of inputs or outputs beyond the ones that are explicitly declared.

Overloaded Methods in Java That Encapsulate M-Code

When the MATLAB Builder JA product encapsulates your M-code, it creates an overloaded method that implements the MATLAB functions. This overloaded method corresponds to a call to the generic MATLAB function for each combination of the possible number and type of input arguments.

In addition to encapsulating input arguments, the builder creates another method, which represents the output arguments, or return values, of the MATLAB function. This additional overloaded method takes care of return values for the encapsulated MATLAB function. This method of encapsulating the information about return values simulates the mlx interface in the MATLAB Compiler product.

These overloaded methods are called the standard interface (encapsulating input arguments) and the mlx interface (encapsulating return values). See Programming Interfaces Generated by the MATLAB Builder JA Product for details.

Back to Top

Adding Fields to Data Structures and Data Structure Arrays

When adding fields to data structures and data structure arrays, do so using standard programming techniques. Do not use the set command as a shortcut.

For examples of how to correctly add fields to data structures and data structure arrays, see the programming examples in Sample Java Applications.

Back to Top

Returning Data from MATLAB to Java

All data returned from a method coded in MATLAB is passed 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.

Back to Top

Programming

Importing Classes

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS