BONDI Feedback APIs

From MemberWiki

Jump to: navigation, search

Contents

About this wiki page

This wiki page is one of several wiki pages that OpenAjax Alliance will use to collect feedback from its members via its wiki about the BONDI 1.0 Release Candidate specifications. The key review period goes from 'Feb. 12-25, 2009. See BONDI for more information about this BONDI review and feedback initiative. The full set of wiki pages is as follows:

  • BONDI - Main wiki page
  • BONDI Feedback APIs - Feedback page relative to the general approaches that OMTP is using for its APIs. Are the APIs understandable, familiar in approach, and convenient to JavaScript developers?
  • BONDI Feedback Security - Feedback page relative to the security features in BONDI. Is the design robust? Are there any security holes? Are the security features easy enough to use?
  • BONDI Feedback Enterprise - Enter any detailed spec errors on this wiki
  • BONDI Evangelism - Possible ways that OpenAjax Alliance might be able to help evangelize BONDI
  • BONDI V2 Wishlist - OMTP will start discussion about future versions of BONDI in March 2009. This wiki page collects any feature requests from OpenAjax members.
  • BONDI History - Quick introduction of historical activities leading up to BONDI initiative

BONDI Feedback: APIs

Introduction

This wiki page contains feedback from members of OpenAjax Alliance on the general approaches that OMTP is using for its APIs. Are the APIs understandable, familiar in approach, and convenient to JavaScript developers?

API Overview

bondi global object

Q: How does it get onto the 'window' object?

(a) Presumably the long-term preferred path would be that the 'bondi' global object would just be there as a built-in feature within a browser (either native to the browser or added when a BONDI browser plugin initiatizes). Correct?
(b) In the short-term, sometimes the web page might have to invoke browser-specific dynamic loading features, such as ActiveX on IE. Correct?

Feedback

Please bracket comment with your name, eg [jonferraiolo]...[/jonferraiolo].

[jonferraiolo]Where is the detailed documentation of the bondi global variable? Is there an overall BONDI Developer's Guide or other overview document? It's difficult to get started with reviewing BONDI without that information.[/jonferraiolo]

bondi.load()

Q: Suppose you need a particular feature, such as accessing the file system. When is it necessary to invoke bondi.load() within a Web page to access that feature?

(a) It is a BONDI requirement in all possible cases that you must always load a feature before it can be used.
(b) For W3C Widgets, you don't have to load a feature because that will be done for you by the widget engine in response to <feature> elements; however, when running in browsers, you always have to load the features you need.

Q: Is there a bondi.unload()?

Q: The documentation for AddressBook shows the following example: 

bondi.load('pim.contact', { id: 'contact', success, failure });

What's going on here? That's incorrect JavaScript. Do you mean: 

(a) bondi.load('pim.contact', { id: 'contact', success: successCB, failure: failureCB });

or 

(b) bondi.load('pim.contact', { id: 'contact'}, successCB, failureCB );

Q: What is the first parameter ('pim.contact' in this example)?

Q: The second parameter appears to be an object. What are all of the properties that are defined for that object? What are the extensibility rules: can particular implementations define implementation-specific properties? If so, are there particular naming conventions that must be followed to prevent two extensions from colliding?

Q: How do you get the JavaScript object which holds the APIs that you have loaded?

(a) Does bondi.load() return an object?
(b) Is the the first parameter (in the above example, 'pim.contact') the name of the JavaScript global onto which the APIs will be placed?

Q: What are the signatures (i.e., parameters) for the success and failure callback functions? How is scope established (i.e., what is the "this" object for the callback functions)?

Q: What are the rules about throwing exceptions? For example, can callbacks throw exceptions?

Feedback

[jonferraiolo]Where are the detailed docs for bondi.load? Difficult to provide feedback without basic documentation of how modules get loaded. None of the (three) sample widgets show the use of bondi.load().[/jonferraiolo]

[jonferraiolo]Really want to understand the details about bondi.load() and how the async features work. Can only speculate at this point, but most of the likely options for how it appears that bondi.load() works would be weird for JavaScript developers.[/jonferraiolo]

[jonferraiolo]Need to have a clear strategy and clear set of rules regarding extensibility.[/jonferraiolo]

[jonferraiolo]Need to have a clear idea about setting up the "this" object.[/jonferraiolo]

[jonferraiolo]Need to have a clear strategy and clear set of rules regarding exceptions.[/jonferraiolo]

[jonferraiolo]The BONDI team might want to look at these two web pages:

They contain various best practices that OpenAjax has defined for implementing and using our OpenAjax Hub. There might be value in reviewing this wiki page for ideas for a checklist of the various details that BONDI needs to think about and document in the BONDI specs.[/jonferraiolo]

File system APIs

Example from BONDI specs: 

    var root = fs.mount(fs.getPersistLocation());
    for(var i = 0; i < root.length; i++) {
        alert(root[i].name); // displays name of each file in root
directory
    }
    var file = root.createFile("test.txt");
    var out  = file.open("w");
    // writes Hello World to test.txt
    out.writeLine("Hello World", "UTF-8");
    out.close();

Q: How is "fs" object created?

Q: Regarding fs.getPersistLocation():

(a) always return the same location for any given widget or web page?
(b) why does it return a string instead of an opaque object?
(c) is the returned location a full path within the device's local file system or a partial path or a virtual path of some sort?
(d) Why is a mimetype passed to getPersistLocation? Wouldn't you first get a

Q: Regarding fs.mount()

(a) The parameter ('location') says "must be absolute in the file system". You mean that a widget deals with full path names on the device itself?

Q: Regarding events (both file systems and FileStreamListener)

(a) Why would a widget care if there was a mount event or an unmount event? Is this so a widget knows that someone else mounted a virtual file system, or that this same widget mounted a virtual file system?

Q: Regarding writeLine() and readLine()

(a) why is encoding passed with each line, versus setting up the encoding when the stream is created?
(b) what happens with newlines?

Q: Regarding File.moveTo()

(a) What is Runnable? Why not just "Function"?
(b) Why are there separate parameters for directory and name?
(c) What are signatures for completeCallback and failureCallback?

Feedback

[jonferraiolo]Seems weird that there is a call such as file.open("r");. Isn't it more natural and more "standard" to say filehandle = file.open(filename, mode);? See [1][/jonferraiolo]

[jonferraiolo]Why would you put the burden of managing file separators on the widget developer? Why not allow widgets to use "/" and then have the BONDI engine take care of Windows?[/jonferraiolo]

[jonferraiolo]Why does the find() function only work with a single file (i.e., no wildcard support)? Aren't there a lot of use cases to find all of the *.jpg files or whatever?[/jonferraiolo]

[jonferraiolo]Since the results of getMetadata() are implementation-dependent, doesn't seem to have much value.[/jonferraiolo]

[jonferraiolo]Regarding urlDownloadToFile(), wouldn't it be common to want to download a directory of files? How about downloading a ZIP which then explodes onto local disk? [/jonferraiolo]

AddressBook

Feedback

[jonferraiolo]Why are address books indexed by number? Why not use an associative array approach so that there can be an AddressBook['system'] or AddressBook['MSOutlook'] or whatever instead of AddressBook[0] and AddressBook[1]?[/jonferraiolo]

deviceStatusManager.watchPropertyChange

Feedback

[jonferraiolo]There is an example in the spec as follows: 

    var orientationChangeHandler = deviceStatusManager.watchPropertyChange(
     {aspect:"display",
      property:"orientation"},
     {
       onPropertyChange:function(ref, value) {
          alert("Property changed: "+ref.property+" "+ref.component+"
"+ref.aspect+" "+ref.vocabulary);
          alert("New value: "+value);
       }
     }
   );:
   deviceStatusManager.setPropertyValue({property:"orientation",
aspect:"Display"}, 0);

Why is onPropertyChange nested so deeply in the structure? Looks like the approach is mimicking Java event listeners and handler functions. No need for that in JavaScript.[/jonferraiolo]

Retrieved from "http://www.openajax.org/member/wiki/BONDI_Feedback_APIs"
Personal tools