Project Structure & Modules

The guide’s own example of rename-to shows the first use, a short module name:

Source: GWT — Organizing Projects: Renaming modules

The short name matters beyond tidiness. GWT.getModuleBaseURL() is the URL of the output directory, and @RemoteServiceRelativePath("catalog") is resolved against it, so the Bookshelf’s catalog service lives at /bookshelf/catalog precisely because the module is renamed to bookshelf. Static files from the public path are reached with GWT.getModuleBaseForStaticFiles() followed by the file name.

The second use is a working module: a module that inherits the real one and pins properties, to cut the number of permutations during development. The guide’s example pins user.agent to ie6, a value that no longer exists. In GWT 2.13.1 UserAgent.gwt.xml defines gecko1_8 and extends it with safari only. The same trick with current values, written for the Bookshelf’s small slots module, compiled to exactly one permutation:

Source: GWT — Organizing Projects: Renaming modules

On the full bookshelf-client module, which has three locale values (default, en, es) and two user agents, the compiler printed Compiling 6 permutations; the slots module above printed Compiling 1 permutation. A working module is a development tool: ship the real module.

Source: GWT — Organizing Projects: Renaming modules

<inherits> is the only way to make library code visible. The Developer Guide asks you to inherit "at least the User module", and its table of standard modules is from GWT 1.5, which is why it lists only five modules and three themes. The modules that exist in the 2.13.1 gwt-user and that a Bookshelf-style project meets most often are:

Source: GWT — Organizing Projects: How do I know which GWT modules I need to inherit?, GWT 2.13.1 — User.gwt.xml

Inheritance is transitive and idempotent: User brings Editor (through UI) and Activity brings Place, which is why removing the Bookshelf’s explicit Editor line, or its Place line, still compiled in the scratch runs. Declaring modules explicitly is still the better habit, because a project then keeps compiling if a library stops pulling a module in.

The source path is the compiler’s view of "what may become JavaScript". The three source-like elements share the same filtering attributes, which follow Ant’s FileSet rules: includes, excludes, defaultexcludes (on by default), casesensitive, and nested <include>, <exclude> and (in the parser) <skip> elements:

Source: GWT — Organizing Projects: Filtering Public and Source Packages

Three rules to remember. First, path is relative to the package that holds the module file, and <source path=""> means the module’s own package. Second, declaring any <source> or <super-source> removes the implied client, so a module that declares only <source path="shared"/> no longer sees client. Third, a <super-source> replaces classes by name: the Bookshelf needs a checksum for cache keys, and the server implementation uses java.util.zip.CRC32, which GWT does not emulate. The shared source keeps the JVM version and a super-source supplies the browser one:

Source: GWT — Organizing Projects: Overriding one package implementation with another

Both files compile in the scratch Bookshelf and the browser build contains no reference to CRC32. Two caveats come from the guide: a super-source class is never used in development mode with the JVM classes (the JRE class always wins there), and a super-source is the mechanism GWT itself uses for its JRE emulation. The two versions above return different values for the same text, so such a result must never be compared across the client/server boundary; in a real project make the behaviour of both versions identical, or compute the value on one side only.

An entry point is a class that implements com.google.gwt.core.client.EntryPoint and can be constructed without arguments; onModuleLoad() is called once the module and the outer document are ready. All entry points of a module, including those of inherited modules, are compiled into the same script and called in sequence. A module that is only a library (the Bookshelf’s Shared) declares none. A module that is loaded from a host page should have at least one, but the compiler does not check it: in the scratch runs, a module with no <entry-point> compiled successfully and simply did nothing in the browser, while a misspelled class name failed the compile:

Source: GWT — Organizing Projects: Entry-Point Classes

<stylesheet> and <script> are meant to let a reusable module bring its own CSS and JavaScript, so that "clients of your library have everything they need automatically by inheriting from your module". The stylesheet half works as documented. The Bookshelf’s public path holds bookshelf.css, the module links it, and the compiled bookshelf.nocache.js loads it next to the Clean theme’s gwt/clean/clean.css:

Source: GWT — Organizing Projects: Including External Stylesheets

The script half does not work with the default linker. The guide’s page still says scripts "will be loaded when your application starts", but the xsiframe linker, which is the default, refuses them. This is the exact error from the scratch build with <script src="stats-stub.js" /> in the module:

Source: GWT 2.13.1 — CrossSiteIframeLinker.java

With xsiframe.failIfScriptTag set to FALSE the build passes, the log says Ignoring the following script tags in the gwt.xml file, and the script is still copied to the output directory but never loaded. The reliable approach is to put a <script> element in the host page, before the selection script, and keep third-party scripts out of the module.

Source: GWT — Organizing Projects: Automatic Resource Inclusion, GWT 2.13.1 — CrossSiteIframeLinker.java

<servlet path="/catalog" class="..."/> mounted a servlet inside the embedded development server. The guide itself notes that since GWT 1.6 the element no longer loads servlets in development mode and a WEB-INF/web.xml must do it; since GWT 2.13 the development server serves only static files at all. Declare servlets in web.xml (or with annotations) of the server module. The Bookshelf maps its RPC servlet to the module-relative path that @RemoteServiceRelativePath("catalog") produces:

Source: GWT — Organizing Projects: XML Element Reference (servlet), GWT — Release notes 2.13.0

<set-property>, <extend-property> and <set-configuration-property> all work on named properties, but they are different kinds. Deferred-binding properties (locale, user.agent) have a set of values and each combination is a permutation, so <extend-property> and <set-property> change what is compiled. Configuration properties (CssResource.enableGss, xsiframe.failIfScriptTag) are plain compile-time settings with no permutations. A <set-configuration-property> for a name that was never defined is tolerated for backwards compatibility but logs a warning, and one for a name that is a binding property is an error. The property names GWT itself defines are documented on the pages that own them.

Source: GWT — Organizing Projects: XML Element Reference

The linker decides what files the compiler writes and what the bootstrap script does. <add-linker name="..."/> picks one by name. There are three categories: pre-linkers run before the primary linker, there is exactly one primary linker (the last one added wins), and post-linkers run after it. xsiframe is the default; sso produces a single JavaScript file; std and xs are deprecated in favour of xsiframe (the bootstrap and the linkers are the subject of Linkers & Bootstrap). Adding sso to the one-permutation slots module replaced the whole output with two files, a single script of about 39 KB and the clear.cache.gif image, and no .cache.js file or .devmode.js file:

Source: GWT — Linkers: usage

A single-script build needs a single permutation, which is why the example pins the properties. Custom linkers are registered with <define-linker name="short" class="..."/> and then added the same way.

Source: GWT — Linkers: usage, GWT — Linkers: available linkers, GWT — Linkers: custom linkers

A permutation exists for every combination of values of the deferred-binding properties. The collapse elements tell the compiler that some values do not need separate code. They are absent from the Developer Guide; the parser (ModuleDefSchema) accepts <collapse-property name="..." values="..."/> and <collapse-all-properties/>, and GWT’s own mobile sample uses the first to collapse its custom formfactor property. The trade-off was measured on the Bookshelf client:

Source: GWT 2.13.1 — ModuleDefSchema.java (collapse elements)

Collapsing trades a larger download for fewer compiles; the collapsed script has to contain the code for every value and choose at run time. Use it for properties that change little (a custom property you defined) and measure before using it on locale.

Source: GWT 2.13.1 — ModuleDefSchema.java (collapse-property), GWT 2.13.1 — FormFactor.gwt.xml

For the bookshelf module the compiler wrote this directory, one script per permutation plus the bootstrap script. The slots module, with one permutation, wrote the minimal version:

Source: GWT — FAQ Debugging and Compiling: The .nocache.js File, gwt-maven-plugin — Artifact Handlers (gwt-app layout)

The FAQ still describes .cache.html files loaded into a hidden iframe; with the default linker of 2.13.1 the permutation files are .cache.js. The principle in the FAQ is current: the nocache.js file is regenerated under the same name on every compile, so it must not be cached by browsers or proxies, while the content-hashed files can be cached for a long time.

The selection script is where deferred binding is resolved in the browser. It reads the gwt:property meta tags, runs the property providers (for example the locale and user.agent ones), looks up the permutation that matches the values, and fetches that one script:

Two points follow from the guide’s bootstrap analysis. Put the selection script tag early in the page, because the compiled script is fetched asynchronously and it blocks no other script. And external <script> tags are guaranteed to have finished loading when onModuleLoad runs, while <img> tags are not.

Source: GWT — Organizing Projects: The Bootstrap Sequence

A <meta name="gwt:property" content="name=value"> tag in the host page sets the value of a deferred-binding property for that page load, which is the standard way to pick a locale for a page. Because the selection script does the reading, the tag must appear in the page, not in the module XML. The runtime source of the script gives the full set of meta names it understands: gwt:property, gwt:onPropertyErrorFn and gwt:onLoadErrorFn, and each can be limited to one module by prefixing the name with the module name and two colons (bookshelf::gwt:property), which matters when two modules share a page. In the Bookshelf, the tag locale=en sets English for the page, while the URL parameter ?locale=es takes priority over the meta tag, as the locale.queryparam configuration property (default locale) says:

Source: GWT — Organizing Projects: HTML Host Pages (properties)

Internationalization covers the locale property in depth. The value in a gwt:property tag must be one of the values the module allows; a function named in a gwt:onPropertyErrorFn tag is the hook for reporting a bad value.

Source: GWT — Organizing Projects: HTML Host Pages (properties), GWT — Internationalization: Locale, GWT 2.13.1 — processMetas.js