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)
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
Andre, Thanks for the reply, you have been very busy. The read/write flags in the latest version of the spec are what I required. I agree that the read/write methods should handle byte arrays, rather than strings. Could you please change the SIDL description of the read()/write() methods? At present the 'buffer' argument is type 'string'. This caused me some confusion when I first read the specification. Thanks, Graeme Andre Merzky wrote:
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.
Should be fixed by now in CVS, for both files and streams. Also, I made the buffer inout for reads, as they should be allocated in application space before the read occurs. Hope I did not miss any misplaced string... Cheers, Andre. Quoting [Graeme Pound] (Feb 20 2006):
Andre,
Thanks for the reply, you have been very busy.
The read/write flags in the latest version of the spec are what I required.
I agree that the read/write methods should handle byte arrays, rather than strings. Could you please change the SIDL description of the read()/write() methods? At present the 'buffer' argument is type 'string'. This caused me some confusion when I first read the specification.
Thanks, Graeme
Andre Merzky wrote:
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
participants (2)
-
Andre Merzky
-
Graeme Pound