E10S and general API issues

[Myk Melez]

Rocketeers!

Atul, Drew, and I met yesterday to review APIs for any lingering e10s compatibility issues and any other API issues that we might want to fix before we ship the first beta (which will constrain API changes pretty significantly, since we don't want to break APIs for beta users without a really good reason).

We identified some e10s issues and some API consistency/simplicity/usability/etc. issues, including a bunch that don't actually block the release (since they are additive). The lists below are the issues we identified (along with a couple more I noticed while converting my notes into bug reports).

Check the 0.10 blockers bug for the subset of these issues that actually blocks the first beta release because they are (or appear to be, in the case of docs fixes) breaking changes.

E10S Issues:

• bug 612664: Panel.show() takes a DOMElement argument, but such objects can't be passed across the process boundary. "Handles" can, though, and seem appropriate in this case, since they allow us to anchor panels to both chrome and content elements, so the docs should be updated to specify that the argument be a handle.
  
  
• bug 612673: Certain APIs share state with the chrome process or OS, and we cannot guarantee that the shared state won't change between successive API calls (without complex locking schemes that seem like the wrong solution given our audience of casual developers), so we should document the issues that can arise.
  
  
• bug 612676: An alternate implementation of the Selection API would mitigate the problem caused by the selection being shared state between processes. We should consider altering the API accordingly.
  
  
• bug 612678: The Tab.location property is a Location object, which can't cross the process boundary, so it should be a String instead.
  
  
• bug 612681: The Tab.thumbnail property is a Canvas, which can't cross the process boundary, so it should be a data: URI String instead.
  

General API Issues:

• bug 612685: The onReady option to the openWindow() method of the Windows API is not useful, given that the API doesn't give consumers access to the DOM content of windows, so it should be removed.
  
  
• bug 612716: The contentScriptURL option should be renamed to contentScriptFile to clarify that it only accepts references to local files.
  
  
• bug 612719: The Page Worker API's "ready" event should be removed in favor of content scripts now that the API no longer provides direct access to each page's DOM.
  
  
• bug 612726: It should be possible for an addon's main code to communicate directly via a WebWorker-like API with a page into which the addon's own local content is loaded.
  
  
• bug 612728: The contentScript and contentScriptFile properties should be Lists.
  
  
• bug 612733: The Private Browsing API's "active" property should be renamed to "isActive", and it should have activate() and deactivate() functions rather than a setter.
  
  
• bug 612735: The Selection API's "contiguous" property should be renamed to "isContiguous".
  
  
• bug 612747: Tab.close() should accept a callback to be called when the closing process finishes.
  
  
• bug 612751: The Window.close() and Tab.close() callbacks should be informed of success or failure.
  
  
• bug 612757: The Windows API should reference the "close" event type by its correct name.
  
  
• bug 612758: The Windows API's browserWindows.openWindow() method should be simply browserWindows.open() for consistency with the Tabs API's open() function.
  
  
• bug 612761: The erroneous reference to a Window.focus() method should be removed.
  

-myk

[Julián Ceballos]

What do you think about use getter/setter methods?, good idea or bad idea?

El 16/11/10 18:55, Myk Melez escribió:

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.
To post to this group, send email to mozilla-la...@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jet...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

-- 
Julián Ceballos
Mozilla México Software

[Myk Melez]

On 11/16/2010 05:56 PM, Julián Ceballos wrote:

What do you think about use getter/setter methods?, good idea or bad idea?

I think it depends on the context. We use getters and setters in some cases already, and there are both advantages and disadvantages to doing so.

Lately the disadvantages have been weighing on my mind more, in particular that it isn't always clear from a cursory examination of API documentation that one may trigger a certain behavior (like activating a tab) by setting a property to a new value.

Nevertheless, they do have their place and should remain part of our overall API design "toolbox," with their use to be determined on a case-by-case basis in alignment with our overall design principles and conventions.

-myk

[Irakli Gozalishvili]

Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/
Address: 29 Rue Saint-Georges, 75009 Paris, France

What about renaming browserWindows.activeWindow to browserWindows.active and the same for tabs it's shorter and completely clear. 

 

• bug 612761: The erroneous reference to a Window.focus() method should be removed.
  

Actually Window's do have focus method and activeWindow setter just calls it.
There are also technical reasons to keep focus method. Access to the wrapped
window is encapsulated in the `BrowserWindow` instances so that no one else can
have access the window object itself and there for focus it. That being said of
course it's not impossible but will end up in more complex code without much of
an advantage.

As an alternative I can suggest converting `activeWindow` property to a read
only and keep focus method. 
This is also less verbose:

browserWindows[3].focus();

then 

borwserWindows.activeWindow = browserWindows[3];


I guess web devs also might find themself more familiar cause dom API's do 

usually have focus() methods.

[Myk Melez]

On 11/18/2010 03:48 AM, Irakli Gozalishvili wrote:
> What about renaming browserWindows.activeWindow
> to browserWindows.active and the same for tabs it's shorter and
> completely clear.

I had originally planned to call these simply "active", actually, but I
eventually came to the conclusion that while that name is indeed shorter
and simpler, it is not actually clearer, and it requires a process of
mental dereferencing (from the name of the property back to its object)
that is more expensive (in terms of mental effort and ease) than the
cost of the additional characters, and thus, despite the redundancy and
additional length, it's better to be more explicit.

> There are also technical reasons to keep focus method. Access to the
> wrapped
> window is encapsulated in the `BrowserWindow` instances so that no one
> else can
> have access the window object itself and there for focus it. That
> being said of
> course it's not impossible but will end up in more complex code
> without much of
> an advantage.

The advantage is a reduction in the surface area of the API to that set
of properties and methods that we actually intended to explicitly
expose, which has collateral benefits for security and API stability.

> As an alternative I can suggest converting `activeWindow` property to
> a read
> only and keep focus method.
> This is also less verbose:
>
> browserWindows[3].focus();
>
> then
>
> borwserWindows.activeWindow = browserWindows[3];

Yes, I agree that this approach is preferable, and this is the third
time this suggestion has come up in conversation this week, which I'm
sure is telling me something, if only I could figure out what. ;-)

But I would call it "activate" rather than "focus", which has a
specific, different meaning on the web and in Firefox's web-like chrome
interface (the latter of which unfortunately reuses "focused" along with
"current", and "active", "selected", and "frontmost" haphazardly and
inconsistently to expose and describe the concept of window and tab
activation).

-myk