Restrictions on subclasses of JavaScriptObject

Subclasses of JavaScriptObject represent a view of a JavaScript object from Java. Such classes must conform to a number of restrictions so that the compiler can implement them. This page lists those restrictions.

In the following, "JSO class" means any subclass of `JavaScriptObject`. Rationales are written like this.

1. All instance methods on JSO classes must be one of: explicitly final, a member of a final class, or private. Methods of JSO classes cannot be overridden, because calls to such methods could require dynamic dispatch.
2. An interface type may be implemented by at most one JSO subtype. This ensures that polymorphic dispatch via a "SingleJsoImpl" interface can be statically resolved to exactly one implementing JSO subtype.
   1. A `JavaScriptObject` that implements a "SingleJsoImpl" interface may be further extended. The subclasses may implement additional "SingleJsoImpl" interfaces. The methods on a JSO must be effectively final, so each "SingleJsoImpl" method still has a 1:1 mapping to a method defined within a JSO subtype.
   2. It is valid for any number of any non-`JavaScriptObject` types to implement a "SingleJsoImpl" interface. There is a slight runtime dispatch penalty when a "SingleJsoImpl" interface is implemented by both JSO and non-JSO types.
3. No instance methods on JSO classes may override another method. This catches accidents where JSO itself did not finalize some method from its superclass.
4. JSO classes cannot have instance fields. The fields would have no place to live in web mode. Programmers should instead make an explicit wrapper class and put the fields there.
5. Nested JSO classes must be static. The implicit `this` fields of a non-static inner class has the same problems as an explicit field.
6. "new" operations cannot be used with JSO classes. This avoids ever being able to try to instantiate JSO objects using the new keyword. New JSO instances can only come from JSNI, as in previous versions of GWT.
7. JSNI methods may not refer to instance methods defined within a `JavaScriptObject`.
8. Every JSO class must have precisely one constructor, and it must be protected, empty, and no-argument.