MATLAB® Builder™ JA

Programming Interfaces Generated by the MATLAB^® Builder™ JA Product

APIs Based on MATLAB^® Function Signatures

builder 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 contains 0 elements!
  

  And this would be the correct usage:

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

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

Back to Top

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.

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

public Object[] foo(
int numArgsOut
) 

public Object[] foo(
int numArgsOut, 
Object In1
) 

public Object[] foo(
int numArgsOut, 
Object In1,
Object In2, 
... 
Object InN
) 

public Object[] foo(
int numArgsOut,
 Object in1,
 Object in2,
 ..., 
Object InN,
Object varargin
)

Details about the arguments for these samples of standard signatures are shown in the following table.

Back to Top

mlx API

For a function with the following structure:

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

builder 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;

Back to Top

Code Fragment: Signatures Generated for myprimes Example

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

When you add myprimes to the class myclass and build the component, builder generates the myclass.java file. A fragment of myclass.java is listed to show the three overloaded implementations of the myprimes method in the Java code. The first implementation shows the interface to be used if there are no input arguments, the second shows the implementation to be used if there is one input argument, and the third shows the feval interface.

/* 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.

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.

See APIs Based on MATLAB^® Function Signatures for details about the interfaces.

Back to Top

Data Conversion Rules

MWArray Class Specification