Main Content

Programming Interfaces Generated by MATLAB Compiler SDK

APIs Based on MATLAB Function Signatures

The compiler generates two kinds of interfaces to handle MATLAB® function signatures.

  • A standard signature in Java®

    This interface specifies input arguments for each overloaded method as one or more input arguments of class java.lang.Object or any subclass (including subclasses of MWArray). The standard interface specifies return values, if any, as a subclass of MWArray.

  • mlx API

    This interface allows the user to specify the inputs to a function as an Object array, where each array element is one input argument. Similarly, the user also gives the mlx interface a preallocated Object array to hold the outputs of the function. The allocated length of the output array determines the number of desired function outputs.

    The mlx interface may also be accessed using java.util.List containers in place of Object arrays for the inputs and outputs. Note that if List containers are used, the output List passed in must contain a number of elements equal to the desired number of function outputs.

    For example, this would be incorrect usage:

    java.util.List outputs = new ArrayList(3);
    myclass.myfunction(outputs, inputs); // outputs 0 elements!
    

    The correct usage is:

    java.util.List outputs = Arrays.asList(new Object[3]);
    myclass.myfunction(outputs, inputs); // list has 3 elements

Typically, you use the standard interface when you want to call MATLAB functions that return a single array. In most other cases, use the mlx interface.

Standard API

The standard calling interface returns an array of one or more MWArray objects.

The standard API for a generic function with none, one, more than one, or a variable number of arguments, is shown in the following table.

ArgumentsAPI to Use
Generic MATLAB function
function [Out1, Out2, ..., varargout] = foo(In1, In2, ...,
 InN, varargin)
API if there are no input arguments
public Object[] foo(int numArgsOut) 
API if there is one input argument
public Object[] foo(int numArgsOut, Object In1) 
API if there are two to N input arguments
public Object[] foo(
int numArgsOut, 
Object In1,
Object In2, 
... Object InN
) 
API if there are optional arguments, represented by the varargin argument
public Object[] foo(
int numArgsOut,
 Object in1,
 Object in2,
 ..., Object InN,
Object varargin
)

The following table shows details about the arguments for these samples of standard signatures.

ArgumentDescriptionDetails About Argument
numArgsOutNumber of outputs

An integer indicating the number of outputs you want the method to return. To return no arguments, omit this argument.

The value of numArgsOut must be less than or equal to the MATLAB function nargout.

The numArgsOut argument must always be the first argument in the list.

In1, In2, ...InNRequired input arguments

All arguments that follow numArgsOut in the argument list are inputs to the method being called.

Specify all required inputs first. Each required input must be of class MWArray or any class derived from MWArray.

vararginOptional inputs

You can also specify optional inputs if your MATLAB code uses the varargin input: list the optional inputs, or put them in an Object[] argument, placing the array last in the argument list.

Out1, Out2, ...OutNOutput arguments

With the standard calling interface, all output arguments are returned as an array of MWArrays.

mlx API

Consider a function with the following structure:

function [Out1, Out2, ..., varargout] = foo(In1, In2, ..., 
                          InN, varargin)
The compiler generates the following API as the mlx interface:
public void foo (List outputs, List inputs) throws MWException;
public void foo (Object[] outputs, Object[] inputs) 
                                            throws MWException;

Code Fragment: Signatures Generated for the myprimes Example

For a specific example, consider the myprimes method. This method has one input argument, so the compiler generates three overloaded methods in Java.

When you add myprimes to the class myclass and build the class, the compiler generates the myclass.java file. A fragment of myclass.java is listed below to show overloaded implementations of the myprimes method in the Java code.

/* mlx interface - List version */
public void myprimes(List lhs, List rhs) throws MWException
{
    (implementation omitted)
}
/* mlx interface - Array version */
public void myprimes(Object[] lhs, Object[] rhs) 
                                        throws MWException
{
    (implementation omitted)
 }
/* Standard interface - no inputs*/
public Object[] myprimes(int nargout) throws MWException
   {
      (implementation omitted)
   }
/* Standard interface - one input*/
public Object[] myprimes(int nargout, Object n) 
                                      throws MWException
   {
      (implementation omitted)
   }

The standard interface specifies inputs to the function within the argument list and outputs as return values. The second implementation demonstrates the feval interface, the third implementation shows the interface to be used if there are no input arguments, and the fourth shows the implementation to be used if there is one input argument. Rather than returning function outputs as a return value, the feval interface includes both input and output arguments in the argument list. Output arguments are specified first, followed by input arguments.

For details about the interfaces, see Programming Interfaces Generated by MATLAB Compiler SDK.