[API-DOC] Change-Proposal

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 Friday, 28 January 2011 11:21:35 UTC