W3C home > Mailing lists > Public > public-media-annotation@w3.org > February 2011

AW: [API-DOC] Change-Proposal

From: Bailer, Werner <werner.bailer@joanneum.at>
Date: Thu, 3 Feb 2011 12:01:00 +0100
To: Florian Stegmaier <stegmai@dimis.fim.uni-passau.de>, "public-media-annotation@w3.org" <public-media-annotation@w3.org>
Message-ID: <CD9846F872C7874BB4E0FDF2A61EF09F965B789347@RZJC1EX.jr1.local>
Dear Pierre-Antoine,

+1 for your proposal.

Concerning the first point: making it more similar to get the status code would either mean querying the status code separately in sync mode (very unusual for Web services), or get result + status in one callback in the async mode (different than the other examples of async APIs we have seen from other groups).

On the second point: again, this would mean two calls in sync mode or exceptions, both which are probably worse choices.

Best regards,
Werner

________________________________________
Von: public-media-annotation-request@w3.org [public-media-annotation-request@w3.org] im Auftrag von Florian Stegmaier [stegmai@dimis.fim.uni-passau.de]
Gesendet: Donnerstag, 03. Februar 2011 10:25
An: public-media-annotation@w3.org
Betreff: Re: [API-DOC] Change-Proposal

Dear Pierre-Antoine!

Thanks for your feedback! Itīs really more than welcome! The solution to have these two lists was more or less a less-than-ideal solution, but we could not think of a better way to do it.

I really like your idea to have the status code directly in the MediaAnnotation interface! This would be also really nice to get rid of a special return type interface (this was the second thing i donīt really like in my proposal).

+1 to your proposal!

Any other ideas/comments/remarks?

Best,
Florian

Am 03.02.2011 um 08:30 schrieb Pierre-Antoine Champin:

> Hi Florian,
>
> Thanks to you, Werner and Martin for working on this tricky problem. The solution you propose seems to solve it, and you explained clearly the rationale of your choices.
>
> However, I still have a few bad feelings about them... (note that I am not a JS programmer, so my remarks may not be relevant).
>
> First, I would rather have a consistent way to get the statusCode across the three sync methods. But I must admit that I can't find a satisfying way to do that...
>
> Second: I'm not sure it is a good idea to mix the status code with the actual results in the list returned by getPropertyNamesHavingValues and getOriginalMetadata. But on the other hand, this is the lightest way to do it, so I can live with that.
>
> Third: with getMediaProperty, I'm not a big fan of mapping statusCodes and MediaAnnotations by their index in two different lists. It bother me all the more that in case of a failure, there will not be a one-to-one mapping.
>
>
> Regarding my third point, here's another proposal -- with all due respect to the work you three have provided... may be you've been there too and decided that it was a bad idea!
>
> I remember at the last telecon, you mentioned the possibility to add a statusCode field directly in the MediaAnnotation structure. I think I like that idea better:
> * getMediaProperty would simply return a list of MediaAnnotation;
> * if it fails, the list will contain a single MediaAnnotation with a failure statusCode, and all other fields undefined or set to null;
> * else, it will return a list of MediaAnnotation, each with its own statusCode.
>
>  list = mr.getMediaProperty("contributor");
>  if (list[0].statusCode == STATUS_FAIL) {
>    ...
>  } else {
>      for (i=0; i<list.length; i++) {
>          ... // look for individual statusCode at list[i].statusCode
>          ... // or retrieve other properties of list[i]
>      }
>  }
>
> what do you think?
>
>  pa
> On 01/28/2011 12:20 PM, Florian Stegmaier wrote:
>> Dear all,
>>
>> today in the morning, i had a discussion with Werner and Martin regarding the API document. At first we try to focus on the WebIDL specification, before addressing the textual changes.
>>
>> Against my first idea, we consider to stick to the (already specified) two scenarios, but mention which communication mode they use by default. The first scenario (user agent) uses by default the asynchronous mode whereas the Web service scenario is using the synchronous mode.
>>
>> ##Letīs start with the async mode:
>> Since i am no C(++) programmer, the design of the async mode is not quiet clear to me, but Werner and Martin said, this would be fine. In the case of the first use case, it is suitable to be implemented. In the second use case, it would be possible, if the client also is able to manage the responses in the right way. This is no conflict to our spec and furthermore, the default mode for a Web service is sync.
>>
>> ##Regarding the sync mode:
>> Here we had the issue, that it is a little bit tricky to handle call by reference calls with Web services. We propose the following change to the synchronous mode:
>>
>> [NoInterfaceObject, Constructor(in DOMString mediaResource, in optional MetadataSource[] metadataSources)]
>> interface MediaResource {
>>     SyncResponse getMediaProperty (in DOMString propertyName, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString subtype, in optional DOMString language);
>>     DomString[] getPropertyNamesHavingValues (in optional DOMString sourceFormat, in optional DOMString language, in optional DOMString fragment);
>>     DomString[] getOriginalMetadata (in DOMString sourceFormat);
>> };
>>
>> interface SyncResponse {
>>     attribute    short[]                         statusCode;
>>     attribute    MediaAnnotation[]   mediaAnnotations;
>> }
>>
>> For clarification:
>> i) The "getMediaProperty" method needs a special return type, because the status codes may be bound to specific properties in a strict implementation (e.g., if it is a structured type or not). Here we have the response object containing two lists and the following to cases may arise:
>>    * Error in processing the request: the associated status code will be inserted in the statusCode list, the mediaAnnotations list is empty
>>    * Properties are retrieved: mediaAnnotations list is filled with the annotations, related to this, the status code for each property is saved in the statusCode list (mediaAnnotations[i] = statusCode[i])
>> ii) "getPropertyNamesHavingValues" only retrieves all property names, that carry values. Here the status is not linked to a single property (we donīt get informations whether the property is structured or not). The status code will be always at the first position of this array, identifying the state of processing
>> iii) "getOriginalMetadata" extracts the original metadata informations - status unbound, so always at the first position.
>>
>> It would be nice, if we could have a resolution in the teleconf on Tuesday regarding the API doc in order to move on.
>>
>> Best,
>> Florian
>> _____________________________
>> Dipl. Inf. Florian Stegmaier
>> Chair of Distributed Information Systems
>> University of Passau
>> Innstr. 43
>> 94032 Passau
>>
>> Room 248 ITZ
>>
>> Tel.: +49 851 509 3063
>> Fax: +49 851 509 3062
>>
>> stegmai@dimis.fim.uni-passau.de
>> https://www.dimis.fim.uni-passau.de/iris/
>> http://twitter.com/fstegmai
>> _____________________________
>>
>>

_____________________________
Dipl. Inf. Florian Stegmaier
Chair of Distributed Information Systems
University of Passau
Innstr. 43
94032 Passau

Room 248 ITZ

Tel.: +49 851 509 3063
Fax: +49 851 509 3062

stegmai@dimis.fim.uni-passau.de
https://www.dimis.fim.uni-passau.de/iris/
http://twitter.com/fstegmai
_____________________________
Received on Thursday, 3 February 2011 11:06:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 3 February 2011 11:06:31 GMT