RE: Feedback about the current API design

Dear Lawrence, all,

 

I already answered to you personally on the questions you had, but I will
repeat them here so everybody can see them.

 

As for the exception remarks, I agree that error codes can also be used. And
probably are more interesting (for language issues and such). Currently we
have not discussed (at all) what kind of exceptions should be raised so this
was just a first step.

 

For the arrays I use, I have based myself on a W3C Editor's draft from 30
august 2009 (http://dev.w3.org/2006/webapi/WebIDL/) which does include
arrays in such ways.

 

Finally, the inheritance of the unstructured interface is included because
we want to allow the possibility that the return value is in fact an
unstructured string (for example if we don't know what the first and last
name is of a  creator, we might return an unstructured string containing
both. In that case it is up to the application to parse the unstructured
value.)

 

Kind regards,

Chris 

 

 

From: public-media-annotation-request@w3.org
[mailto:public-media-annotation-request@w3.org] On Behalf Of Lawrence Miao
Sent: dinsdag 22 september 2009 13:48
To: public-media-annotation@w3.org
Subject: Feedback about the current API design

 

Dear All

 

I've sent feedback to the co-editors already. As requested, I summarized the
feedback here. 

 

1. About the RESULT design

*	Chri's has an approach by defining each type of Error as an
interface with a string member denoting the error message. 
*	I proposed another two approaches: First one, use the
[ExceptionConstant] extend attribute documented at Web IDL specs [1] section
3.8.3. The [ExceptionConstant] is created to help documenting error code
like exceptions. Here's the example:
[ExceptionConsts=FileIOExceptioin]
module fileio {
    exception FileIOException {
        unsigned short code;
    }

   const unsigned short FILE_NOT_FOUND = 1;
   const unsigned short READ_ERROR = 2;
   const unsinged short WRITE_ERROR = 3;
}
*	The second approach is refering BONDI [2] which is a Web IDL based
API sepcification for web runtime applications. In BONDI, the exceptions are
documented as normal 'interface' other than 'exception', as Web IDL
'exception' does not support inheritance. In the design pattern document of
BONDI [3],  it contains the purpose behind their design. Here's the example:
interface GenericError {    
     readonly attribute unsigned short code; 
}; 

interface DeviceAPIError : GenericError {    
     const unsigned short UNKNOWN_ERROR           = 10000;    
     const unsigned short INVALID_ARGUMENT_ERROR  = 10001;
     const unsigned short NOT_FOUND_ERROR         = 10002;    
     const unsigned short PENDING_OPERATION_ERROR = 10003;    
     const unsigned short IO_ERROR                = 10004;
     const unsigned short NOT_SUPPORTED_ERROR     = 10005;
};

2. About the array type:

*	As I know, the way to define an array in Web IDL is using the
sequence<T> type. In the current document, the array is documented as T[].
Since Web IDL defines the binding to other languages, in order to make our
API successfully be generated to specific language libraries, we'd better
follow the exact syntax. 

Here's an example:

typedef sequence<Object> ObjectArray

typedef sequence<DOMString> StringArray

3. About the returnType

*	The question is why we inherit each interface to Unstructured
interface?

 

If allowed, let's discuss it in today's meeting. 

 

Best Regards, 

 

Hui

 

[1] http://www.w3.org/TR/WebIDL/

[2] http://bondi.omtp.org/default.aspx

[3]
http://bondi.omtp.org/1.01/apis/BONDI_Interface_Patterns_v1.0.html#errorhand
ling