Classes
class	xmog_java_element
	A class implementing the xmog_java_dynamic interface for accessing Java array elements via JNI or Codemesh's remoting protocol. More...

class	xmog_java_array_size
	The proxy type representing the length of an array. More...

class	xmog_java_array
	The baseclass for all Java proxy array types. More...

class	xmog_java_bool_array
	The wrapper type for the Java `boolean[]` type. More...

class	xmog_java_jboolean_array
	The wrapper type for the Java `boolean[]` type. More...

class	xmog_java_byte_array
	The wrapper type for the Java `byte[]` type. More...

class	xmog_java_char_array
	The wrapper type for the Java `char[]` type. More...

class	xmog_java_double_array
	The wrapper type for the Java `double[]` type. More...

class	xmog_java_float_array
	The wrapper type for the Java `float[]` type. More...

class	xmog_java_int_array
	The wrapper type for the Java `int[]` type. More...

class	xmog_java_long_array
	The wrapper type for the Java `long[]` type. More...

class	xmog_java_short_array
	The wrapper type for the Java `short[]` type. More...

class	xmog_java_object_array
	The proxy type for reference arrays. More...

class	xmog_java_array_template< ElementType >
	The object array template type to support arrays of proxy types. More...

Typedefs
typedef xmog_java_bool_array	jcpp_bool_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_byte_array	jcpp_byte_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_char_array	jcpp_char_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_double_array	jcpp_double_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_float_array	jcpp_float_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_int_array	jcpp_int_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_long_array	jcpp_long_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

typedef xmog_java_short_array	jcpp_short_array
	A typedef that allows C++ calling code to use the pre 3.0 type name. More...

Detailed Description

Introduction

Arrays require some special facilities to be useful in a natural way.
There are some basic differences between arrays in Java and arrays in C++. C++ inherits the C interpretation of arrays: an array is simply a pointer into memory. The memory holds (aligned) instances of the array element type.

A Java array on the other hand is a full object. It has a length property that allows you to query the array length and it has some memory that holds the actual array data. The memory used to hold the array elements might or might not be contiguous; the JVM does not have to make any guarantees about this.

When we're asked to make C++ arrays and Java arrays interoperable, we have a couple of choices and we can provide some integration features easily whereas others are very hard to provide. A quick summary of available integration features follows:

there is a dedicated proxy type for every primitive array type.
there is a template type for arrays of object references.
all proxy array types extend xmog_java_array.
all proxy array types have a read-only length field.
all proxy array types have overloaded subscript operators that allow per-element access to the array. Please see the section on performance that discusses other access options.

General Conventions

In general, proxy types for Java reference types will have a typedef for array types of rank 1 and 2. If you're generating your own proxy types, you can control the maximum rank up to which these typedefs are generated via the "Array Rank" setting. The following code snippet illustrates the type definitions that the generated String type might contain:

class String : ...
{
public:
 
    typedef xmog_java_array_template< java::lang::String > array1D;
 
    typedef xmog_java_array_template< xmog_java_array_template< java::lang::String > > array2D;
 
    ...
};

Using these typedefs, you can use array types very naturally. You would for example declare an array of ten String instances using the following line:

String::array1D arr( 10 );

You can of course always use the long form or create your own typedef'ed types:

// use the template form rather than the typedef
xmog_java_array_template< java::lang::String >    arr( 10 );
 
// create and use your own typedef
typedef xmog_java_array_template< java::lang::String >    StringArray;
StringArray        arr( 10 );

Primitive array types are created by prefixing the native type with xmog_java_ and appending _array. The array type for integers (int ) is for example xmog_java_int_array. Native booleans are supported in two flavors: via the C++ bool type and the JNI jboolean type. There are two different array types which correspond with these two types: xmog_java_bool_array and xmog_java_jboolean_array.

Performance

The subscript operators allow per-element access to the proxy array. Using the operators is very convenient, but it is hardly the highest performing way to access the array: for each element, we are calling accross the the language boundary at least once and because there is no way to provide the xmog_localenv pointer as part of the operator call, we also need to access thread local storage once for each access. This combined overhead will completely
dominate the application if you're choosing ease-of-use over performance. The following snippet shows ab example of such array usage. Please note that there's nothing wrong with using the framework array types like that. You should always write easily readable and maintainable code first and then optimize performance in the areas that profiling in contrast to guessing indicates to be problematic.

//create an integer array of size 10
xmog_java_int_array   iArr( 10 );
 
//iterate over the array elements and double them
for( int i=0; i<iArr.length; i++ )
    iArr[ i ] *= 2;

There are other options that are a little harder to use, but offer much better performance. You might for example be better off performing the array traversal on a native array and then copying the native array into a Java array.

Quite frequently, you are faced with the problem of having to convert a native array type to the corresponding Java array type. You might wish for conversion operators between the two sides, but we believe that conversion operators would encourage some coding patterns that lead to hard- to-understand problems. Let's assume for a moment that we had trivially usable conversion operators. What if you wrote code like this:

jint   nativeInputOutputArray[ 10 ];
 
Algorithm.calculate( nativeInputOutputArray );

In the above example, the native array would be transformed into a Java array when it is passed to the calculate method. The calculate method reads the array elements, performs a calculation, and returns the result in the passed in array. Now the problem is this: does the native array contain the output or still the input?

We really can't know what's being done to an array on the Java side, so to be safe, we would always have to update the native array completely with the contents of the temporary Java array if we wanted to make sure that the user is not surprised by runtime behavior differences between C++ code and Java code. For that reason (and other more technical reasons), we have chosen to make conversion between native and Java arrays an explicit operation. A proxy array type has a constructor that takes a pointer to some native memory and an array size as input and creates a Java array from that native array. The following code snippet illustrates this:

jint                 nativeInputOutputArray[] = { 0, 1, 2, 3, 4 };
xmog_java_int_array  javaInputOutputArray( nativeInputOutputArray, 5 );
 
Algorithm.calculate( javaInputOutputArray );

Now, the intent is perfectly clear. The javaInputOutputArray instance is going to receive all updates (if any) and then it is up to the user to set them back into the native array.

jint                 nativeInputOutputArray[] = { 0, 1, 2, 3, 4 };
xmog_java_int_array  javaInputOutputArray( nativeInputOutputArray, 5 );
 
Algorithm.calculate( javaInputOutputArray );
 
javaInputOutputArray.to_native( nativeInputOutputArray, 0, 5 );

As with all framework methods, you can pass in an optional xmog_localenv pointer to slightly improve the performance.