[saga-rg] Queries and minor points

[G.E.POUND at soton.ac.uk]

Andre,

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

Graeme



Quoting Andre Merzky <andre at merzky.net>:

> 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 at mai.com',
> 'b at 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).