Passing Arguments to and from Java :: Programming (MATLAB® Builder™ JA)

Learn more about MATLAB Builder JA

Passing Arguments to and from Java

On this page…
Format Manual Conversion of Data Types Automatic Conversion to a MATLAB Type Specifying Optional Arguments Handling Return Values

On this page…

Format

Manual Conversion of Data Types

Automatic Conversion to a MATLAB Type

Specifying Optional Arguments

Handling Return Values

Format

When you invoke a method on a MATLAB Builder JA component, the input arguments received by the method must be in the MATLAB internal array format. You can either convert them yourself within the calling program, or pass the arguments as Java data types, which are then automatically converted by the calling mechanism.

To convert them yourself, use instances of the MWArray classes; in this case you are using manual conversion. Storing your data using the classes and data types defined in the Java language means that you are relying on automatic conversion. Most likely, you will use a combination of manual and automatic conversion.

Manual Conversion of Data Types

To manually convert to one of the standard MATLAB data types, use the MWArray data conversion classes provided by the builder. For class reference and usage information, see the com.mathworks.toolbox.javabuilder package.

Code Fragment: Using MWNumericArray

The Magic Square example (Deploying a Component with the Magic Square Example) exemplifies manual conversion. The following code fragment from that program shows a java.lang.Double argument that is converted to an MWNumericArray type that can be used by the M-function without further conversion:

MWNumericArray dims = null;
dims = new MWNumericArray(Double.valueOf(args[0]), 
              MWClassID.DOUBLE);

result = theMagic.makesqr(1, dims);

Code Fragment: Passing an MWArray. This example constructs an MWNumericArray of type MWClassID.DOUBLE. The call to myprimes passes the number of outputs, 1, and the MWNumericArray, x:

x = new MWNumericArray(n, MWClassID.DOUBLE);
cls = new myclass();
y = cls.myprimes(1, x);

MATLAB Builder JA product converts the MWNumericArray object to a MATLAB scalar double to pass to the M-function.

Automatic Conversion to a MATLAB Type

When passing an argument only a small number of times, it is usually just as efficient to pass a primitive Java type or object. In this case, the calling mechanism converts the data for you into an equivalent MATLAB type.

For instance, either of the following Java types would be automatically converted to the MATLAB double type:

A Java double primitive
An object of class java.lang.Double

For reference information about data conversion (tables showing each Java type along with its converted MATLAB type, and each MATLAB type with its converted Java type), see Data Conversion Rules.

Code Fragment: Automatic Data Conversion

When calling the makesqr method used in the getmagic application, you could construct an object of type MWNumericArray. Doing so would be an example of manual conversion. Instead, you could rely on automatic conversion, as shown in the following code fragment:

result = M.makesqr(1, arg[0]);

In this case, a Java double is passed as arg[0].

Here is another example:

result = theFourier.plotfft(3, data, new Double(interval));

In this Java statement, the third argument is of type java.lang.Double. According to conversion rules, the java.lang.Double automatically converts to a MATLAB 1-by-1 double array.

Code Fragment: Passing a Java Double Object

The example calls the myprimes method with two arguments. The first specifies the number of arguments to return. The second is an object of class java.lang.Double that passes the one data input to myprimes.

cls = new myclass();
y = cls.myprimes(1, new Double((double)n));

This second argument is converted to a MATLAB 1-by-1 double array, as required by the M-function. This is the default conversion rule for java.lang.Double.

Code Fragment: Passing an MWArray

This example constructs an MWNumericArray of type MWClassID.DOUBLE. The call to myprimes passes the number of outputs, 1, and the MWNumericArray, x.

x = new MWNumericArray(n, MWClassID.DOUBLE);
cls = new myclass();
y = cls.myprimes(1, x);

builder converts the MWNumericArray object to a MATLAB scalar double to pass to the M-function.

Code Fragment: Calling MWArray Methods

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

For example, the following code fragment calls the constructor for the MWNumericArray class with a Java double as the input argument:

double Adata = 24;
MWNumericArray A = new MWnumericArray(Adata);
System.out.println("Array A is of type " + A.classID());

The builder converts the input argument to an instance of MWNumericArray, with a ClassID property of MWClassID.DOUBLE. This MWNumericArray object is the equivalent of a MATLAB 1-by-1 double array.

When you run this example, the result is as follows:

Array A is of type double

Changing the Default by Specifying the Type

When calling an MWArray class method constructor, supplying a specific data type causes the MATLAB Builder JA product to convert to that type instead of the default.

For example, in the following code fragment, the code specifies that A should be constructed as a MATLAB 1-by-1 16-bit integer array:

double Adata = 24;
MWNumericArray A = new MWnumericArray(Adata, MWClassID.INT16);
System.out.println("Array A is of type " + A.classID());

When you run this example, the result is as follows:

Array A is of type int16

Specifying Optional Arguments

So far, the examples have not used M-functions that have varargin or varargout arguments. Consider the following M-function:

function y = mysum(varargin)
%   MYSUM Returns the sum of the inputs.
%   Y = MYSUM(VARARGIN) Returns the sum of the inputs.
%   This file is used as an example for the MATLAB 
%   Builder for Java product.

%   Copyright 2001-2007 The MathWorks, Inc.

y = sum([varargin{:}]);

This function returns the sum of the inputs. The inputs are provided as a varargin argument, which means that the caller can specify any number of inputs to the function. The result is returned as a scalar double.

Code Fragment: Passing Variable Numbers of Inputs

The MATLAB Builder JA product generates a Java interface to this function as follows:

/* mlx interface - List version*/
public void mysum(List lhs, List rhs)
                          throws MWException
{
   (implementation omitted)
}
/* mlx interface - Array version*/
public void mysum(Object[] lhs, Object[] rhs)
                          throws MWException
{
   (implementation omitted)
}

/* standard interface - no inputs */
public Object[] mysum(int nargout) throws MWException
{
   (implementation omitted)
}

/* standard interface - variable inputs */
public Object[] mysum(int nargout, Object varargin)
                          throws MWException
{
   (implementation omitted)
}

In all cases, the varargin argument is passed as type Object. This lets you provide any number of inputs in the form of an array of Object, that is Object[], and the contents of this array are passed to the compiled M-function in the order in which they appear in the array. Here is an example of how you might use the mysum method in a Java program:

public double getsum(double[] vals) throws MWException
{
   myclass cls = null;
   Object[] x = {vals};
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.mysum(1, x);
      return ((MWNumericArray)y[0]).getDouble(1);
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
	      cls.dispose();
   }
}

In this example, an Object array of length 1 is created and initialized with a reference to the supplied double array. This argument is passed to the mysum method. The result is known to be a scalar double, so the code returns this double value with the statement:

return ((MWNumericArray)y[0]).getDouble(1);

Cast the return value to MWNumericArray and invoke the getDouble(int) method to return the first element in the array as a primitive double value.

Code Fragment: Passing Array Inputs. The next example performs a more general calculation:

public double getsum(Object[] vals) throws MWException
{
   myclass cls = null;
   Object[] x = null;
   Object[] y = null;

   try
   {
      x = new Object[vals.length];
      for (int i = 0; i < vals.length; i++)
         x[i] = new MWNumericArray(vals[i], MWClassID.DOUBLE);

      cls = new myclass();
      y = cls.mysum(1, x);
      return ((MWNumericArray)y[0]).getDouble(1);
   }
   finally
   {
      MWArray.disposeArray(x);
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

This version of getsum takes an array of Object as input and converts each value to a double array. The list of double arrays is then passed to the mysum function, where it calculates the total sum of each input array.

Code Fragment: Passing a Variable Number of Outputs

When present, varargout arguments are handled in the same way that varargin arguments are handled. Consider the following M-function:

function varargout = randvectors
%   RANDVECTORS Returns a list of random vectors.
%   VARARGOUT = RANDVECTORS Returns a list of random
%   vectors such that the length of the ith vector = i.
%   This file is used as an example for the MATLAB 
%   Builder for Java product.

%   Copyright 2001-2007 The MathWorks, Inc.

for i=1:nargout
   varargout{i} = rand(1, i);
end

This function returns a list of random double vectors such that the length of the ith vector is equal to i. The MATLAB Compiler product generates a Java interface to this function as follows:

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

Code Fragment: Passing Optional Arguments with the Standard Interface. Here is one way to use the randvectors method in a Java program:

public double[][] getrandvectors(int n) throws MWException
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.randvectors(n);
      double[][] ret = new double[y.length][];

      for (int i = 0; i < y.length; i++)
         ret[i] = (double[])((MWArray)y[i]).getData();
      return ret;
   }

   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

The getrandvectors method returns a two-dimensional double array with a triangular structure. The length of the ith row equals i. Such arrays are commonly referred to as jagged arrays. Jagged arrays are easily supported in Java because a Java matrix is just an array of arrays.

Handling Return Values

The previous examples used the fact that you knew the type and dimensionality of the output argument. In the case that this information is unknown, or can vary (as is possible in M-programming), the code that calls the method might need to query the type and dimensionality of the output arguments.

There are several ways to do this. Do one of the following:

Use reflection support in the Java language to query any object for its type.
Use several methods provided by the MWArray class to query information about the underlying MATLAB array.
Coercing to a specific type using the toTypeArray methods.

Code Fragment: Using Java Reflection

This code sample calls the myprimes method, and then determines the type using reflection. The example assumes that the output is returned as a numeric matrix but the exact numeric type is unknown.

public void getprimes(int n) throws MWException
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, new Double((double)n));
      Object a = ((MWArray)y[0]).toArray();

      if (a instanceof double[][])
      {
         double[][] x = (double[][])a;

         /* (do something with x...) */
      }

      else if (a instanceof float[][])
      {
         float[][] x = (float[][])a;

         /* (do something with x...) */
      }

      else if (a instanceof int[][])
      {
         int[][] x = (int[][])a;

         /* (do something with x...) */
      }

      else if (a instanceof long[][])
      {
         long[][] x = (long[][])a;

         /* (do something with x...) */
      }

      else if (a instanceof short[][])
      {
         short[][] x = (short[][])a;

         /* (do something with x...) */
      }

      else if (a instanceof byte[][])
      {
         byte[][] x = (byte[][])a;

         /* (do something with x...) */
      }

      else
      {
         throw new MWException(
            "Bad type returned from myprimes");
      }
   }

This example uses the toArray method to return a Java primitive array representing the underlying MATLAB array. The toArray method works just like getData in the previous examples, except that the returned array has the same dimensionality as the underlying MATLAB array.

Code Fragment: Using MWArray Query

The next example uses the MWArray classID method to determine the type of the underlying MATLAB array. It also checks the dimensionality by calling numberOfDimensions. If any unexpected information is returned, an exception is thrown. It then checks the MWClassID and processes the array accordingly.

public void getprimes(int n) throws MWException
{
   myclass cls = null;
   Object[] y = null;

   try
   {
      cls = new myclass();
      y = cls.myprimes(1, new Double((double)n));
      MWClassID clsid = ((MWArray)y[0]).classID();

      if (!clsid.isNumeric() ||
         ((MWArray)y[0]).numberOfDimensions() != 2)
      {
         throw new MWException("Bad type 
                          returned from myprimes");
      }

      if (clsid == MWClassID.DOUBLE)
      {
         double[][] x = (double[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }

      else if (clsid == MWClassID.SINGLE)
      {
         float[][] x = (float[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }

      else if (clsid == MWClassID.INT32 || 
              clsid == MWClassID.UINT32)
      {
         int[][] x = (int[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }

      else if (clsid == MWClassID.INT64 || 
              clsid == MWClassID.UINT64)
      {
         long[][] x = (long[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }

      else if (clsid == MWClassID.INT16 || 
              clsid == MWClassID.UINT16)
      {
         short[][] x = (short[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }

      else if (clsid == MWClassID.INT8 || 
              clsid == MWClassID.UINT8)
      {
         byte[][] x = (byte[][])((MWArray)y[0]).toArray();

         /* (do something with x...) */
      }
   }
   finally
   {
      MWArray.disposeArray(y);
      if (cls != null)
         cls.dispose();
   }
}

Code Fragment: Using toTypeArray Methods

The next example demonstrates how you can coerce or force data to a specified numeric type by invoking any of the toTypeArray methods. These methods return an array of Java types matching the primitive type specified in the name of the called method. The data is coerced or forced to the primitive type specified in the method name. Note that when using these methods, data will be truncated when needed to allow conformance to the specified data type.

Object results = null;
try {
    // call a compiled m-function
    results = myobject.myfunction(2);

    // first output is known to be a numeric matrix
    MWArray resultA = (MWNumericArray) results[0];
   double[][] a = (double[][]) resultA.toDoubleArray();

    // second output is known to be 
    //    a 3-dimensional numeric array
    MWArray resultB = (MWNumericArray) results[1];
   Int[][][] b = (Int[][][]) resultB.toIntArray();  
}
 finally {
    MWArray.disposeArray(results);
}

Creating an Instance of the Class

Passing Java Objects by Reference

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit