The BONDI API Design Patterns - Version 1.01

27 July 2009

2. WebIDL patterns

2.1. Error Handling

Motivation and problem statement

WebIDL allows methods, getters and setters to raise not only exceptions, but also objects that expose given interfaces. WebIDL exceptions cannot be inherited and therefore no hierarchy of exceptions can be built. However, within BONDI each module is able to define its own error interface. Thus, to support hierarchy of errors within BONDI, we are going to use only error interfaces for which a specific inheritance hierarchy has been built.

Solution

• Exceptions MUST NOT be defined within BONDI WebIDL.
• All the error interfaces within BONDI WebIDL MUST inherit (directly or indirectly) from BONDI generic error interface, GenericError, whereas GenericError directly inherits from ECMAScript's Error.
• Only objects instantiating interfaces that inherit from GenericError MAY be raised by BONDI methods and attributes' getters and setters.
• Error objects MUST be uniquely identifiable by error object's prototype, constructor as well as the error codes that are attribute of the GenericError object.
• Security-related error interfaces MUST inherit from SecurityError, whereas SecurityError MUST directly inherit from GenericError.
• Error code constants MUST have the following syntax:
  • They must be defined in uppercase.
  • Words with the error constant definition must be separated by "_" (underscore) character.
  • The constant name MUST be postfixed with "_ERROR".
  • Common error codes MUST be grouped in DeviceAPIError interface that MUST directly inherit from GenericError.
  • Module specific error constants MUST start with the value of 0 (zero).
  • Common error codes must be in the range of 10000-19999.
  • Security-related error codes must be in the range of 20000-29999.
  • The specification of the error code in the doxygen-like format MUST follow the format specified in format for WebIDL method.

WebIDL definition

interface Error {

        readonly attribute DOMString name;

        readonly attribute DOMString message;
};

interface GenericError : Error {

        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;
};

interface SecurityError : GenericError {
        const unsigned short PERMISSION_DENIED_ERROR = 20000;
};

2.2. Asynchronicity

Motivation and problem statement

ECMAScript methods can be either synchronous or asynchronous. Methods using the synchronous mode of operation do not return control to the caller until the operation is complete. Asynchronous methods return immediately and notify the caller at some point in the future of the results via callback method(s). The callback methods are specified as parameters to the asynchronous method. The following rules describe how to specify asynchronous methods in BONDI WebIDL.

Solution

• Each asynchronous method MUST have at least two parameters, as follows:
  • the first parameter MUST be a Function object instantiating or inheriting from SuccessCallback interface,
  • the second parameter MUST be a Function object instantiating or inheriting from ErrorCallback interface.
• Each asynchronous method MUST return PendingOperation object or null. When null is returned, it means that one of the callback functions was executed prior to the accomplishment of the asynchronous method.
• The PendingOperation interface MUST enable cancellation of the asynchronous method call by means of the "cancel" method of this interface. The "cancel" method has the following characteristics:
  • it is synchronous
  • it is always successful, i.e. the asynchronous operation is either cancelled or immediately accomplished,
  • it returns a boolean value with the following meaning:
    • true - if one of the callback functions (instantiating or inheriting from SuccessCallback or ErrorCallback) has been called during the call to this method
    • false - otherwise, i.e. the pending operation was just cancelled, without being accomplished either successfully or erroneously, and none of the callbacks were called.

WebIDL definition

[Callback] interface SuccessCallback {

        void onSuccess(in Object ob);

};

[Callback] interface ErrorCallback {

        void onError(in Error error);

};

interface PendingOperation {

        boolean cancel();

};

2.3. Versioning

Motivation and problem statement

It is assumed that the BONDI interfaces will evolve over time. The interfaces defined within BONDI Release 1.0 may be modified in future releases of the BONDI specifications. They may add new methods or attributes, they may remove them or modify the way they operate. Therefore a versioning model is defined that will enable widgets to be installable and to function properly on WUAs that are equipped with the appropriate implementation of the APIs.

Solution

iquery         = *( ipchar / iprivate / "/" / "?" )

iquery             = iqueryversion / iqueryversionrange / iquerynext
iquerynext         = *( ipchar / iprivate / "/" / "?" )
iqueryversion      = %x76.3d DIGIT *(DIGIT) %x2e DIGIT *(DIGIT) %x2d DIGIT *(DIGIT) %x2e DIGIT  *(DIGIT) %x3f iquerynext
iqueryversionrange = %x76.3d DIGIT *(DIGIT) %x2e DIGIT *(DIGIT) %x3f iquerynext

It should be noted that iquery is the non-hierarchical part of IRI, therefore it is able to provide versioning to all parts of the IRI used throughout BONDI specifications, include BONDI Architecture & Security. By using the query part, we state that we mean the same resource (i.e. API), but we refer to some specific version of it (IRI semantics).

Query being non-hierarchical allows for defining APIs (being hierarchical) to be grouped by the query part, thus being orthogonal to the API hierarchies.

http://bondi.omtp.org/api/filesystem.read?v=1.0

http://bondi.omtp.org/api/filesystem.read?v=1.0-2.0.

3. Documentation patterns

3.1. General format

Motivation and problem statement

Solution

        /**
         * \brief Messaging specific error callback.
         *
         * This callback error interface is specific to this messaging API. It
         * specifies a error callback with a function taking an MessagingError object
         * input argument.
         */
        [Callback] interface MessagingErrorCallback {
                void onError(in MessagingError error);
        };

The documentation syntax MUST begin with the line that includes only "/**" and white-space characters (space, tab or new line). Each of the subsequent documentation lines MUST begin with "*" and the final documentation line MUST consist of only "*/" and white-space characters. Each line of the documentation MAY include up to one keyword, i.e. a token prefixed with the backslash ("\") character. The following keywords are available for BONDI widl documentation:

• brief - provides a short comment about the functionality
• n - specifies new line in the resulting HTML documentation of the widl
• code - introduces the sample code snippet
• endcode - ends the sample code snippet
• def-api-feature - defines the API feature used in the security model
• device-cap - refers to the device capability that is associated with API feature defined by def-api-feature
• def-device-cap - defines the device capability
• param - specifies the parameter of the device capability or the parameter of the WebIDL method
• author - provides name and email address of the module author's
• throw - specifies the error object that MAY be thrown by a method, a getter or a setter
• return - specifies the type of value that is returned by a method

3.2. Common types, errors and interfaces

Motivation and problem statement

Solution

• Type definitions
  • StringArray
  • ByteArray
  • ShortArray
  • LongArray
  • FloatArray
• Callback functions
  • SuccessCallback
  • ErrorCallback
• Error interface definitions
  • GenericError inheriting from ECMAScript's Error
  • DeviceAPIError inheriting from GenericError
• Error constants
  • UNKNOWN_ERROR
  • INVALID_ARGUMENT_ERROR for invalid parameter specification
  • NOT_FOUND_ERROR for failing search operation
  • PENDING_OPERATION_ERROR for notification about a pending operation
  • IO_ERROR for input/output error
  • NOT_SUPPORTED_ERROR for unsupported feature

The PendingOperation interface MUST also be specified in bondi.widl.

3.3. Documentation syntax

Motivation and problem statement

• module for module definition
• interface for interface definition
• typedef for type definition
• attribute for attribute definition
• const for constant definition

Solution

3.3.1. Documentation format for WebIDL module

• brief - Brief description of the module functionality
• Module description in free text
• def-api-feature - A description of all the API features used by the module
• def-device-cap - A description of all the Device Capabilities used by the module
• author - Module authors
• version - Module version

    /**
     * \brief 
     *
     * 'module description'
     *
     * \def-api-feature 'API Feature Identifier'
     * \brief 'API Feature brief description'
     *
     * 'API Feature detailed description (optional, blank line above not needed if absent)'
     * \device-cap 'Identifier of related Device Capability'
     * 'optional brief description of circumstance in which that device cap is used'
     *
     * ...
     * \def-device-cap 'Device Capability Identifier'
     * \brief 'Device capability brief description'
     *
     * 'Device Capability detailed description (optional, blank line above not needed if absent)'
     * \param 'security parameter name' 'brief description'
     * ...
     *
     * \author 'Name' 'e-mail'
     * \version 'API version'
     *
     */
     module foo {
      ...
     };

3.3.2. Documentation format for WebIDL interface

• brief - Brief description of the interface functionality
• Module description in free text
• code and endcode - A sample code to present the usage of the interface

    /**
     * \brief 'Brief interface description'
     *
     * 'Detailed description of the interface'
     *
     * \code
     * 'Code Example'
     * \endcode
     */
    interface fooInterface {
    ...
    }

For instance, in the case of the FileSystemManager Interface

    /**
     * \brief FileSystemManager API.
     *
     * This file system API provides basic filesystem access.
     *
     * \code
     *    var dir = bondi.filesystem.mount(fs.getDefaultLocation("app:public"));
     *    var files = dir.listFiles();
     *    for(var i = 0; i < files.length; i++) {
     *      alert(files[i].name); // displays name of each file in directory
     *    }
     *    var file = dir.createFile("test.txt");
     *    var out  = file.open("w", "UTF-8");
     *    // writes Hello World to test.txt
     *    out.write("Hello World");
     *    out.close();
     * \endcode
     */
    interface FileSystemManager {

3.3.3. Documentation format for WebIDL attribute

• brief - Brief description of the attribute
• More detailed description of the attribute, including that the attribute is read-only and also related requirements
• code and endcode - A sample code to present the usage of the attribute

Additionally, read-write attributes MUST include a description of the possible errors and the conditions in which they are raised when setting or getting the value of the attribute based on the setraises or getraises WebIDL keywords.

• throw - Specification of errors that may be thrown and the circumstances under which they are raised.

 /**
  * \brief 'brief attribute description'
  *
  * 'detailed attribute description'. 
  * This attribute is read-only
  * \code
  *   'example code'
  * \endcode  
  */
  readonly attribute 'type' 'name'

 /**
  * \brief Contains the implementation dependent maximum path length.
  *
  * This attribute is read-only.
  *
  * \code
  *    alert(bondi.filesystem.maxPathLength);
  * \endcode
  */
  readonly attribute long maxPathLength;

 /**
  * \brief 'brief attribute description'
  *
  * 'detailed attribute description'. 
  * This attribute is read-only
  *
  * \code
  *   'example code'
  * \endcode  
  * \throw 'error object and code to be thrown' 'conditions in which is thrown'
  */
  attribute 'type' 'name'
       setraises('errorobject');

  /**
    * \brief Get/set current position in this stream.
    *
    * The position of this stream is an offset of bytes from the start
    * of the file stream.  When invoking an operation that reads or writes
    * from the stream, the operation will take place from the position
    * in the position attribute.
    *
    * \code
    *   alert(stream.position); // displays current stream position
    *   // alters current stream position to the begin of the file,
    *   // like seek() in C
    *   stream.position = 0;
    * \endcode
    * \throw FileSystemError IO_ERROR if invalid position was given.
    */
    attribute long position
              setraises(FileSystemError);

3.3.4. Documentation format for WebIDL method

• brief - Brief description of the method
• More detailed description of related requirements
• code and endcode - A sample code to present the usage of the method
• param - Specification of every input argument
• return - Specification of the return value
• throw - Specification of errors that may be thrown and the circumstances under which they are raised

 /**
   * \brief 'Method's brief description'
   *
   * 'Method's long description'
   *
   * \api-feature 'API Feature ID' 'optional brief description'
   *
   * \code
   * 'example code'   
   * \endcode
   *
   * \param 'name' - 'description'
   * \return 'description of the return value'
   * \throw 'errorobject' 'error code' if 'error condition'
   */

3.3.5. Documentation format for WebIDL constant

• brief - Brief description of the constant
• More detailed description of the constant including related requirements
• code and endcode - A sample code to present the usage of the constant

 /**
   * \brief 'Constant's brief description'
   *
   * 'Constant's long description'
   *
   * \code
   * 'example code'   
   * \endcode
   *
   */

3.3.6. Documentation format for WebIDL type

• brief - Brief description of the type
• More detailed description of the type including related requirements
• code and endcode - A sample code to present the usage of the type

 /**
   * \brief 'Type's brief description'
   *
   * 'Type's long description'
   *
   * \code
   * 'example code'   
   * \endcode
   *
   */