The mpiJava API is modelled as closely as practical on the C++ binding defined in the MPI 2.0 standard (currently we only support the MPI 1.1 subset). A number of changes to argument lists are forced by of the restriction that arguments cannot be passed by reference in Java. In general outputs of mpiJava methods come through the result value of the function. In many cases MPI functions return more than one value. This is dealt with in mpiJava in various ways. Sometimes an MPI function initializes some elements in an array and also returns a count of the number of elements modified. In Java we typically return an array result, omitting the count. The count can be obtained subsequently from the length member of the array. Sometimes an MPI function initializes an object conditionally and returns a separate flag to say if the operation succeeded. In Java we return an object handle which is null if the operation fails. Occasionally an extra field is added to an existing MPI class to hold extra results--for example the Status class has an extra field, index, initialized by functions like Waitany. Rarely none of these methods work and we resort to defining auxilliary classes to hold multiple results from a particular function. In another change to C++, we often omit array size arguments, because they can be picked up within the wrapper by reading the length member of the array argument.
As a result of these changes mpiJava argument lists are often more concise than the corresponding C or C++ argument lists.
Normally in mpiJava, MPI destructors are called by the Java finalize method for the class. This is invoked automatically by the Java garbage collector. For most classes, therefore, no binding of the MPI_class_FREE function appears in the Java API. Exceptions are Comm and Request, which do have explicit Free members. In those cases the MPI operation could have observable side-effects (beyond simply freeing resources), so their execution is left under direct control of the programmer.