RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

Here I go with my response which is shorter than I promised, as I was going to comment about stuff already solved this afternoon like the naming inconsistency in the SimpleService interface.

My response is sometimes not just a +1 or -1, sorry

a) Evidence interface:

For me, although it may sound like breaking our Simple... naming approach, the interface should be called HTTPEvidence in order to make it clearer to developers.

I'm OK with...
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName); 

... although if the interface was HTTPEvidence, we might avoid so many HTTP in the names of the methods. By the way, for naming consistency, headerExists should be HTTPHeaderExists.

This is clearer to me than the alternative of having newHTTPEvidence(Map map) and leave it up to the implementation on how to build the Map.

I'd create a new HTTPEvidence() -no args- and then I would putHTTPHeader(name, value) as many times as I want. It may be uglier than the newHTTPEvidence(Map map), but it is easier to understand for programmers and more language agnostic.

José commented: "Note that I'm not in favour of using Map<String,String> as it would bind us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4"... In general, I am in favour of doing things as general as possible and avoid shortcuts for a specific language, although it may create a given language binding of the API a bit more complex than it would have been by using shortcuts. I am worried about these shortcuts stopping interoperability (Perl software consuming information from a Java implementation of the DDR API).

So...

PROPOSED RESOLUTION A: I'd like a newEvidence method with no args and putHeader, getHeader and headerExists.

PROPOSED RESOLUTION B: +0.5 to Evidence-->SimpleEvidence. Let's be more direct by changing Evidence to HTTPEvidence (although we break our Simple... naming convention, as there is a more well known name than Simple).

b) Support for Property Terms distinct from PropertyRefs

PROPOSED RESOLUTION C ALERNATIVE 1: It sounds interesting.. it can be understood quickly and it is easy to use but

PROPOSED RESOLUTION C ALERNATIVE 2: we should be consistent to the PropertyName and PropertyRef concepts, so +1 to this and -1 to the latter.

> c) Additional proposed resolutions
> 
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
> 
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
> 
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
to
> newSimplePropertyRef

Res D: +1, it is easier to understand the purpose of the method.
Res E: +1, for the same reason
Res F: I concur, although it might make sense in order to be consequent with other naming decisions. Particularly, I find the PropertyRef name a bit cryptic but no other good options come to my mind (PropertyAspectBinding sounds too long, but it is a bit more clear).

I must say that sometimes it is difficult for me to balance between the ease-of-use and formality when choosing alternatives in the design of the API and I find myself voting for easiness in a situation while trying to keep things formal in another :-(

Regards and sorry for the delay on my answer,

Nacho

-----Mensaje original-----
De: Jo Rabin [mailto:jrabin@mtld.mobi] 
Enviado el: martes, 26 de febrero de 2008 15:47
Para: Ignacio Marin; public-ddwg@w3.org
Asunto: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

I'm about to post a link to some Java which I think represents group
consensus, so if you could give your comments on that, that would be
great.

Thanks


> -----Original Message-----
> From: Ignacio Marin [mailto:ignacio.marin@fundacionctic.org]
> Sent: 26 February 2008 14:45
> To: Jo Rabin; public-ddwg@w3.org
> Subject: RE: Final chance, for now, to offer opinion on Simple API
[was
> Continuation of discussion from today's call]
> 
> I shall answer this tonite.
> I have barely had the chance to be connected since I left yesterday's
> teleconference and my opinion will take some time to be expressed (it
> will not be only +/-1 or 0).
> 
> I'll respond in some hours (4 hours more or less, as I will be in a
> meeting outside CTIC and then in the University doing some teaching)
and
> I hope you'll accept it as being sent today O:-)
> 
> Regards,
> 
> Nacho
> 
> 
> -----Mensaje original-----
> De: public-ddwg-request@w3.org [mailto:public-ddwg-request@w3.org] En
> nombre de Jo Rabin
> Enviado el: martes, 26 de febrero de 2008 8:53
> Para: public-ddwg@w3.org
> Asunto: Final chance, for now, to offer opinion on Simple API [was
> Continuation of discussion from today's call]
> 
> 
> What follows is an edited version of what I sent yesterday. Apologies
> for sending it to the wrong list initially.
> 
> Aside from Rotan there have been no contributions. For the sake of
> getting a document ready for the Face to Face I am going to start work
> later this afternoon on a draft. In the absence of response I will
take
> it as a "+1" to all resolutions except C Alternative 1.
> 
> Jo
> 
> Contents:
> 
> a) what is the signature of the Evidence interface?
> b) how are underlying PropertyNames to be supported?
> c) Misc renames for consistency
> 
> Urgency:
> 
> The important thing is to resolve this TODAY [that was yesterday] so
we
> can have a substantive draft for discussion in Seoul next week,
> following which we will issue a First Public Working Draft which "with
a
> fair wind and a
> following sea" (colloq. = with luck) will also be a Last Call working
> draft.
> 
> Other Tasks
> 
> We also need to have debate on this list as to the wording of the
> remaining sections of the document - especially Conformance.
> 
> ---
> 
> Let's fix the interface first.
> 
> a) Evidence interface
> 
> PROPOSED RESOLUTION A: The Evidence interface is
> 
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);
> 
> A factory method is added to SimpleService:
> 
> Evidence newEvidence(HashMap<String, String> httpHeaders)
> 
> The reasoning is as follows:
> 
> The caller needs a way to put evidence into a known object in a
> standardised way. The API must support HTTP Evidence in the form of
> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> Header Field value, both strings (ASCII stings, actually, but, er,
let's
> leave that point aside unless we have to).
> 
> The retrieval methods are there so that an object created by some
other
> instantiation method can still be queried by the any implementation,
> although that might not be very efficiently, it does allow inter
> working.
> 
> It is likely that most Java implementations will want to allow the
> passing of a HashMap<String, String> derived directly e.g. from the
jsp
> infrastructure. However, in general this doesn't work as we can't rely
> on support of a HashMap<String, String> structure in other
environments
> / languages, so the factory method will probably look different in the
> IDL.
> 
> It ought also to be a documentation and conformance point that HTTP
> Header Field names are treated case insensitively.
> 
> I think we should call this SimpleEvidence (or HTTPEvidence) to
> distinguish it from any other sort of evidence.
> 
> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
> 
> b) Support for Property Terms distinct from PropertyRefs
> 
> Rotan has discussed this in clear terms that I could not hope to match
> [1].
> 
> In essence we have 2 proposals, Rotan's which is to overload the
> semantic of PropertyRef so it can be aspectless, and mine, which is to
> keep the PropertyName class and add a couple of factory methods - one
to
> PropertyName and the other to SimplePropertyValue, so we don't have to
> refer to any inheritance relationships between them.
> 
> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> SimplePropertyRef propertyRef) where the aspect parameter overrides
> whatever aspect is present in the propertyRef and throw exceptions
> appropriately
> 
> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API
and
> can be constructed from a PropertyRef by a factory method. A
PropertyRef
> can be created from a PropertyName by a factory method naming the
> aspect.
> 
> 
> c) Additional proposed resolutions
> 
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
> 
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
> 
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
to
> newSimplePropertyRef
> 
> 
> That's it folks - pls send +1s etc. to this list asap
> 
> Jo
> 
>

Received on Tuesday, 26 February 2008 22:57:28 UTC