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

One of our duties, and in general W3C's, is to create technologies that 
can be used in scenarios not previously envisaged, so I think that our 
SimpleEvidence interface should not name HTTP at all while at the same 
time stating in conformance statements that implementation must deal 
with evidence that represents HTTP headers

The schema of name-value pairs is a very flexible one and allows to be 
used in different adaptation scenarios not only the typical Mobile Web, 
so let's create flexible technology and interfaces

Best Regards

Rotan Hanrahan escribió:
> The Evidence/SimpleEvidence/HTTPEvidence naming question continues...
>
> I will use Java as an example to do some exploration of the issue, which might help other people who are thinking about this too.
>
> In Java, the TreeMap class [1] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfTree() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Hashtable class [3] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfHashtable() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Attributes class [4] supports the Map interface.... ok you get the picture by now.
>
> The interface is supposed to be general if there is a possibility of re-use. In the case of the Simple API we have already had discussion where we recognise that some implementations are likely to want to support better forms of evidence. So it seems that, like the Java Map interface, there should be a general interface for Evidence. Even if this is just to identify what can be passed as a parameter in a query method.
>
> Separate factory methods can produce instances of classes that implement the Evidence class, and these can be instances of things that represent HTTP headers, or things that represent other identifying data.
>
> But, I hear you say, this is surely just the "Simple" API, so why does it matter if its called Evidence, SimpleEvidence or HTTPEvidence?
>
> It might matter because any implementation that tries to offer anything more than HTTP header evidence will still have to pass the evidence objects to the query methods as if they were supporting "HTTPEvidence", when in fact they are not HTTP evidence at all. They are just "evidence". So a generic interface name would be better.
>
> However, there is an alternative view.
>
> If a custom implementation provides a custom factory in the SimpleService to produce an instance of a custom SuperEvidence class, then it should be possible for this implementation to also provide custom overloaded query methods that take a SuperEvidence object instead of an instance of some class that implements the HTTPEvidence interface. Given that the SuperEvidence class is not dealing with HTTP headers, there's no reason for it to implement the HTTPEvidence interface, so we don't cause any polymorphic ambiguity. Plus, the Simple API is now a proper subset of the enhanced custom implementation, so the custom implemention can still claim to be conformant (so long as nobody uses the enhanced features).
>
> So, my position is that I don't really mind if the Simple API uses an interface called Evidence or one called HTTPEvidence. If the former, then any enhancements I offer will also implement Evidence though I'll add a few more interfaces for good measure. If we decide to call the interface HTTPEvidence, then any enhancements I offer will implement their own evidence interfaces and I'll overload the getPropertyValue* methods. In both cases, I'll also be providing custom factories.
>
> So I'm now "0" on this question :)
>
>
> ---Rotan
>
>
> [1] http://java.sun.com/j2se/1.4.2/docs/api/java/util/TreeMap.html
> [2] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html
> [3] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Hashtable.html
> [4] http://java.sun.com/j2se/1.4.2/docs/api/java/util/jar/Attributes.html
>
>
>
> ________________________________
>
> From: public-ddwg-request@w3.org on behalf of Ignacio Marin
> Sent: Tue 26/02/2008 22:57
> 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]
>
>
>
>
> 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 Wednesday, 27 February 2008 06:55:36 UTC