DOM & Elemental2

The overlay model keeps the API small, and the gaps are the reason Elemental2 exists. dom.client has no addEventListener, no removeEventListener, no querySelector/querySelectorAll, no getElementsByClassName, no classList, no dataset, no fetch. The Javadoc of EventTarget states the first one openly: the class intentionally does not specify dispatchEvent, addEventListener and removeEventListener; events reach Java through sinkEvents and handlers instead (next section). Calling a method that is not there fails at compile time with the usual message for a member that is missing from an overlay:

Source: GWT 2.13.1 — EventTarget.java

A browser element only fires an event to GWT if the element is told to. sinkEvents(int bits) on a Widget (or DOM.sinkEvents(Element, int) for a bare element) registers interest in the event types whose bits are or-ed together; onBrowserEvent(Event) is then called on the widget when one of them reaches it. The bit constants live on Event; the values are the ones the 2.13.1 DOMImplStandard switches on:

The group constants FOCUSEVENTS, KEYEVENTS, MOUSEEVENTS, TOUCHEVENTS and GESTUREEVENTS combine the related bits. Event.UNDEFINED is deprecated. For events that have no bit (for example dragstart, input, transitionend) the widget layer uses sinkBitlessEvent(String), which the addDomHandler mechanism calls for you.

Sinking is lazy for widgets: until a Widget is attached, sinkEvents only records the bits (eventsToSink), and onAttach applies them. That detail matters for the lifecycle section below.

The following widget is built directly on a DOM element, counts clicks and still lets ordinary handlers be added to it:

Source: Javadoc — Widget

The caller adds an ordinary ClickHandler, a native preview handler and then dispatches a synthetic click built with Document.createClickEvent, which is also how GWT’s own tests drive widgets:

Source: GWT Developer Guide — Events and Handlers

The order is the design: the native preview handlers see the event first, then the widget’s onBrowserEvent, and Widget.onBrowserEvent finally calls DomEvent.fireNativeEvent, which runs the handlers registered with addDomHandler (and therefore every addClickHandler). Forgetting super.onBrowserEvent(event) in an override silently disables all of those handlers; this is the most common mistake in a hand-written widget. The Events & Handlers page covers the handler types, HandlerManager and event buses in detail. Suppressing the browser’s default action is done on the native event: NativeEvent.preventDefault() stops the default action (a link navigation, a form submit) and NativeEvent.stopPropagation() stops the event bubbling to ancestors; the handler types pass the NativeEvent through DomEvent.preventDefault() and DomEvent.stopPropagation().

Event.addNativePreviewHandler(Event.NativePreviewHandler) registers a global handler for every native event that GWT sinks, before it is delivered to its widget. It returns a HandlerRegistration. Inside, NativePreviewEvent.cancel() cancels the native event so that it is not delivered, consume() marks it as handled and prevents any handler from cancelling it (even one that already called cancel()), and isFirstHandler() tells whether the current handler is the first to preview this event. The Developer Guide’s keyboard-shortcut example uses exactly this API:

Source: GWT Developer Guide — Using the DOM

A preview handler lives until it is removed, whatever happens to the widget that created it. This is the main source of leaks in real GWT applications and is the subject of the lifecycle section further down.

The other two examples of the Developer Guide page (changing a widget’s background colour through getElement().getStyle(), and finding anchor tags with a JSNI helper) map to today’s API like this:

Compiling the probe module with -style PRETTY for one permutation shows how thin both layers are. The dom.client code from the first example became (the Java setInnerText is a textContent assignment, and the Style setters write the inline style object):

and the Elemental2 example became:

Member names of native types are never renamed, so the output is the JavaScript a person would write. A Java cast to a native class is not free of checks: it becomes castToNative(value, $wnd.HTMLDivElement), a check against the browser’s own constructor.

Source: Elemental2 — README

Each Elemental2 module is a separate Maven artifact (groupId com.google.elemental2) with its own GWT module. The artifacts include their .java sources next to the classes, which GWT requires.

The artifact elemental2-webassembly is also on Maven Central at 1.3.2 but is not in the README table. The dependencies of the four modules used here form a chain that Maven resolves for you: elemental2-dom depends on -core and -promise, -core on -promise, and -webstorage on -dom and -core. All of them declare jsinterop-annotations 2.0.2, jsinterop-base 1.1.1 and jspecify 1.0.0.

The Bookshelf client POM adds the four artifacts with an explicit version, because the org.gwtproject:gwt BOM manages GWT and jsinterop-annotations but not Elemental2:

and the module file inherits the four GWT modules:

Source: Elemental2 — README

With both in place, mvn -B package -pl bookshelf-client -am compiled the Bookshelf client (a call to DomGlobal.console.log was added to App) with six permutations and BUILD SUCCESS. Maven resolved jsinterop-annotations to 2.0.0 and jsinterop-base to 1.1.1: the GWT BOM pins the first below the 2.0.2 that the Elemental2 POMs declare, and jsinterop-base 1.2.0 (2026-06-30) exists but nothing forces it. Both combinations compiled and ran; if you need a newer jsinterop-base, declare it in dependencyManagement.

Forgetting the GWT module is the usual first error. The classes are on the classpath, so javac is happy, but the GWT compiler only reads source that a module puts on its source path:

Both families describe the same browser objects, so a value can be moved between them without a conversion: use Js.cast (from jsinterop-base) to treat a GWT overlay as an Elemental2 type, and Js.uncheckedCast to go back. This is the practical way to get classList and querySelector on an element that a GWT widget owns:

Source: jsinterop-base — Js and JsPropertyMap

The two libraries use the same simple names (Element, Event, Document, Window, Node, Storage), so a class that imports both must fully qualify one of them, as the bridge example does. Prefer to import the Elemental2 names in classes that use Elemental2 and keep GWT’s Event out of them; the compiler error for a clash is an ordinary Java "already defined" or "cannot be resolved" message.

Creating elements and listening to events with Elemental2 looks like the JavaScript it replaces, with Java types:

Source: MDN — EventTarget.addEventListener

Things to notice:

Source: MDN — EventTarget.removeEventListener: matching event listeners for removal

Keep the EventListener in a field (as onClick above) whenever you intend to remove it.

DomGlobal.fetch(...) returns an Elemental2 Promise<Response>. Promise has then, catch_ and finally_ (the underscore avoids the Java keywords), and the static resolve, reject, all and race. There is no await in Java, so asynchronous steps are chained. The Bookshelf REST endpoint of the server module is read like this; the first then converts an HTTP error into a rejection, the second parses the text with JSON.parse and walks the array through two small native types:

Source: MDN — fetch()

The native types need no runtime support: name = "Object" says "treat this as a plain JavaScript object", the public fields are property accesses, and Js.uncheckedCast only tells the compiler the type. The cast is not validated, so a response with a missing field yields undefined in Java; check untrusted data field by field before using it.

Two failure modes behave differently and both appear in the next listing. A response with an error status (the servlet answers a POST with 405) resolves the promise with res.ok == false; only a network failure (connection refused, DNS, blocked by CORS) rejects it:

Source: WHATWG Fetch Standard

Rules that keep fetch code safe and predictable:

Promise.all combines several promises. Its Java signature is static <V> Promise<V[]> all(IThenable<? extends V>... promises), and the array in the result is a JavaScript array. Instantiated with V = String, GWT inserts a cast to String[] in the lambda and the call fails at run time; with V = Object it works and each element is converted with Js.cast:

Source: MDN — Promise

Global.JSON (from elemental2-core) is the browser’s JSON object: parse(String) and stringify(Object). Compared with the GWT-specific options it is the shortest path from text to a typed native object:

Source: MDN — JSON

A JavaScript exception thrown from native code reaches Java as com.google.gwt.core.client.JavaScriptException; getMessage() carries the browser’s text, which differs between browsers. The RequestBuilder, JSON & XML page covers the GWT-side JSONValue classes and JsonUtils in depth.

URL and URLSearchParams build and parse addresses without string concatenation, which also gets the percent-encoding right:

Source: MDN — URL

url.href or url.toString() yields the absolute string for fetch, and fetch(URL) accepts the object directly. URL.canParse(String) tests an address without exceptions, and URL.createObjectURL(Blob)/revokeObjectURL exist for downloads (revoke the object URL when done, it is a manual resource).

WebSocket is a native class with callback fields (onopen, onmessage, onclose, onerror) typed as @JsFunction interfaces, so lambdas work:

Source: MDN — WebSocket

The Bookshelf server has no WebSocket endpoint; the probe connected to a small echo server on the same origin as the host page:

(The close callback reported code 1006 because that throwaway echo server closed the TCP connection without a complete closing handshake; a real server answers with 1000.) e.data is a union type, so asString() is checked with isString() first when binary frames are possible. Security rules for WebSockets are the same as for any endpoint: use wss:// on an HTTPS page (a secure page may not open an insecure WebSocket), authenticate and authorise on the server for every message, and verify the Origin header during the handshake so that another site cannot open an authenticated socket in the user’s browser.

elemental2-webstorage adds the Storage interface and WebStorageWindow, a Window with the localStorage and sessionStorage fields. GWT also has com.google.gwt.storage.client.Storage (getLocalStorageIfSupported()), which returns null where the feature is missing and is covered by the HTML5 Features page; the Elemental2 type assumes the browser has it.

Source: MDN — Web Storage API

getItem returns null for a missing key. Everything in web storage is readable by any script on the origin, so a single XSS flaw exposes it: never store session tokens, passwords or personal data there. Wrap reads and writes in try/catch; browsers throw when storage is disabled or the quota is exceeded.

The leak in question is a reference cycle between a JavaScript object and a native DOM element: widget to element to a closure that points back to widget. Old Internet Explorer’s garbage collectors could not free such cycles, and the common workaround (walking the DOM at window.onunload) missed detached elements and long-running applications. GWT’s rule was therefore: a widget must not be in a cycle with a native element while it is detached. Each widget has one root element; when the widget is attached, exactly one back reference from the element to the widget is created and, when it is detached, removed.

The code of 2.13.1 still follows this design. DOMImpl.setEventListener stores the listener in an expando property named __listener on the element, Widget.onAttach calls it with the widget, and Widget.onDetach calls it with null inside a finally block. sinkEvents assigns one shared dispatcher function to the element (elem.onclick = dispatchEvent, and likewise for the other events) instead of a closure per widget, which is why the article says you have to sink events with bits. The dispatcher walks up from the event target to the first ancestor that has a __listener, so an event on a child element is delivered to the nearest widget root. The probe checks the expando through jsinterop-base:

Source: GWT 2.13.1 — DOMImpl.java

The consequence the article states, and the code confirms, is a design limit: a widget cannot hang listeners on elements inside itself. It receives the event and works out which child it came from, with Element.as(event.getEventTarget()) and the DOM tree (getParentElement, isOrHasChild), exactly as ClickCounter.onBrowserEvent did above. Cell widgets rely on the same delegation: they receive the event at their root element and work out which cell it belongs to.

What the old guarantee does not cover is everything that is not the widget’s own root-element listener. Those registrations are held by long-lived objects (the window, the event preview stack, a static event bus, a running timer) which keep your widget reachable through the handler’s closure. A modern engine’s collector handles cycles, so this is no longer a cycle problem; it is a lifetime problem: the widget is removed from the page but can never be collected, and its handler keeps running.

Widget exposes the lifecycle through four methods and one event, called in a fixed order:

addAttachHandler(Handler) is the non-subclassing form: it receives an AttachEvent on both transitions. Subclasses that override onAttach or onDetach must call super; with assertions enabled GWT checks it when the parent attaches or detaches the child (the assertion message starts with "Failure of"), and a missing super.onDetach() leaves the expando in place, which is the leak the Javadoc of onDetach warns about. Calling the methods in the wrong state throws:

The Composite and Panel classes manage the lifecycle of their children, and Widget.removeFromParent() is the call that detaches a widget. The older safety net, RootPanel.detachOnWindowClose(Widget) (a list of widgets to detach when the page unloads), is @Deprecated in 2.13.1: its Javadoc says it was introduced to combat memory leaks in old browsers, that it is no longer necessary, that the unload event it relies on is being removed from browsers and that it is unreliable for guaranteeing onUnload() calls (issue 9908). So is Window.addCloseHandler, for the same reason; the 2.12.0 release notes record that unload-based calls were deprecated.

The probe module creates two widgets for each kind of global handler: a leaky one that registers in its constructor and never unregisters, and a tidy one that registers in onLoad and unregisters in onUnload. First the GWT native preview handler:

Then an Elemental2 listener on the window, with the same two shapes (the tidy one keeps its EventListener in a field so the same instance is removed):

The driver attaches both widgets, dispatches one event, detaches both, dispatches two more events and prints the counters, first for a click (picked up by the native preview handlers) and then for a window resize:

Source: Javadoc — Event.addNativePreviewHandler

After the widgets were removed from the page, the leaky handlers still ran for every later event (3 in total against 1), and each of them keeps its widget and the widget’s element tree alive. That is the whole story of a GWT memory leak in 2026, and the same pattern applies to every long-lived source:

Handlers added with widget.addClickHandler(...) or addDomHandler are different: they are stored in the widget’s own HandlerManager, so they live and die with the widget and need no cleanup. ResettableEventBus is the right tool when a presenter registers many handlers on a shared bus; the probe registers one handler, fires two events, calls removeHandlers() after the first, and the second event finds nothing:

Source: Javadoc — ResettableEventBus

The MVP, Activities & Places page applies the same idea: an Activity gets an EventBus that is reset when the activity stops, so handlers registered through it disappear with the screen.