[saga-rg] Java implementation issues

22 Nov 2005

      I have been looking at the Strawman SAGA API (v0.2+) with a view to 
developing a Java implementation of the API over multiple types of 
resource. Ultimately I am looking to develop SAGA implementations in 
Matlab and Jython as part of the GeodiseLab activity for the OMII 
(www.omii.ac.uk).

I have some comments about the current SAGA API as it is defined in SIDL 
from the Java perspective, and some questions about the SAGA approach. 
There are also some trivial points about the SIDL interface.

My key concern is whether the SAGA API (as defined in the SIDL interface 
in the strawman document) will produce 'nice' Java that will be simple 
to use. The problem stems from the use of the SIDL keywords 'out' and 
'inout' to define method arguments that are passed by reference. This is 
perfectly acceptable in FORTRAN, C and C++, however when translated to 
Java the result is clumsy.

In Java arguments are (typically) passed by value. In particular 
primitive types, such as 'long', and immutable types, such as 'String', 
are effectively passed by value. This URL describes how Java arguments 
are passed: http://www.yoda.arachsys.com/java/passing.html.

When the Babel tool is used to parse the following SIDL definition into 
Java:
     package Hello version 1.0 {
         class World {
          void getMsg(out int ppp);
         }
     }

The integer argument is placed within a mutable object that may be 
altered from within the 'getMsg' method. This solution may be opaque to 
may Java users of the API.

In most situations in the SAGA API passing a single output argument by 
reference can be avoided by specifying a return argument (where it is 
currently void). For example:

   interface JobService {
       void submitJob (in  JobDefinition jobDef,
                                out Job           job);
        ...
   }

becomes:

   interface JobService {
             Job submitJob (in  JobDefinition jobDef);
             ...
   }

However, the problem is slightly more complex where multiple output 
arguments are returned by reference. For example:

     class File  {
         void read        (in  long            len_in,
                           out string          buffer,
                           out long            len_out  );
         ...
     }

In this situation there are many alternatives to passing multiple output 
arguments by reference. For example; placing the output information in a 
single object, or, where appropriate, making the variables available as 
attributes of the class.

A similar problem exists in Matlab and Python where arguments are passed 
by value. Incidentally, here multiple output arguments are supported by 
returning a vector (or tuple) of variables.

The 'pass by value' issue leads me to a more general question about the 
SAGA API. Is it your objective that the API is strictly consistent 
between languages? My concern, if this was the case, is that this may 
lead to a 'worst-of-all-worlds' solution rather than an API that is 
appropriate for each language. Certainly this issue would arise for 
object-oriented versus procedural languages. Andre suggested to me that 
the language bindings were yet to be standardised. Does the scope exist 
to vary the language bindings to play to the strengths of each target 
language?

Thanks,
     Graeme Pound

Minor points

  - ExceptionCategory does not have enum values specified

  - SAGA.Task.Task.throw(); "throw" is a reserved word in Java

  - Should TaskContainer, File and LogicalFile be a classes or an 
interfaces?

- Enums are frequently not capitalised, stylistically it would be nice 
to be consistent about this (from the Java POV these would be classes so 
should be capitalized)

  - void return type is frequently not specified