Queries and minor points

Graeme Pound

24 Nov 2005 24 Nov '05

4:12 p.m.

Please find below a couple of queries, and diverse minor points, which arose during my preparation of a Java implementation of the API. I anticipate that my comments on the semantics of the API will become a little more substantive in due course. Thanks, Graeme ######### Queries - I am little unclear of the purpose and operation of Attribute.getVectorAttribute() and Attribute.setVectorAttribute(). What is returned if a vector attribute is queried with getAttribute()? Why are a vector of values associated with a key required? - contextType does not appear to be very extensible, how would different security models be specified? ######### Minor points - Exceptions are not described in the SIDL interface, however Exception types are listed in long description of the methods (for example ReadOnlyAttribute and NoSuchKey). This information should be in the SIDL description as it is fundamental to the interface. - capitalise ivec, openDirFlags, openFlags? - JobService.runJob() returns Job and stdin, stdout, stderr. However stdin, stdout, stderr are available from Job.getJobInfo()? Can runJob() simply return an object Job? - enum values are not specified by JobState - LogicalFile argument types not specified for addLocation, removeLocation, replicate. These should be 'string' - The enumerations openDirFlags and openFlags exist in the following packages SAGA.Namespace, SAGA.File and SAGA.LogicalFile (although SAGA.Namespace is imported by SAGA.File and SAGA.LogicalFile). Is this duplication required? - the interfaces Stream and StreamServer implements Attributes, however Attributes does not exist. Is this Attribute (perhaps Attributes is a better name for this class)? - File.readP() and File.writeP() define input argument of type 'pattern'. This type is not defined by the SIDL API, is 'pattern' an undefined class or primitive type? - in Stream void getContext (out context info); should read void getContext (out Context info); - strawman_error.txt: "All objects in SAGA implement ErrorHandler...", the SIDL for these objects should indicate that they implement the ErrorHandler interface. The following objects: Directory File Job JobService LogicalDirectory LogicalFile Multiplexer Stream StreamServer Task TaskContainer ... any others ?

Show replies by date

Steven Newhouse

25 Nov 25 Nov

9:20 p.m.

New subject: [saga-rg] Queries and minor points

Is there a document describing how you would go from a SIDL defined method in the strawman API to a Java method (or others). I could not see a link on the website or in the document? It would be useful - if there is not one to define one. Steven -- ---------------------------------------------------------------- Dr Steven Newhouse Tel:+44 (0)2380 598789 Deputy Director, Open Middleware Infrastructure Institute (OMII) Suite 6005, Faraday Building (B21), Highfield Campus, Southampton University, Highfield, Southampton, SO17 1BJ, UK

Andre Merzky

20 Jan 20 Jan

5:19 p.m.

New subject: [saga-rg] Queries and minor points

Until now we don't have such a procedure defined. A good approach might be to wait for the Java bindings, and to reverse-engineer that into a procedure? :-) Cheers, Andre. Quoting [Steven Newhouse] (Nov 25 2005):

...

Date: Fri, 25 Nov 2005 21:20:31 +0000 From: Steven Newhouse To: saga-rg@ggf.org Subject: Re: [saga-rg] Queries and minor points

Is there a document describing how you would go from a SIDL defined method in the strawman API to a Java method (or others). I could not see a link on the website or in the document?

It would be useful - if there is not one to define one.

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

Andre Merzky

5:40 p.m.

New subject: [saga-rg] Queries and minor points

Hi Graeme, I am not sure if answers to that mail are still relevant - let me attempt to answer your points anyway, as far as I can... A longer mail in respect to your details list of comments is in the pipeline as well - sorry for the delay... *sigh* Quoting [Graeme Pound] (Nov 24 2005):

...

Please find below a couple of queries, and diverse minor points, which arose during my preparation of a Java implementation of the API. I anticipate that my comments on the semantics of the API will become a little more substantive in due course.

Thanks, Graeme

######### Queries

- I am little unclear of the purpose and operation of Attribute.getVectorAttribute() and Attribute.setVectorAttribute(). What is returned if a vector attribute is queried with getAttribute()? Why are a vector of values associated with a key required?

A use case is, as pointed out by Hrabri for instance, the specification of a list of email addresse to be notified on job completion: [perl] job.set_vector_attributes ('SAGA_JobContact', ('a@mai.com', 'b@mailcom')); If a vector attribute key is set/queried with the scalar attribute call, and exception should be raised (NoSuchKey). Same for the other case. Actually, I think that this model is not very nice. For one thing, we need an inspection interface (does that attribute exist? Is it a scalar or vector?). Also, we need to be clear if attribute can be scalars or vectors (if you set only one email?). Sorry for not having a better answer...

...

- contextType does not appear to be very extensible, how would different security models be specified?

The spec states that A implementation CAN implement various types of Security contexts. or just one type. and Other types MAY be specified by a SAGA implementation. which basically means that out of the types specified in the spec, and any other types you can think of, a non empty subset has to be implemented by the SAGA implementation.

...

######### Minor points

- Exceptions are not described in the SIDL interface, however Exception types are listed in long description of the methods (for example ReadOnlyAttribute and NoSuchKey). This information should be in the SIDL description as it is fundamental to the interface.

Yes, we probably should do that. Two reasons why we did not yet: - it clutters the API definition visually - it would mean to maintain the exceptions in the SIDL and in the description part. I think it is best to keep them detailed in the desciption part, and to copy them to the SIDL part during final edit. Does that make sense?

...

- capitalise ivec, openDirFlags, openFlags?

Well, ask 2 people about that and you get 5 answers ;-) Fact is, capitalization should be consistent through the API, and it is not currently. I think it is best if you choose a native java scheme for naming, I guess there is one?

...

- JobService.runJob() returns Job and stdin, stdout, stderr. However stdin, stdout, stderr are available from Job.getJobInfo()? Can runJob() simply return an object Job?

Yes, it could. SubmitJob does exactly that. However, runJob is supposed to be a convenience routine, for the most simple case. Therefor it is redundant anyway (with submitJob). I am not sure if that answers the question though :-)

...

- enum values are not specified by JobState

They should, thanks. This is fixed by now.

...

- LogicalFile argument types not specified for addLocation, removeLocation, replicate. These should be 'string'

Fixed, thanks.

...

- The enumerations openDirFlags and openFlags exist in the following packages SAGA.Namespace, SAGA.File and SAGA.LogicalFile (although SAGA.Namespace is imported by SAGA.File and SAGA.LogicalFile). Is this duplication required?

They are gone in the namespace by now, as the namespace has no open calls anyway... The flags for Files and LogicalFiles might well be different, so the duplication is needed there I think.

...

- the interfaces Stream and StreamServer implements Attributes, however Attributes does not exist. Is this Attribute (perhaps Attributes is a better name for this class)?

Good catch: we need to define these attributes. They are (for example) 'buffer size', 'reliable', etc. I have the list somewhere buried in my mail, and need to update the spec. Sorry...

...

- File.readP() and File.writeP() define input argument of type 'pattern'. This type is not defined by the SIDL API, is 'pattern' an undefined class or primitive type?

The pattern is a string - the API should be changed. thanks.

...

- in Stream void getContext (out context info); should read void getContext (out Context info);

Right, thanks.

...

- strawman_error.txt: "All objects in SAGA implement ErrorHandler...", the SIDL for these objects should indicate that they implement the ErrorHandler interface. The following objects: Directory File Job JobService LogicalDirectory LogicalFile Multiplexer Stream StreamServer Task TaskContainer ... any others ?

G.E.POUND＠soton.ac.uk

24 Jan 24 Jan

9:13 a.m.

New subject: [saga-rg] Queries and minor points

Andre, Thanks for the feedback. I have added a few further comments below. Graeme Quoting Andre Merzky :

...

Hi Graeme,

I am not sure if answers to that mail are still relevant - let me attempt to answer your points anyway, as far as I can...

A longer mail in respect to your details list of comments is in the pipeline as well - sorry for the delay... *sigh*

Quoting [Graeme Pound] (Nov 24 2005):

...
Please find below a couple of queries, and diverse minor points, which arose during my preparation of a Java implementation of the API. I anticipate that my comments on the semantics of the API will become a little more substantive in due course.

Thanks, Graeme

######### Queries

- I am little unclear of the purpose and operation of Attribute.getVectorAttribute() and Attribute.setVectorAttribute(). What is returned if a vector attribute is queried with getAttribute()? Why are a vector of values associated with a key required?

A use case is, as pointed out by Hrabri for instance, the specification of a list of email addresse to be notified on job completion:

[perl]

job.set_vector_attributes ('SAGA_JobContact', ('a@mai.com', 'b@mailcom'));

If a vector attribute key is set/queried with the scalar attribute call, and exception should be raised (NoSuchKey). Same for the other case.

Actually, I think that this model is not very nice. For one thing, we need an inspection interface (does that attribute exist? Is it a scalar or vector?). Also, we need to be clear if attribute can be scalars or vectors (if you set only one email?).

Sorry for not having a better answer...

It may be simpler to consider that all non-string attributes (including vectors of strings) are a special case. Many of the Attribute based interfaces require attributes of a specific type, in the current spec it is up to the user to cast to and from a String themselves. In the longer list of comments I raised the possibility that these interfaces could provide specific get and set methods for these attributes. Casting (or storing) values of a different type is then an issue for the implementation provider.

...

...
- contextType does not appear to be very extensible, how would different security models be specified?

The spec states that

A implementation CAN implement various types of Security contexts. or just one type.

and

Other types MAY be specified by a SAGA implementation.

which basically means that out of the types specified in the spec, and any other types you can think of, a non empty subset has to be implemented by the SAGA implementation.

So would an implementation extend (or redefine) the enumeration of context types?

...

...
######### Minor points

- Exceptions are not described in the SIDL interface, however Exception types are listed in long description of the methods (for example ReadOnlyAttribute and NoSuchKey). This information should be in the SIDL description as it is fundamental to the interface.

Yes, we probably should do that. Two reasons why we did not yet:

- it clutters the API definition visually - it would mean to maintain the exceptions in the SIDL and in the description part.

I think it is best to keep them detailed in the desciption part, and to copy them to the SIDL part during final edit. Does that make sense?

...
- capitalise ivec, openDirFlags, openFlags?

Well, ask 2 people about that and you get 5 answers ;-) Fact is, capitalization should be consistent through the API, and it is not currently. I think it is best if you choose a native java scheme for naming, I guess there is one?

Yes consistency within the API is important. Java has a well defined set of naming conventions (http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html#367). Where the SAGA API differs from the conventions of different languages, will the API be altered to meet those conventions in the language bindings?

...

...
- The enumerations openDirFlags and openFlags exist in the following packages SAGA.Namespace, SAGA.File and SAGA.LogicalFile (although SAGA.Namespace is imported by SAGA.File and SAGA.LogicalFile). Is this duplication required?

They are gone in the namespace by now, as the namespace has no open calls anyway...

The flags for Files and LogicalFiles might well be different, so the duplication is needed there I think.

Yes that sounds sensible.

...

...
- the interfaces Stream and StreamServer implements Attributes, however Attributes does not exist. Is this Attribute (perhaps Attributes is a better name for this class)?

Good catch: we need to define these attributes. They are (for example) 'buffer size', 'reliable', etc. I have the list somewhere buried in my mail, and need to update the spec. Sorry...

I actually raising the issue of the typo 'Attributes', but I prefer the typo to the interface name 'Attribute' (which is something of a misnomer).

Andre Merzky

23 Feb 23 Feb

11:01 p.m.

New subject: [saga-rg] Queries and minor points

Hi Graeme, its always fun to go randomly through a mail box - you'll ALWAYS find mails you did not answer, but should have... Well, this is another one, comments are included. Cheers, Andre. Quoting [G.E.POUND@soton.ac.uk] (Jan 24 2006):

...

Andre,

Thanks for the feedback. I have added a few further comments below.

Graeme

Quoting Andre Merzky :

...
[... vector attributes etc.]

A use case is, as pointed out by Hrabri for instance, the specification of a list of email addresse to be notified on job completion:

[perl]

job.set_vector_attributes ('SAGA_JobContact', ('a@mai.com', 'b@mailcom'));

If a vector attribute key is set/queried with the scalar attribute call, and exception should be raised (NoSuchKey). Same for the other case.

Actually, I think that this model is not very nice. For one thing, we need an inspection interface (does that attribute exist? Is it a scalar or vector?). Also, we need to be clear if attribute can be scalars or vectors (if you set only one email?).

Sorry for not having a better answer...

It may be simpler to consider that all non-string attributes (including vectors of strings) are a special case.

Many of the Attribute based interfaces require attributes of a specific type, in the current spec it is up to the user to cast to and from a String themselves. In the longer list of comments I raised the possibility that these interfaces could provide specific get and set methods for these attributes. Casting (or storing) values of a different type is then an issue for the implementation provider.

Yes, a note about setters/getters in language bindings made it to the spec by now.

...

...
...
- contextType does not appear to be very extensible, how would different security models be specified?

The spec states that

A implementation CAN implement various types of Security contexts. or just one type.

and

Other types MAY be specified by a SAGA implementation.

which basically means that out of the types specified in the spec, and any other types you can think of, a non empty subset has to be implemented by the SAGA implementation.

So would an implementation extend (or redefine) the enumeration of context types?

Yes, exactly - extend would be better I guess, or at least use values which are not taken by the spec.

...

...
...
- capitalise ivec, openDirFlags, openFlags?

Well, ask 2 people about that and you get 5 answers ;-) Fact is, capitalization should be consistent through the API, and it is not currently. I think it is best if you choose a native java scheme for naming, I guess there is one?

Yes consistency within the API is important.

Java has a well defined set of naming conventions (http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html#367). Where the SAGA API differs from the conventions of different languages, will the API be altered to meet those conventions in the language bindings?

The language bindings should meet the conventions for the specific language, if possible.

...

...
...
- The enumerations openDirFlags and openFlags exist in the following packages SAGA.Namespace, SAGA.File and SAGA.LogicalFile (although SAGA.Namespace is imported by SAGA.File and SAGA.LogicalFile). Is this duplication required?

They are gone in the namespace by now, as the namespace has no open calls anyway...

The flags for Files and LogicalFiles might well be different, so the duplication is needed there I think.

Yes that sounds sensible.

Well, that changed again :-P As namespace was changed into a class, and HAS constructors and open methods, the flags are needed there as well. So flags are now indeed duplicated through the API. SIDL does not support it, but the language bindings should probably do something like (Hartmut introduced that in our implementation): class saga::ns_entry { enum open_flags { Read = 0, ... } ... }; class saga::file : public ns_entry { typedef open_flags saga::ns_entry::open_flags; ... }; in order to avoid duplication. That won't be possible in all places I guess, as flags might differ slightly. I don't see a better solution though...

...

...
...
- the interfaces Stream and StreamServer implements Attributes, however Attributes does not exist. Is this Attribute (perhaps Attributes is a better name for this class)?

Good catch: we need to define these attributes. They are (for example) 'buffer size', 'reliable', etc. I have the list somewhere buried in my mail, and need to update the spec. Sorry...

I actually raising the issue of the typo 'Attributes', but I prefer the typo to the interface name 'Attribute' (which is something of a misnomer).

I agree. However, we decided at one point to stick to singular names: stream, file, attribute, job etc - we hade that mixed before... Thanks, Andre. -- "So much time, so little to do..." -- Garfield

6799

Age (days ago)

6890

Last active (days ago)

List overview

Download

5 comments

4 participants

participants (4)

Andre Merzky
G.E.POUND＠soton.ac.uk
Graeme Pound
Steven Newhouse