[saga-rg] More comments on Strawman API

[Graeme Pound]

Andre,

Here are some additional comments on the Strawman API (v0.2) that I have 
recovered from a HD failure.

Would it be possible for you to clarify point 3.25, whereby bytes and 
strings are possibly confused in the API?

Thanks,
	Graeme



######### Specific comments on the API

  -3.23 SAGA.File.openFlags should specify read/write modes

  -3.24 At what point should files be truncated, and to what length?

  -3.25 Do the operations of SAGA.File.File deal with byte or character 
arrays? The semantics of this in the API are inconsistent, arguments are 
described of type 'string', but the documentation discusses bytes. See 
comment 3.26.

  -3.26 The SAGA.File read() and write() methods specify arguments of 
type 'string' as the output/input parameter. However there is no way for 
the user to specify the character encoding of the file. Because of the 
unknown provenance of files located on the Grid the default character 
encoding for the local machine may be incorrect.

Is it the intention for these methods to deal with strings/character 
arrays, or at the level of byte encodings?  If SAGA.File read() methods 
return strings the user must be able to specify the character encoding 
for the file, if they return byte arrays this is not a problem. The 
character encoding could be specified as a property of the File class.

  -3.27 Should SAGA.File.File inherit the interface SAGA.NameSpace.NSEntry?

  -3.28 SAGA.NameSpace.NSDir.removeFlags.Recursive: This must be set to 
delete a directory, but how can a user delete a directory without 
deleting non-empty directories?

  -3.29 Many of the exceptions described in the specification document 
are fairly generic, for example the ubiquitous "NoSuccess". Will 
attempts be made to further characterise error conditions that may be 
expected to be common to many Grid platforms, such as 
"AuthenticationFailure" and "AuthorisationFailure". I understand the 
need to avoid an overload of throwable exceptions within the API, 
however these exceptions would be expected in a fairly well defined 
subset of the methods.

  -3.30 Details of NSDir.find()
         "the find operates recursively below the current working 
directory, unless the NoRecursive flag is specified"
        NoRecursive is not defined in the findFlags enumeration (instead 
Recursive is defined & default)