Deferred Binding & Generators

For every GWT.create(T.class) it can reach, and for every permutation, the compiler asks a StandardRebindOracle for the answer. The oracle walks the module’s rules, replace-with, generate-with and fail, and takes the first rule whose conditions are all true. Rules are kept in a deque to which each new rule is added at the front, so the rule declared last is examined first. Inherited modules are loaded where their inherits element appears, so a rule in the inheriting module’s body, after the inherits, overrides the same rule of the module it inherits. A comment in GWT’s own Resources.gwt.xml makes the same point: the last matching rule wins, so a later rule selectively overrides an earlier one.

The figure shows the decision as the 2.13.1 StandardRebindOracle implements it. If no rule matches at all, the answer is the requested type itself, so GWT.create(DesktopPageSizer.class) on a concrete class with a public no-argument constructor works without any rule. Interfaces and abstract classes need a rule.

The answer is then validated, and the failures are reported against the line of the GWT.create() call. The rules and messages below were all reproduced:

The result of the decision is visible in compilation-mappings.txt in the module’s output folder, which lists the property values that each .cache.js permutation file was compiled for. For the Bookshelf demo module of this page:

Source: GWT — Deferred Binding: Defining Deferred Binding Rules, GWT source (2.13.1) — StandardRebindOracle.java

Nothing is decided in the browser except the selection of the permutation. The bootstrap script (<module>.nocache.js) runs the property providers, looks the resulting values up in its permutation table and loads the matching .cache.js. The GWT.create() calls inside that file were already replaced by new expressions of the chosen classes, which is why the single-line GWT.create in the Java source costs nothing at run time. See Linkers & Bootstrap for the script itself; the property part is in Property providers.

The Bookshelf catalogue shows ten books per page on a desktop and four on a phone. Application code does not test Window.getClientWidth(); it asks for a PageSizer, and the compiler wires in the right class per permutation. The user-defined property formfactor is described in Property providers.

Compiling it with the plain compiler (the command is the one from Compiler & Compilation, with the module name changed) reported four permutations, two user.agent values times two formfactor values. Opened in headless Chrome, the entry point wrote these lines into the page:

Swapping the two replace-with elements, so that the unconditional default comes last, shows the rule order: the default is now examined first, always applies, and the mobile page reports desktop pageSize=10 as well. No error or warning is printed.

Source: GWT — Deferred Binding: Example Class Hierarchy using Replacement

The module parser also accepts a fail element (it is not in the developer guide or the DTD). It takes the same conditions as replace-with and aborts the compile when it matches, which is how a module can forbid a combination:

With that rule in the demo module the compile stopped with Deferred binding request failed for type 'com.example.bookshelf.demo.client.PageSizer' followed by Failed to resolve 'com.example.bookshelf.demo.client.PageSizer' via deferred binding on the GWT.create line. Use it sparingly: it is only declared in ModuleDefSchema, not documented.

Source: GWT source (2.13.1) — ModuleDefSchema.java

Because when-property-is only works for a defined property, a rule that refers to a property of a module you do not inherit fails at module load, not at the GWT.create. Misspelling formfactor as formfactr in the demo stopped the compile with Line 25: Property 'formfactr' not found. The module that declares the property must be inherited (directly or through another module) before the rule that uses it.

set-property is the main tool for shorter development builds. It removes values from the permutation space. The guide calls the result a "working module": it produces only the variant you test. Every number below is the Compiling n permutations line of a real compile of the demo module.

Collapsing still works at run time: the collapsed demo still printed mobile pageSize=4 for ?formfactor=mobile and desktop pageSize=10 for ?formfactor=desktop, from 6 files instead of 12. A collapsed property becomes a "soft permutation", so the file contains the code of each answer and picks at run time. Collapsing trades download size for fewer files and a faster compile.

Source: GWT — Organizing Projects: Restricting the number of permutations, GWT source (2.13.1) — ModuleDefSchema.java

The fallback value exists for new values. extend-property with fallback-value says "if no rule matches this value exactly, use the rule of that other value". In a test module, formfactor was extended with tablet and fallback mobile, the desktop rule was made specific with when-property-is, and no rule mentioned tablet. The compiler logged, for the PageSizer rebind of the tablet permutations:

In the browser ?formfactor=tablet produced mobile pageSize=4. The compiler also saw that the tablet and mobile permutations produced identical code and shared one file (Compiling 4 permutations for 3 x 2 combinations). An exact rule always beats a fallback.

set-property-fallback is a different thing: it sets the value that a provider can use when it cannot decide. In a provider body the literal text /*-FALLBACK-*/ is replaced by that value when the selection script is generated. It is not applied automatically: with set-property-fallback declared but a provider that returned watch anyway, nothing was selected.

For a binding property whose value is not fixed at compile time the browser must compute it. That is the job of the provider: a JavaScript function body that returns one of the allowed values (a string), or a PropertyProviderGenerator class that returns such a body (generator="..."). user.agent uses a generator (UserAgentPropertyGenerator), locale uses one (LocalePropertyProviderGenerator), and GWT’s mobile sample defines formfactor with an inline body. A PropertyProviderGenerator implements generate(TreeLogger, SortedSet<String> possibleValues, String fallback, SortedSet<ConfigurationProperty>) and returns the JavaScript body as a string.

The Bookshelf provider reads the query parameter and falls back to the window width. The CDATA section is necessary because the body contains < and &:

With this provider ?formfactor=watch renders desktop pageSize=10, because the unknown value was replaced by the fallback; ?formfactor=mobile gives mobile pageSize=4.

A provider runs in the selection script, before any GWT code is loaded, so it cannot call Java or reference your classes. The script offers a few globals; each one below was used in a compiled test:

Together these let the server decide: a servlet or Thymeleaf/JSP template renders the meta tag from its own device detection, and the compiled application obeys it. With the meta tag formfactor=mobile the page reported mobile pageSize=4, with formfactor=watch plus the fallback token desktop pageSize=10.

If the provider returns a value that is not allowed, the selection script calls the handler named by a gwt:onPropertyErrorFn meta tag, if any, with the property name, the list of allowed values and the bad value, and then throws. The handler must be an expression, so wrap a function in parentheses:

In a test with a provider that returned the meta value unchecked, the document title became bad formfactor [desktop,mobile] watch and the application did not start. Without a handler and without the checking code of the previous provider the page stayed empty and, in the DOM dump, the loader had requested a file called undefined.cache.js; that silent failure is why a provider should validate its result.

Source: GWT — Organizing Projects: property-provider, GWT source (2.13.1) — sample FormFactor.gwt.xml, GWT source (2.13.1) — properties.js

The developer guide adds that set-property and property-provider on the same property overwrite each other and the last definition wins. Do not mix them for one property in the same module.

Configuration properties carry settings to compile-time code: generators, linkers and the CSS and i18n tooling. They are declared once and set anywhere downstream:

Source: GWT — Organizing Projects: Modules, units of configuration

Setting a configuration property without defining it works but logs the warning shown in the element table; always define it. A generator reads one with the property oracle, as in the BuildTagGenerator of Writing a generator, where locale.queryparam came back as locale. Typical built-in ones, from the 2.13.1 module files, are CssResource.enableGss and CssResource.conversionMode (set in the Bookshelf module), ClientBundle.enableRenaming, locale.queryparam, locale.cookie, locale.useragent, locale.usemeta, locale.searchorder, runtime.locales and user.agent.runtimeWarning.

user.agent is defined in UserAgent.gwt.xml and today it has two values: gecko1_8 and safari. The module defines the first, extends it with the second and attaches the generator-based provider. Browsers that are neither identify as one of them: the provider tests the lower-cased user-agent string for webkit (then safari, which includes Chrome and current Edge) and then for gecko (then gecko1_8), otherwise it returns the property’s fallback value, which for user.agent is empty and therefore not an allowed value. The values ie6, ie8, ie9, ie10, opera and plain gecko that the developer guide and the book mention are gone; Internet Explorer 11 identifies itself with gecko and so selects gecko1_8. A rule that names a removed value is rejected when the module loads: Value 'ie8' in not a valid value for property 'user.agent'.

Two related settings live in the same module. webApiUsage is a binding property with the values stable and modern (default modern) that lets widgets use not-yet-standardised web APIs. user.agent.runtimeWarning is a configuration property, true by default; the module comment says to set it to false to avoid runtime warnings about a mismatch between the compile-time and the runtime value. The check is done by the entry point UserAgentAsserter. When you build a single-permutation test with -setProperty user.agent=gecko1_8 and open the page in a WebKit browser, the asserter throws:

(reproduced in headless Chrome with the demo module). Use the other user.agent values only in per-browser test builds, and never ship a single-agent build.

Source: GWT source (2.13.1) — UserAgent.gwt.xml, GWT source (2.13.1) — UserAgentPropertyGenerator.java

locale is a binding property defined in I18N.gwt.xml with the single value default; the application extends it, as the Bookshelf module does:

The module also declares <set-property-fallback name="locale" value="default"/>, the fallback that its provider generator can substitute for a locale it does not know. Its provider is generated by LocalePropertyProviderGenerator, and five configuration properties steer where the browser looks for the value:

Every new locale multiplies the permutations (see the permutation counts table), and it also changes which implementation of every Localizable interface (Messages, Constants) the generator produces. Locale inheritance, plural forms, the Dictionary class for dynamic look-up and DateTimeFormat/NumberFormat belong to the Internationalization page. The point for this page is that locale and user.agent are ordinary binding properties, and everything said about conditions, fixing and collapsing applies to them. The exact search order is also the answer to a common surprise: with <meta name="gwt:property" content="locale=en"> in the host page and ?locale=es in the URL, the page showed Spanish because the query parameter comes first.

Source: GWT source (2.13.1) — I18N.gwt.xml, GWT — Internationalization: Locale

The scenario needs a way to print a book for audit logs without writing and maintaining a toString() for every shared entity. Describer<T> is the client-side contract; the generator creates the implementation for any interface that extends it, by reading the getters of T from the type oracle. The client side:

The generator lives in a rebind package that is not on the module’s source path:

Registered in the module XML next to the rules above:

The compile printed the generator’s own INFO lines inside the tree that the compiler builds for the rebind:

and -gen out/a/gen (a compiler flag that writes the generated sources) produced the class below. The type oracle returned the methods in alphabetical order, not in declaration order, so never depend on source order:

In the browser the entry point wrote Book{author=Frank Herbert, copies=3, id=7, title=Dune, year=1965}.

Source: GWT — Deferred Binding: Generator Implementation, GWT Javadoc — Generator

The generator is plain Java for the JVM that runs the compiler. It is compiled by javac like any server class and may use the whole JDK, but it must not be on the module source path. With <source path="demo"/> instead of demo/client, the rebind package became GWT source and the lenient compiler printed only Ignored 1 unit with compilation errors in first pass. In strict mode (-failOnError) it then printed a long list:

By convention the package is called rebind, and it sits beside client and shared in the project. In a Maven project the class must be compiled by javac and have gwt-dev on its compile classpath (the client module of the archetype already depends on gwt-dev).

A generator can read the permutation’s property values through the PropertyOracle. The output of such a generator differs per permutation, so the compiler runs it for every permutation. The test generator below writes one class per combination:

Source: GWT — Deferred Binding: Generator Implementation

Its log shows four invocations, one per permutation, whereas the property-independent DescriberGenerator above logged once (its later invocations found the class already created and returned early with nothing to print):

Four classes were generated (BuildTag_gecko1_8_desktop, BuildTag_gecko1_8_mobile, BuildTag_safari_desktop, BuildTag_safari_mobile), and in headless Chrome (WebKit, so safari) the page showed safari/mobile/locale and safari/desktop/locale for the two form factors.

@Generator.RunsLocal tells the compiler that a generator only uses local information, so it can run as early as possible in the incremental compile tree. The Javadoc states two restrictions: it may not use global type information such as JClassType.getSubTypes() or TypeOracle.getTypes(), and it may only read the properties listed in requiresProperties (RunsLocal.ALL allows any, at a speed cost). The restriction is enforced. Annotating the property-reading generator above with a plain @RunsLocal failed the compile:

The Bookshelf DescriberGenerator reads no properties, so it can carry the annotation. Written as an IncrementalGenerator it looks like this and produced the same behaviour in the demo:

Be realistic about the benefit. isGeneratorResultCachingEnabled() is false unless a caller switches it on, and in the 2.13.1 sources the only code that does is ShellModuleSpaceHost, the classic Dev Mode host. So the caching half of IncrementalGenerator is of little use for a new generator, while getVersionId() is what invalidates a stale cached result when you change the generator. A plain Generator that cooperates with tryCreate is enough for application code. The generator instance is kept and reused by the compiler, so it must be thread-safe and must not keep per-rebind state in fields.

Source: GWT source (2.13.1) — IncrementalGenerator.java, GWT source (2.13.1) — Generator.java, GWT source (2.13.1) — StandardGeneratorContext.java

The GWT library is full of generators, but writing a new one is a last resort today, for these reasons.

Prefer, in this order: a hand-written factory, a replace-with rule over a property when only a choice of implementation is needed, an annotation processor when code must be derived from types, and a generator only when the code depends on a GWT property or on another GWT.create result (as Messages does with locale). The type model is also different from what the 2007 book describes: its generators read Javadoc metadata tags such as @gwt.typeArgs, which no longer exist; use annotations (JClassType.getAnnotation) and generics (JParameterizedType.getTypeArgs()).