The JavaScriptObject class has been an extremely useful concept because it provides zero-overhead interoperation with external (typically, non-GWT) JavaScript while adding additional value to external JavaScript objects by representing them as actual Java types that are amenable to refactoring, code completion, and Javadoc-style documentation. However, subclassing JavaScriptObject was not generally supported before GWT 1.5 because we weren't sure if it was the right solution, or if we might need to evolve it in breaking ways. This document describes the "old model" prior to GWT 1.5, and the new model, overlay types, which shipped in GWT 1.5 as well as extensions to overlay types that will first ship in GWT 2.0.

The old model used two very different approaches for hosted mode and web mode, but in both cases the point of interest was the boundary point between Java and JavaScript code, when a JavaScript object passes into "the Java world". This boundary point was most often the return value of a JSNI function, but could also occur when a JSNI function accessed Java code through a field assignment, or by passing parameters to a Java function called from JSNI.

In hosted mode, we created an instance of JavaScriptObject (or a JavaScriptObject subclass) as we marshalled the value from JavaScript to Java. This instance served as a Java wrapper for the underlying JavaScript object. It had strong type identity, and handled instanceof, casts, and polymorphic calls through the normal Java mechanisms.