Re: [API-DOC] Change-Proposal

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
> _____________________________
>
>

Received on Thursday, 3 February 2011 08:45:15 UTC