[saga-rg] More comments on Strawman API

[Andre Merzky]

Hi Graeme, 

working on the email-backlog - sorry for the delay - I can
imagine that those points are rather important for the
implementation...


Quoting [Graeme Pound] (Feb 16 2006):
> 
> ######### Specific comments on the API
> 
>  -3.23 SAGA.File.openFlags should specify read/write modes

They do by now.  Could you please check if that is what you
had in mind?


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

The Truncate flag to open would imply that the file is
truncated to length zero, as with POSIX open.  The file
pointer is then positioned at the begin of the file.


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

This should be bytes - strings would, as you say, imply an
encoding, which complicates things.  There are several
places where strings are useful (file names, urls etc) -
in read/write they are not.


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

See above - should be a byte array


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

Yes, this was recently fixed.

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

Hmm, very good point - I guess we should handle that as on
command line: setting recursive deletes non-empty
directories, not setting the flag deletes empty directories
only.  Same goes then for copy I think, for consistency.


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

See separate mail.


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

That should read then:

  "the find operates recursively below the current working
  directory if the Recursiveflag is defined (default)."

I will fix that.

Thanks for the remarks! :-)

Andre.



-- 
"So much time, so little to do..."  -- Garfield