Every object and type defined in SIDL can be put into a SIDL array of that type. Arrays are a fairly complex topic, and the specifics of the Babel Array API are discussed earlier in Section 5.4. Suffice to say that the entire API is available in Java, except for
ensure, borrow, and first, all of which have no real use in Java. addRef and deleteRef exist in Java, but shouldn't be used, because the Java decrements the reference count itself when it garbage collects a SIDL object or array. If it is necessary to deleteRef an array, you should use the destroy() array function instead.
More to the point are the specifics of the Java implementation. Each SIDL type and class includes a static inner class named Array. This is the main Array class, and in order to support up to 7 dimensional arrays, every method takes either 7 array indices, or an array of indices. For example, in order to get the element (2,3) from a 2 dimensional array, we would type arry._get(2,3,0,0,0,0,0).
Since typing all those zeros can get a little tedious, we also implemented a set of subclasses of Array. One subclass for each dimension. So, if we had and Array2 instead of an Array we could simply type arry2._get(2,3) to get the correct element.
These numbered Array subclasses improve on the Array API usability somewhat, but that do have a side effect. In order to avoid conflicts between the Array superclass and the numbered Array subclass functions, all other basic Array methods found in the Array superclass are preceded by an underscore '_'. For example, in order to get an array's dimension, you can type arry._dim(). The numbered arrays all inherit these methods, so arry2._dim() will also work, although in this case, the answer should be obvious.
Furthermore, there is another underscore rule for Arrays in Java. All numbered arrays have two get and two set functions. The _get and _set functions are the same in Array and all the Array# subclasses, they simply pass the arguments of the _get call down to the underlying implementation. However, the underscore-less get and set do bounds checking in Java before calling the underlying implementation, and, if there is a problem, throw an ArrayIndexOutOfBoundsException.
Because the numbered arrays are subclasses of Array, if necessary you can Java cast an Array# to an Array. However, some functions return an Array. In order to convert an Array to the correctly numbered array, we provided a function in Array called _dcast(). In order to cast an Array object to a numbered array, simply call _dcast() on it. For example, assume we have a 1 dimensional array of type foo.Bar called arry that is represented by the Java class Array. In order to get a correctly numbered array type:
foo.Bar.Array1 arry1 = arry._dcast();
After this cast we have 2 references to the same array, arry and arry1.
Finally, the Java array constructors are slightly different then they are in other languages. This is the constructor definition for Array.
public Array(int dim, int[] lower, int[] upper, boolean isRow)
This constructor creates and array of dimension dim. It takes two arrays of integers to define the lower and upper bounds of each dimension in the array. If lower or upper has fewer elements than there are dimensions in the array, or any element in lower is larger than the corresponding element in upper, this constructor will throw an exception. Finally, this constructor takes a boolean isRow. If isRow is true, this constructor will create a SIDL array in row-major order, if it is false, it will create an array in column-major order.
The constructors for numbered arrays are simpler. Here's the constructor for a 2 dimensional array:
public Array2( int l0, int l1, int u0, int u1, boolean isRow)
The dimension argument is no longer necessary, and it is no longer necessary to create arrays of bounds to pass into the constructor. l0 and l1 are the lower bounds. and u0 and u1 are the upper bounds. This constructor still includes the choice between column and row major orders.
If all your lower bounds are 0, you can use an even simpler constructor:
public Array2( int s0, int s1, boolean isRow)
Another alternate way to construct sidl arrays is present in numbered arrays. The following constructor takes a Java 2 dimensional array, and copies it into a SIDL 2 dimensional array:
public Array2(foo.Bar[][] array, boolean isRow)
If you already have a numbered SIDL array of the correct dimension, you can copy a java array into it with the method fromArray. The method takes the same arguments as the constructor above, and returns nothing.
If you wish to go the other way, to copy a sidl array into a Java array, you may use the numbered array function toArray. toArray takes no arguments, and returns a new Java array with the SIDL array elements copied into it.