JRE Emulation & Shared Code

Browsers do not have a JVM, so the GWT compiler cannot translate calls into rt.jar/the platform modules. Instead it needs the source of every class that client code touches. For your own classes that source is on the module’s source path; for java.lang.String, java.util.ArrayList and the rest of the JRE it is the JRE emulation library: hand-written, translatable Java source files, shipped inside gwt-user-2.13.1.jar under com/google/gwt/emul/ and registered by the module com.google.gwt.emul.Emulation. A comment in that file tells you not to inherit it directly but to inherit com.google.gwt.core.Core, which every normal GWT module does through com.google.gwt.user.User. The module consists of a <super-source/> element: the files below com/google/gwt/emul are re-rooted so that com/google/gwt/emul/java/util/ArrayList.java is seen by the compiler as java/util/ArrayList.java.

Source: GWT 2.13.1 — Emulation.gwt.xml

Consequences worth keeping in mind:

Source: GWT — Compatibility: Classes that provide similar functionality

The reference page RefJreEmulation.html lists the supported packages, and for each type the supported constructors, methods and fields. It is generated from the emulation sources, so it follows the release (2.13.0 reworked it to also document what is not supported, below). The packages it covers, and what the 2.13.1 sources contain, are:

Source: GWT — JRE Emulation

The headline point is that the library is a deliberately small, browser-oriented subset: several packages are present only with a handful of types. Absent entirely, and therefore compile errors, are among others java.time, java.util.regex, java.util.UUID, java.io.File, java.lang.Thread, java.util.Scanner and java.net. The sample code below compiles a class that uses several of them and shows the messages the compiler produces.

Source: GWT — Compatibility: Runtime library support

Compiling it with java -cp ... com.google.gwt.dev.Compiler -sourceLevel 17 -strict com.example.bad.Bad fails with one error per unsupported type (the compiler repeats the list in a second "Finding entry point classes" pass):

Source: GWT — FAQ: Troubleshooting

The hint is misleading for JRE types: no module can be inherited to obtain java.time.LocalDate; either avoid it, use a GWT replacement, or supply the class yourself with super-source (below). A class that is emulated but lacks a member produces a different message, because the type resolves and only the method does not:

Source: GWT — Missing parts of JRE Emulation

Because some errors surface only in the second phase, read the whole list before fixing one by one, and compile with -strict (alias -failOnError, which the archetype turns on through <failOnError>true</failOnError>) so that a unit with errors is never silently skipped.

The language level (syntax) and the library level (emulation) move independently: the compiler’s front end (JDT) accepts the syntax, while the library has to contain the classes the syntax relies on. The release notes give the history:

Source: GWT — Release notes: 2.13.0, GWT — Roadmap

The compiler flag is -sourceLevel (values auto, 1.8, 9, 10, 11, 17 in the 2.13.1 help text). The gwt-maven-plugin exposes it as <sourceLevel>, whose default is the user property maven.compiler.source; the archetype-generated parent POM sets it explicitly next to failOnError:

Source: gwt-maven-plugin — gwt:compile: sourceLevel

The command-line compiler’s default is 1.8 (the default argument registered in ToolBase; the -help text and the Developer Guide are right), so Java 12 to 17 syntax needs an explicit -sourceLevel 17. The value auto resolves to the running JVM’s level. Set it explicitly in the build, and keep the release setting of maven-compiler-plugin and the GWT sourceLevel equal so javac (server and tests) and the GWT front end accept the same code.

The following shared class uses Java 17 syntax and compiled and ran in the browser build and on the JVM:

Source: GWT — Release notes: 2.12.0

Records (record Copy(String title, int n) {}), text blocks, var, and sealed hierarchies with permits also compiled at -sourceLevel 17; in the browser a record printed as Copy[title=Emma, n=2] and its generated equals returned true, as on the JVM. What does not compile is Java 21 pattern matching in switch. With level 17 the compiler reports:

Source: GWT — Compatibility: Language support

Use instanceof patterns and if/else chains until the supported level moves. The syntax itself is the ordinary Java covered in the Records and Sealed Classes, Pattern Matching, Lambdas and Method References, Generics and Streams and Collectors pages; the point here is only whether the GWT version and its library accept it. Two details are specific to GWT:

JavaScript has one numeric type, the 64-bit floating point number. GWT builds the Java primitives on top of it, and the differences are the main source of bugs in code that was written for the JVM and is later shared. The probe below runs the same statements in the browser (2.13.1, production-style output) and on JDK 21. The operands come from Integer.parseInt/Long.parseLong on purpose: the compiler folds constant expressions (Integer.MAX_VALUE + 1 printed -2147483648 in the browser only because it was folded at compile time).

Source: GWT — Compatibility: Language support

Source: GWT — Compatibility: Language support

The rules that explain the table:

These semantics are why the Bookshelf Book of the scenario keeps a long id and an int copies and does no arithmetic on them beyond counting and comparing; a checksum (an ISBN check digit, a cache key) belongs in a method with explicit | 0 or in a long. The Java-side background is on the Primitive Types and Variables, Operators and Expressions and Numbers and Math pages.

String is the JavaScript string, and the emulation re-implements the Java methods on top of it. Most methods behave as in Java (substring, indexOf, replace, trim, toUpperCase gave STRASSE for "stra\u00dfe" as on the JVM); the differences are concentrated in four places.

Regular expressions are JavaScript regular expressions. String.matches, replaceAll, replaceFirst and split hand the pattern to the browser’s RegExp. The Javadoc comment of the emulated split says the same and advises using only the subset of regular expression syntax common to Java and JavaScript. Observed with Chrome:

Source: GWT — Compatibility: Differences between JRE and emulated classes

The dangerous cases are the silent ones (\p{Alpha}, \Q..\E, character-class intersections [a-z&&[^bc]], lookbehind support that depends on the browser), which return a wrong answer rather than failing. Keep regular expressions in shared code to the common subset, put them in one class, and test that class both on the JVM and with a GWTTestCase (see Testing). The Java-side syntax is explained on the Regular Expressions page.

The portable alternative is com.google.gwt.regexp.shared.RegExp. It is in the module com.google.gwt.regexp.RegExp, has a JavaScript-style API (compile(pattern), compile(pattern, flags), exec, test, replace, split, quote, getGlobal, …​) and exists in two implementations: on the browser it calls the native RegExp; on the JVM it is backed by java.util.regex.Pattern, and it translates the JavaScript replacement syntax ($&, $$, backslashes) for Java. Its Javadoc warns that Java-only constructs such as [a-z&&[^bc]], (?<=foo), \A and \Q work only in the JVM implementation and are rejected by neither. The shared validation class used in the Bookshelf (for the ISBN field of the book editor) is therefore:

Source: GWT Javadoc — RegExp

Both sides printed prefix 978, check digit 7, invalid and 978-0-5965-2068-7 for the inputs 978-0-596-52068-7, 12-34 and 9780596520687. For the module, add <inherits name="com.google.gwt.regexp.RegExp"/>; on the server the classes come from the GWT library jar (they are in gwt-servlet-jakarta-2.13.1.jar as well as in gwt-user).

String.split follows Java 8 semantics since 2.13.0. The release notes list it as a breaking change. The implementation now discards a zero-length match at the start of the input, and trailing empty strings are removed unless the limit is negative. Observed on 2.13.1 and identical on the JVM:

Source: GWT — Release notes: 2.13.0

Code written against earlier GWT versions that relied on a leading empty element from a zero-width split must be adjusted when upgrading. The same release makes Collectors.toMap throw when a value is null (the JVM behaviour, although not what its Javadoc says) and removes the AccessControlException emulation.

Characters and locales are ASCII-oriented. The Character emulation says several methods "do not properly handle characters outside of ASCII": isLetter, isDigit, isLetterOrDigit, isLowerCase, isUpperCase, and Character.isLetter('\u00e9') returned false in the browser (it is true on the JVM). Use RegExp with the right flags, or compare against explicit ranges, for user-facing text such as the author names of the Bookshelf, and use the i18n classes for case and number formatting.

Formatting is not String.format. String.format, formatted and printf are missing (the localization issue above); use NumberFormat, DateTimeFormat, Messages interfaces and SafeHtml templates.

Shared code is Java that must compile twice: with javac against the full JDK for the server, and with the GWT compiler against the emulation for the browser. The Bookshelf keeps it in its own Maven module, bookshelf-shared, whose jar is also published with the sources classifier because the GWT compiler needs source files:

Source: GWT — Organizing Projects: Standard Directory and Package Layout

The module file lives in the package com.example.bookshelf, so <source path="shared"/> means com.example.bookshelf.shared, found in the sources jar of bookshelf-shared. If that jar was not built, the client compile fails, for example when running mvn test -pl bookshelf-client -am without package:

Source: GWT — Organizing Projects: Modules

Use mvn verify (or install) so the sources jar exists before the client is compiled.

The discipline for shared classes is short:

@GwtIncompatible (com.google.gwt.core.shared.GwtIncompatible; a copy under any other package works because only the simple name matters) removes the annotated type, method, constructor or field from what the GWT compiler sees, while javac still compiles it for the server. Its Javadoc warns that removing members this way can have surprising effects together with method overloading or inheritance. The probe’s Pricing.today() uses java.time and was ignored by the browser build, which compiled without error:

Source: GWT Javadoc — GwtIncompatible

When the behaviour differs but both versions must exist in the same compilation unit, ask the environment. com.google.gwt.core.shared.GWT is the class made for shared code; it also exists on the JVM, where isClient(), isScript() and isProdMode() return false and getVersion() returns null:

Source: GWT Javadoc — com.google.gwt.core.shared.GWT

Running the shared GWT calls in a plain main on JDK 21 printed false false false null for isClient, isScript, isProdMode and getVersion, and GWT.create(Runnable.class) threw:

Source: GWT 2.13.1 — core/shared/GWT.java

Prefer @GwtIncompatible or super-source over runtime branching for anything that pulls in a non-emulated class: a GWT.isClient() branch still has to compile on both sides, whereas the @GwtIncompatible member is not seen by GWT at all, and the optimiser removes unreachable branches of isScript() checks only after the types in them have been resolved.

The <super-source> module element "re-roots" a source path, so that files below it replace or add classes as if the directory prefix were not there (the module XML elements are covered in Project Structure & Modules). The Developer Guide’s own example is adding java.util.UUID: put the file in com/example/myproject/jre/java/util/UUID.java, add <super-source path="jre"/> to MyProject.gwt.xml, and the compiler sees it as java/util/UUID.java. GWT uses the same technique for its own emulation. The same mechanism lets shared code have a different implementation in the browser than on the server without changing the class’s name or callers:

Source: GWT — Organizing Projects: Module XML files

Source: GWT — Organizing Projects: Module XML files

In the browser Platform.describe() returned Browser: probe; on the JVM the same class name returned the JVM: ... text. The two files have the same fully qualified name com.example.probe.shared.Platform, so callers (here ProbeEntry) and the shared module need no change. This is exactly how com.google.gwt.regexp.shared.RegExp is built: a pure Java version in the shared path for the server, a super-sourced version that calls native JavaScript for the browser (its module declares both <source path="shared"/> and <super-source path="super"/>).

Rules and caveats:

The "GWT Class API" reference page, RefGWTClassAPI.html, is a short pointer: it only introduces the class library (user interface, RPC, internationalisation, unit testing) and links to the Javadoc; the Javadoc is the actual reference. The class that every application meets first is com.google.gwt.core.client.GWT; com.google.gwt.core.shared.GWT is its JVM-safe base for shared code. The members below were checked in the 2.13.1 sources and, where marked, run:

Source: GWT Javadoc — com.google.gwt.core.client.GWT

The Bookshelf entry point uses several of them in a few lines:

Source: GWT — Compatibility

@RemoteServiceRelativePath removes the need for setServiceEntryPoint in almost every case; the explicit form is shown because it is where getModuleBaseURL() is used. A user-facing message in the handler must not include the exception text, which may contain internal details.

Older GWT material, including the first-edition chapters on the generated JavaScript and the JRE emulation library (GWT 1.3 and 1.4, 2007), describes a world with these differences:

Source: Manning — GWT in Action

Source: GWT — FAQ: Troubleshooting

Source: GWT — Release notes

What’s Changed & Migration lists the changes across the whole section.