| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| <title>Restrictions on subclasses of JavaScriptObject</title> |
| </head> |
| <body> |
| <p>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.</p> |
| <p>In the following, "JSO class" means any subclass of <code>JavaScriptObject</code>. |
| Rationales are written <em>like this</em>.</p> |
| <ol> |
| <li>All instance methods on JSO classes must be one of: |
| explicitly final, a member of a final class, or private. <em>Methods |
| of JSO classes cannot be overridden, because calls to such methods |
| could require dynamic dispatch.</em></li> |
| <li>JSO classes may implement interfaces that define methods, but |
| only if those interfaces are annotated with <code>@SingleJsoImpl</code>. |
| <em>This ensures that polymorphic dispatch via a <code>@SingleJsoImpl</code> |
| interface can be statically resolved to exactly one implementing JSO |
| subtype.</em> |
| <ol> |
| <li>A <code>@SingleJsoImpl</code> interface may only extend |
| "tag" interfaces that declare no methods or other interfaces |
| annotated with <code>@SingleJsoImpl</code>.</li> |
| <li>It is valid for a <code>@SingleJsoImpl</code> interface to |
| be extended by an interface that is not annotated in this fashion, |
| however the sub-interface may not be implemented by any <code>JavaScriptObjects</code>.</li> |
| <li>A <code>JavaScriptObject</code> that implements a <code>@SingleJsoImpl</code> |
| interface may be further extended. The subclasses may implement |
| additional <code>@SingleJsoImpl</code> interfaces. <em>The |
| methods on a JSO must be effectively final, so each <code>@SingleJsoImpl</code> |
| method still has a 1:1 mapping to a method defined within a JSO |
| subtype.</em></li> |
| <li>It is valid for any number of any non-<code>JavaScriptObject</code> |
| types to implement a <code>@SingleJsoImpl</code> interface. <em>There |
| is a runtime dispatch penalty when a <code>@SingleJsoImpl</code> |
| interface is implemented by both JSO and non-JSO types.</em></li> |
| </ol> |
| </li> |
| <li>No instance methods on JSO classes may override another |
| method. <em>This catches accidents where JSO itself did not |
| finalize some method from its superclass.</em></li> |
| <li>JSO classes cannot have instance fields. <em>The fields |
| would have no place to live in web mode. Programmers should instead |
| make an explicit wrapper class and put the fields there.</em></li> |
| <li>Nested JSO classes must be static. <em>The implicit <code>this</code> |
| fields of a non-static inner class has the same problems as an |
| explicit field.</em></li> |
| <li>"new" operations cannot be used with JSO classes. <em>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.</em></li> |
| <li>JSNI methods may not refer to instance methods defined within |
| a <code>JavaScriptObject</code>.</li> |
| <li>Every JSO class must have precisely one constructor, and it |
| must be protected, empty, and no-argument.</li> |
| </ol> |
| </body> |
| </html> |
