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.

Arguments	API 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.

Argument	Description	Details About Argument
`numArgsOut`	Number 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, ...InN`	Required 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`.
`varargin`	Optional 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, ...OutN`	Output arguments	With the standard calling interface, all output arguments are returned as an array of `MWArray`s.

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.