[SAGA-RG] Some comments on the SAGA specs.

[Ceriel Jacobs]

Hi,

I am currently in the process of modifying the Java language bindings for
SAGA, following the changes in the SAGA specification, using the version
marked as "Version 1.1  Revised November 19, 2009", and came across a couple
of issues, written down below, in random order:

CONSTRUCTOR specification of URL: should have "url", not "buffer", as out
parameter type. Also, the specification does not provide a default value
for the in-parameter, whereas the details do (and the latter is correct,
I think). Version 1.0 of the SAGA specs had this error as well.

DESTRUCTOR specification of URL: should have "url", not "buffer", as
in-parameter type. Version 1.0 of the SAGA specs had this error as well.

URL set_port specification: default value for port = "" ??? That cannot
be right, a port is an integer, so I guess the default value is -1.
This is wrong in the details as well. Version 1.0 of the SAGA specs had
this error as well.

stream.close() still can throw IncorrectState. This is fine, but contradicts
the Errate in Appendix B, which say that close() now is not throwing
IncorrectState anymore. This remark only holds for the
namespace/file/logicalfile close, the rpc close, and the stream_server close.

These errata also don't mention any of the changes to the streams package,
and there are several, such as the added "connect" method in the stream_server
class, and the name change of the stream_server class (which used to be
stream_service).

These errata also don't mention a couple of signature changes in the
task package, and there are several:
task_container add(), remove(), list_tasks(), get_task().
Moreover, these changes all break backwards compatibility.
Also, the task_container.state metric has changed type, again a
change that breaks backwards compatibility.

Appendix B sais in its first paragraph that the version number of the
document has not changed, and remains 1.0. However, the first page of
the document clearly states: "Version: 1.1 Revised November 19,2009".

task_container.add(): the notes specify that it throws AlreadyExists if the
task is already in the container, but AlreadyExists is not in the Throws list.

Question: why can the context constructor still throw IncorrectState? Or
any other exception, for that matter? It doe not call set_default() anymore.
Should these exceptions now be thrown by the add_context method of session?
But that one currently cannot throw IncorrectState.

That's it for now.

Cheers,		Ceriel