Author: Reuben Kan (reuben@google.com), David Hearnden (hearnden@google.com), David Wang (zdwang@google.com)

Date: 19-Oct-2010

Objective

Background

Overview

Stage 1. Server-supplied rendering

Stage 2. Live model (read only)

Stage 3. Write

Stage 4. Feature completeness

Design principles

• Low latency is more important than high throughput. It is better to respond faster with some initial feedback, at the cost of taking longer to complete an entire action, than it is to complete the entire action as fast as possible. A significant part of providing low latency responses is favouring lazy evaluation over eager evaluation. For example, each blip's content model is not processed until that blip is rendered, rather than initializing all the blip content when the model is initially loaded in memory (stage two). Although this increases the total time for rendering the entire contents of a wave, the decrease in response time for the initial display of that wave is preferrable.
• Graceful degradation across browsers. The architecture should be able to support different browsers with varying ability to execute Javascript. The architecture should offer a gradual degradation of features depending on the amount of bandwidth/CPU available.
• Modularization of functionality. Each feature should be able to be enabled/disabled separately on separate passes. This allows us to separately assess the cost of each feature and push slow features to a later stage of processing.

Additional considerations for performance:

• For JavaScript-enabled clients, server-side rendering requires more data to be downloaded, but reduces client-side processing, and is not gated by the download of the wave model state. This is a trade-off between the client's execution speed, download speed, the size of the HTML rendering, and the size of the model data required for client-side rendering. The balance is usually in favour of server-side rendering, but it is not unreasonable (for a very fast browser on a particularly slow network) for client-side rendering to be faster.
• Server-side rendering requires server CPU resources. The client/server rendering protocol is such that the server is not expected to render all the blips. This allows the rendering server to increase and decrease the amount of wave content it renders in response to load and client capabiltiies, trading the rendering work between the client and server.

Detailed design

Initial HTML / bootstrap page

• Stage 1: Browser cache hit before expiry timeout - no network cost
• Stage 2: Browser cache miss because expiry time out, but document is still valid - network round trip to server to discover document is still valid
• Stage 3: Browser cache miss, document modified - full download cost

... 2

function loadScript() { 4
n = document.createElement("script");
n.type = "text/javascript";
n.language="javascript";
n.defer="defer";
n.src = "/a/google.com/static/927E04E13C1E546FDE3DAEEF0C0D0F32.cache.js"; 5
n.onload=start;
document.getElementsByTagName("head")[0].appendChild(n);
}
setTimeout("loadScript()", 0);

... 6

1. IE8 only, standard mode is easier to write for now
2. Style needed for the server-supplied rendering.
3. The JavaScript attribute "defer" is specified so the following code is not executed until the page is loaded. Note, this is only supported in IE.
4. The application is loaded with programmatic script injection to avoid the cost of evaluating the javascript up front.
5. Refering to compiled GWT Javascript
6. Prerendered content from the server. If this content is empty, due to server failure, the content is created dynamically by the javascript loaded at Point 5. See more info about the format of this content in the "HTML Format" section.

Alternative

HTML format

<div>
<div style="display:none">
<div id="render_metadata"> 1
{"idmap" : { 2
"example.com!w+Khns7Nd,example.com!conv+root,t+NDiNWrZkA" : "a",
"example.com!w+Khns7Nd,example.com!conv+root,b+NDiNWrZkB" : "b",
...,
},
"versions" : [ 3
{"wavelet" : "example.com!conv+root", "version" : "83"},
{"wavelet" : "example.com!conv+kl20xE", "version" : "125"},
...
],
...
}
</div>
</div>
...
<div kind="thread" id="a"> 4
...
<div kind="blip" id="b"> 5
...
<span id="b-Time">Jun 4</span> 6
...

1. A preamble containing metadata about the rendering, required for various client-side operations. The components of this metadata are explained below. The rendering metadata is delivered as hidden text in the page content, rather than a script tag, to avoid the delay from the browser evaluating it as Javascript upfront. When the rendering metadata is needed by the client, it is extracted as JSON from the inner text of the metadata DOM element, and evaluated.
2. The rendering metadata contains a string map, mapping between strings that uniquely identify model objects (like blips and threads) and short, obfuscated strings used in HTML ids. Obfuscated HTML ids are used for a number of reasons:
1. HTML ids in IE7 are not case sensitive. Ids for wave model objects are case sensitive. The obfuscation mapping ensures that HTML ids are unique ignoring case.
2. Minor point, the strings that uniquely identify model objects are long. e.g., in order to be unique across multiple waves on the page, the unique id for a blip must contain a wave id, a wavelet id, and a blip id. Mapping these long identifiers to short ones reduces the size of the HTML, because a model id is used as a prefix for view components (see point 6). Note, this may not be a significant size reduction when the HTML is gzipped.
Once the id map loaded, the client can map directly between model objects and the DOM elements of their renderings.

3. The rendering metadata contains the wavelet versions at which the rendering took place, so the client can fetch the model data at that correct state.
4. HTML rendering for thread "t+NDiNWrZkA" in conversation "example.com!conv+root" of wave "example.gom!w+Khns7Nd". This rendering is identified with "a", which is the obfuscated value of the thread's unique model id (which composes its wave id, conversation id, and thread id).
5. HTML rendering for blip "b+NDiNWrZkB" in conversation "example.com!conv+root" of wave "example.gom!w+Khns7Nd". This rendering is identified with "b", which is the obfuscated value of the blip's unique model id (which composes its wave id, conversation id, and blip id).
6. The timestamp component of a blip's HTML rendering. The id of this span is computable from the HTML id of blip that contains this span. In this example, the timestamp element of a blip's HTML is identified by appending "-Time" to the blip's HTML id.

Event handling system - O(1) upfront setup

<div onclick="handle()"> 2
<div>
...
<div kind="blip"> 3
...
<div>
<div> 1

A browser event (e.g., a click) occurs on some element. There are no DOM event handlers on that element, so the event bubbles.

The event reaches the root element, and its handler is invoked (that handler is Undercurrent's event system).

Undercurrent's event system traverses up the DOM from the target element of the event (1) until it sees an element that has a kind. If there is an application-level handler registered for that event type (e.g., clicks) and that kind value ("blip"), then it is invoked with the appropriate context (the element that has the kind). The event system continues to traverse up the DOM looking for elements with kinds, dispatching the event to every application-level handler registered for that event type on that kind, until one of the handlers indicates that propagation should stop.

• Traditional widgets: O(n) setup cost to construct the widgets and attach event listeners. O(n) memory cost from the widget objects, but O(1) cost to dispatch to application-level event handling.
• Undercurrent's approach: O(1) setup cost for the root widget, O(1) memory cost, and O(n) worst case for dispatch (but usually O(1) in typical cases).

Alternatives

<div kind="thread" onclick="window.__handle('click', 'thread', this);">
<div>
<div kind="blip" onclick="window.__handle('click', 'blip', this);">
<div>
<div>

Model/view/presenter and flyweight patterns - O(1) start-up

public final class BlipMetaDomImpl implements ... {
/** The DOM element of this view. */
private final Element self; 1

/** The HTML id of {@code self}. */
private final String id;

//
// UI fields.
//

private Element time;
...

private Element getTime() {
if (time == null) {
// Construct
time = load(id, Components.TIME); 2
}
return time;
}
...

@Override
public void setTime(String time) {
getTime().setInnerText(time);
}
}

1. View objects are bound to DOM elements. The current implementation uses disposable view objects for simplicity; for a pooling variation, these references would obviously be non-final.
2. Parts of a view ("UI fields" in UI Binder terminology) are identified via enums, and loaded lazily using the DOM API's getElementById(). The ids of components are computable from the view's id and the component name.

public final class LiveConversationViewRenderer implements ObservableConversation.Listener, ... { 1
...

@Override
public void onBlipTimestampChanged(ObservableConversationBlip blip, long oldTimestamp, long newTimestamp) {
BlipView blipUi = viewProvider.getBlipView(blip); 2
blipUi.setTime(formatDate(blip.getLastModifiedTime())); 3
}
}

1. Each presenter is an observer of a live model.
2. On a model change event, the live renderer is notified. It materializes views that need updating through a view provider. The provision of a view involves mapping the relevant model object to a unique view id (using the mapping process described earlier), querying the DOM for the element identified by that id, then binding a new (or re-used) view object of the appropriate kind to that DOM element.
3. Model state is then pushed into the view using the view API for that kind (e.g., a BlipView exposes its timestamp, hiding the underlying HTML structure of the view).

Updated concurrency control (CC) stack

Code and Package Structure

• uibuilder - Defines what UiBuilders are (HTML closures), and some helper classes for implementing them
• render - The interfaces that needs to be implemented to render a wave.
• concurrencycontrol - Multi-stage wave stack (non-live, then live).
• wavepanel -
• event - implementation of the single-widget event dispatch system (should probably be in client.event rather than client.wavepanel.event)
• impl - the skeleton structure of a wave panel feature. Fine-grained features exist in sub-packages, and are installed independently.
• ...
• render - wave rendering implementation, for plugging into the wave rendering mechanism in the ...client.render package
• view - view interfaces for UI components within a wave (as per MVP separation), including both intrinsic definitions and full definitions (intrinsic + structure).
• dom - DOM-based implementations of intrinsic parts of views
• impl - flyweight wrappers for upgrading intrinsic implementations to a full view implementation (addition of structure handling)
• fake - pojo implementations of the views, primarily for testing.

Using Undercurrent

1. Following the instructions here to start the server. http://www.waveprotocol.org/code
2. Open http://localhost:9898?enableWavePanelHarness=true&enableUndercurrentEditing=true