External Interfaces/API

Creating an Array of Objects Within MATLAB

To call a Java method that has one or more arguments defined as an array of Java objects, you must, under most circumstances, pass your objects in a Java array. You can construct an array of objects in a call to a Java method or constructor. Or you can create the array within MATLAB.

The MATLAB javaArray function lets you create a Java array structure that can be handled in MATLAB as a single multidimensional array. You specify the number and size of the array dimensions along with the class of objects you intend to store in it. Using the one-dimensional Java array as its primary building block, MATLAB then builds an array structure that satisfies the dimensions requested in the javaArray command.

Using the javaArray Function

To create a Java object array, use the MATLAB javaArray function, which has the following syntax.

• A = javaArray('element_class', m, n, p, ...)
  

The first argument is the 'element_class' string, which names the class of the elements in the array. You must specify the fully qualified name (package and class name). The remaining arguments (m, n, p, ...) are the number of elements in each dimension of the array.

An array that you create with javaArray is equivalent to the array that you would create with the Java code.

• A = new element_class[m][n][p]...;
  

The following command builds a Java array of four lower level arrays, each capable of holding five objects of the java.lang.Double class. (You will probably be more likely to use primitive types of double than instances of the java.lang.Double class, but in this context, it affords us a simple example.)

• dblArray = javaArray('java.lang.Double', 4, 5);
  

The javaArray function does not deposit any values into the array elements that it creates. You must do this separately. The following MATLAB code stores objects of the java.lang.Double type in the Java array dblArray that was just created.

• for m = 1:4
      for n = 1:5
      dblArray(m,n) = java.lang.Double((m*10) + n);
      end
  end
  
  dblArray
  dblArray =
  java.lang.Double[][]:
      [11]    [12]    [13]    [14]    [15]
      [21]    [22]    [23]    [24]    [25]
      [31]    [32]    [33]    [34]    [35]
      [41]    [42]    [43]    [44]    [45]
  

Another Way to Create a Java Array

You can also create an array of Java objects using syntax that is more typical to MATLAB. For example, the following syntax creates a 4-by-5 MATLAB array of type double and assigns zero to each element of the array.

• matlabArray(4,5) = 0;
  

You use similar syntax to create a Java array in MATLAB, except that you must specify the Java class name. The value being assigned, 0 in this example, is stored in the final element of the array, javaArray(4,5). All other elements of the array receive the empty matrix.

• javaArray(4,5) = java.lang.Double(0)
  javaArray =
  java.lang.Double[][]:
       []     []     []     []     []
       []     []     []     []     []
       []     []     []     []     []
       []     []     []     []    [0]
  

Note    You cannot change the dimensions of an existing Java array as you can with a MATLAB array. The same restriction exists when working with Java arrays in the Java language. See the example below.

This example first creates a scalar MATLAB array, and then successfully modifies it to be two-dimensional.

• matlabArray = 0;
  matlabArray(4,5) = 0
  
  matlabArray =
  
       0     0     0     0     0
       0     0     0     0     0
       0     0     0     0     0
       0     0     0     0     0
  

When you try this with a Java array, you get an error. Similarly, you cannot create an array of Java arrays from a Java array, and so forth.

• javaArray = java.lang.Double(0);
  javaArray(4,5) = java.lang.Double(0);
  ??? Index exceeds Java array dimensions.
  

Working with Java Arrays

Accessing Elements of a Java Array