Google Web Toolkit – Hosted vs. Web Mode

07 Oct
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

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

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.


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.


Posted by on October 7, 2008 in GWT/ JSNI / COMPILER


Tags: , , , , , , , , , , , , , ,

10 responses to “Google Web Toolkit – Hosted vs. Web Mode

  1. Adrian Buerki

    October 8, 2008 at 12:20 pm

    You write that the GWT shell is not open source. I’m quite sure GWT is fully open source since December 2006. The GWT homepage says ‘As of version 1.3, Google Web Toolkit is licensed under the Apache 2.0 open source license’… Correct me if I’m wrong.

  2. marco skv

    October 8, 2008 at 12:44 pm

    Hosted mode is available also on Macintosh, not only for Win & linux 😉

  3. Kent

    October 9, 2008 at 4:26 am

    Nice overview of Hosted mode vs. Web mode. Well done, however from version 1.4 and on, gwt:module and gwt.js files are no longer used. When the HTML loads the nocache.js file loads automatically. The nocache file is responsible for bootstrapping the application. The bootstrap sequence is as follows: (1) Establish property-providers, (2) Compute script’s base location, (3) Process metatags, (4) Determine browser using MD5 property values, (5) Insert appropriate cache.html file into an iframe, (6) Load all resources, (7) Start the module. –Cheers!!

  4. Vinay J

    October 12, 2008 at 2:02 pm

    Hi Kent, Thanks for your valuable comments

  5. SaebNajim

    January 31, 2009 at 2:35 pm

    thank you about these good information but i have a project work ok in the hosted mode but when i press compile i get the html only and no thing happened can any one tell me why or what i do (i have more than one window and have rpc connection ) thank you about the help SaebNajim

  6. Samuel

    January 11, 2010 at 1:31 pm

    Hi, Do you know how we can check if we are running in hosted mode or in web mode? I have seen people suggest “GWT.isScript()” but that will not work as soon as you use JSNI in your application.

    Is there an alternative way of telling this?

    Best regards, Sam

  7. Vinay

    January 11, 2010 at 1:37 pm

    Hi sam,

    You can use like below

    if (GWT.getModuleBaseURL().indexOf("/html/") > -1) // tomcat or websphere
    return "../..";
    else // hosted mode
    return "..";

  8. sekhar

    November 16, 2010 at 1:25 pm

    can u please explain me how to check whether we are executing your gwt application in Hosted mode or in Web mode?

  9. Pingback: headshops

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: