[saga-rg] Java implementation issues

[Andre Merzky]

Hi Graeme, 

thanks for the comments.  For the questions, see inlined
comments...

Cheers, Andre.


Quoting [Graeme Pound] (Nov 22 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);
>         }
>     }

We are currently fixing the strawman to avoid the 'void'
signature of the calls - we just would leave:

   package Hello version 1.0 {
       class World {
        getMsg(out int ppp);
       }
   }

So, the signature in the language binding is not necessarily
void.  

There are two major issues with this:

 a) as you mention, for multiple out parameters, the
    situation is more unclear.

 b) the asynchroneous method calls are supposed to use the
    same signatures, but should return a task handle.  That
    immediately raises problems with methods which have a
    single out param, as these are in most languages better
    expressed by returning that param as return value.

> 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 Java binding should use whatever is most 'native' in
Java... - e.g. what is used in posix like implementations,
or in standard libs/classes...


> 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?

No, the language bindings are definitely NOT supposed to be
strictly consistent - but as much as possible.  E.g. method
call names should be recognisable, flags should be
similar/identical if possible, error code should be the same
etc.

In particular the task model might look different in the
various languages...

> Thanks,
>     Graeme Pound
> 
> 
> Minor points
> 
>  - ExceptionCategory does not have enum values specified

Right, its a TODO item already.


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

Good point, probably also in other languages.  We could use
rethrow?  


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

Classes I think.  Why should they be 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)

Right, style is inconsistent as of yet - too many authors
;-)

>  - void return type is frequently not specified

It should be removed wherever it still _is_ specified - see
above.

Thanks, Andre.





-- 
+-----------------------------------------------------------------+
| Andre Merzky                      | phon: +31 - 20 - 598 - 7759 |
| Vrije Universiteit Amsterdam (VU) | fax : +31 - 20 - 598 - 7653 |
| Dept. of Computer Science         | mail: merzky at cs.vu.nl       |
| De Boelelaan 1083a                | www:  http://www.merzky.net |
| 1081 HV Amsterdam, Netherlands    |                             |
+-----------------------------------------------------------------+