Google Web Toolkit – Hosted vs. Web Mode

What is Hosted Mode and Web Mode ?

When you invoked a GWT application you were using what Google calls hosted mode. Hosted mode is only used during development. When in production, your application will be running in web mode. Before going any further in using GWT you need to understand the difference between the two. Note that as of this writing, hosted mode is only available on Windows and Linux.

Hosted mode

Think of hosted mode as training wheels for your GWT application. It’s a hybrid development environment unique to GWT that lets your code run as real Java code, but still inside a browser. Execution in hosted mode is controlled by the Google Web Toolkit development shell.

The development shell is actually an Eclipse Rich Client application, consisting of the shell console, a tomcat server, and one or more hosted browsers.

The hosted browser has two connections back to the development shell. One is just a regular http connection to get the web pages, .css files, images, and other resources. All these are handled by the embedded Tomcat server using a servlet called com.google.gwt.dev.shell.GWTShellServlet.

The second connection is a back-door that intercepts all interactions inside the hosted browser and routes them not to JavaScript but to Java code in the shell. That Java code in turn calls your real client Java code, which was compiled to bytecode by your IDE. The exact details of how this is done are hidden in the shell code, which is not open source.

• The Shell program opens a hosted browser window, which loads MyApp.html.
• MyApp.html loads gwt.js with a <script> tag.
• gwt.js scans MyApp.html and parses out the <meta name=’gwtmodule’> to get the module name.
• GWT reads the module file (MyApp.gwt.xml) to find the name of the EntryPoint class (MyApp).
• The MyApp class is instantiated and its onModuleLoad( ) method is called. Your application begins.
• Your application code makes calls into the GWT user library (gwt-user.jar), which is also Java code.
• Code in gwt-user.jar manipulates the hosted browser’s DOM to add UI components to the web page, and redirects all browser events back to the Java application code using special hooks in the browser.

Because real Java code is running, you can use Java tools like the Eclipse debugger, findbugs, pmd, JUnit, and so forth. It’s almost as if you were developing a rich client program with Swing or SWT because it’s Java end-to-end.

Once you’ve debugged and unit tested your code the next step is to compile it into a form that can be run inside a regular browser (not one that has been hijacked by the development shell). That’s where web mode comes in.

Web mode

When you click the Compile/Browse button in the hosted browser, the GWT compiler translates your .client package into JavaScript and opens a normal web browser to view the application. At this point pages are still served by the shell’s Tomcat instance, but they could just as easily come from the file system or a normal web server.

Another way to invoke the GWT compiler is with the shell script provided by the scaffolding (MyApp-compile). You could also write an Ant script to do it if you prefer. For example to maintain the gwtpowered site I have an ant script that does the compile and then copies everything to my hosting provider. You can find the source at http://code.google.com/p/gwtpowered.

However you invoke it, the GWT compiler combines your code with a JavaScript version of the GWT API (the equivalent of gwt-user.jar) in one JavaScript file. This code and several supporting files are placed in the www directory inside your project. Everything from your public directory is copied there as well. The table below explains what all the files do:

Filename ----------------------Description
long-hex-name.cache.html -----------Compiled JavaScript
long-hex-name.cache.xml -----------Implementation defined
module-name.nocache.html-----------Cache file selection
gwt.js ----------------------------Common GWT bootstrap code
history.html -----------------------Contents of history IFrame
MyApp.html -----------------------Main page, copied from public
tree*.gif --------------------------+/- images used by the Tree widget

(more on GWT Web Mode Files)

The flow of execution during a page load in web mode is a bit different than in hosted mode.
Here’s a breakdown of what happens:

1. The web browser loads MyApp.html.
2. MyApp.html loads gwt.js with a <script> tag.
3. gwt.js scans MyApp.html and parses out the <meta name=’gwtmodule’> to get the module name.
4. gwt.js modifies the page to include an <iframe> that causes the source file module-name.nocache.html to be loaded.
5. JavaScript inside the file module-name.nocache.html looks at the browser’s userAgent field to determine what kind of browser the user is running (IE6, Mozilla, Opera, etc.). Then it selects the correct code (cache file) for that browser type and redirects the <iframe> there.
6. The JavaScript equivalent of your onModuleLoad( ) method is executed, and the rest of your application goes from there. Manipulations to the browser DOM are performed with ordinary dynamic HTML calls in the compiled JavaScript.

Obfuscation

By default, the GWT Java to JavaScript compiler will produce obfuscated output. Code that has been obfuscated is smaller than humanreadable code, and is harder to reverse-engineer. It’s very difficult to debug, though. Should you ever need to debug the JavaScript that GWT produces, you can turn off obfuscation with command line parameters on the GWT compiler (for example as arguments to the MyApp-compile.cmd script). Use the -style pretty option to produce good looking output with readable names and indentation. To see full Java types as part of the names, use the -style detailed option instead.