Introduction to GWT – Tutorial

Posted by

What is GWT?

Writing browser based AJAX (Asynchronous JavaScript and XML) web applications can be very tedious and requires in depth knowledge of both JavaScript, and myriad browser quirks and incompatibilities. The Google Web Toolkit (GWT) is an open source framework that allows Java developers to easily develop AJAX web applications without learning the ins and outs of JavaScript and browser development.

GWT provides a Java API that lets you build component based GUIs while avoiding JavaScript, and abstracting the HTTP protocol and underlying browser DOM model. All of this achieved using the GWT compiler, which does not generate Java bytecode, rather it generates JavaScript! The GWT compiler takes your client side Java code and generates JavaScript. A compiled GWT application consists of fragments of HTML, XML and JavaScript. If you want to have your web application communicate with a web server, GWT has you covered as well. GWT has a Remote Procedure Call (RPC) mechanism that makes it easy for the client and server to pass Java objects back and forth.

GWT also helps to enables developers to effectively test and debug their applications without first compiling them into JavaScript, and deploying the applications to a web-server. GWT allows applications to be run in what is called “Hosted Mode”. In “Hosted Mode”, a JVM executes your GWT application code as Java bytecode inside of an embedded browser window. Running GWT applications in “Hosted Mode” makes debugging your GWT applications very easy. Once you have tested your GWT application in “Hosted Mode”, you can compile your Java source code to JavaScript and deploy your application. GWT applications that have been deployed are said to be running in “Web Mode”.

So, in short, you write your application’s client and server side pieces in Java, and the GWT compiler will convert your client Java classes into browser compliant JavaScript and HTML. You deploy this JavaScript and HTML to your web servers, so end users will only see the web mode version of your application, while the server side classes can be deployed on Tomcat or any Servlet container of your choosing.

The goal of this tutorial is to help Java developers with little knowledge of web development learn how to develop web applications using GWT. Once you are done with this tutorial you should have the skills to build complex and fully functional GWT applications.

Reference material

For more information on GWT, to get resources, tools, and 3rd party libraries that you can use in your projects, visit the Unofficial Google Wiki page on GWT. It has a list of plugins that are available for various IDEs, and it has a set of widgets/GWT components that you can use in your projects. It also provides links to projects like MyGWT and GWT-EXT, which allow seamless integration with EXT JavaScript libraries. You can also find links for GWT log library, GWT drag and drop library, and GWT sound library.

To learn more about GWT, I recommend reading these good books – GWT Solutions, GWT Applications, AJAX Security.

Need more help? offers training courses to empower you, and consulting services to enable you.


Once you are familiar with GWT after reading this tutorial, we have lots more in-depth material that will show you how to use GWT in the real world on this site. We cover topics such as module creation, deployment scenarios, using RPC sessions, history/hyperlink support and many more. We also host tutorials on lots of other technologies, like XML – SAX, DOM, Using Java to manipulate XML, database access using XML, parsing XML from web services, etc. You can find them all here. We have tutorials on Swing and graphics programming, multithreading in Java, as well as SOA related topics, and JavaME/J2ME content as well.

GWT Primer – things to know before getting started

GWT Browser Support

As of GWT version 1.4, GWT supports the following browsers:

  • Firefox 1.0, 1.5, 2.0
  • Internet Explorer 6, 7
  • Safari 2.0
  • Opera 9.0

The GWT Compiler

The GWT compiler converts Java source code into JavaScript. The GWT compiler supports most of the Java language and emulates a subset of the Java runtime library.

Language support

As of GWT version 1.4, the GWT compiler can compile source code that is compatible with J2SE 1.4.2 or older.

The GWT compiler:

  • supports all intrinsic types (byte, char, short, int, float, double, Object, String) and arrays. Please note that since there is no 64-bit integral type in JavaScript, Java variables of type long are mapped to JavaScript double-precision floating point values. Try to use int variables whenever possible.
  • supports Java Exception handling. try, catch, finally and user defined exceptions are supported. Throwable.getStackTrace() is only supported in “Hosted Mode”.
  • parses Java assert statements, but does not generate JavaScript code for them
  • does not support Reflection or dynamic class loading.
  • does not support object finalization during garbage collection
  • does not support Strict Floating Point (strictfp keyword) and can’t ensure any particular degree of floating point precision in translated code.
  • does not support Java Serialization

Runtime Library Emulation

GWT provides a JRE emulation library. This library does NOT emulate all the J2SE and J2EE classes.

The GWT JRE emulation library supports some classes from java.lang and java.util packages. Find out which classes are supported here

Java regular expressions aren’t completely supported in GWT. If you are going to use regular expressions in your GWT application, you need to ensure that you only use Java regular expressions that have the same meaning in JavaScript.

Find out more about Java regular expressions
Find out more about JavaScript regular expressions

The GWT JRE emulation library does not support Java Serialization. In its stead however, GWT has and RPC facility that provides automatic object serialization. This RPC facility allows client-side code to make remote method calls and pass GWT serialized objects as parameters.

To find out more about the GWT compiler check out this article.

Client Side Code

GWT web applications are made up of two distinct pieces. The piece of your application that is sent across the network to a user, where it runs as JavaScript inside of a web browser, is referred to as client-side code. When writing client-side code it is important to keep in mind that this code will ultimately be turned into JavaScript. So make sure to only use libraries and Java language constructs that can be translated.

Server Side Code

The piece of your application that runs on a server computer is referred to as server-side code. Your GWT application might need to interact with your server, e.g. to load or save some data. In order to do this, the application makes a client-side request (from the browser) using GWT’s RPC mechanism. While processing the RPC call, server-side code is being executed. In GWT, client-side code compilation is not dependent on server-side code. As a result, you’re server-side code does not have any of the limitations that are imposed on the client-side code and you are free to choose whatever technology you want to use in your server-side code.

Deferred Binding

Deferred Binding is one of the key features that lets GWT produce well-optimized JavaScript code. As you saw earlier, the GWT compiler doesn’t support Java Reflection or dynamic class loading (also referred to as dynamic binding). This is because the JavaScript environment in which GWT applications run in doesn’t support it. Because dynamic binding is unavailable to GWT, GWT instead uses something called deferred binding. Deferred Binding is similar to dynamic class loading. While dynamic class loading occurs at runtime, Deferred Binding occurs at compile-time.

When the GWT Compiler compiles your client-side code, it determines all of the different “browser idiosyncrasies” it must support, and generates a separate, highly optimized version of the application for every specific configuration. So at the end of the day the compiler will generate a different version of your application for each different supported browser. But there is more to Deferred Binding than just multi-browser detection and support. Deferred Binding is a fully generic mechanism for handling context sensitive features.

A good example of where Deferred Binding is useful is Internationalization. The GWT Compiler uses Deferred Binding to generate completely separate versions of your application for each language. So if GWT supports 4 browsers, and you write your application in 4 languages, GWT will generate a 16 different permutations of your application at compile-time. During bootstrapping, at runtime, GWT picks the appropriate version of your application to show the user.

GWT Bootstrapping

Here is an overview of the bootstrap procedure for a GWT application:

  1. The browser loads and processes the HTML Host Page.
  2. When the browser encounters the <script src=”<Module Name>.nocache.js”> tag in the Host Page, the JavaScript code in the file is downloaded and executed.
  3. The .nocache.js file contains JavaScript code that resolves the Deferred Binding configurations (such as browser detection, Internationalization, etc). The browser uses a lookup table, generated by the GWT Compiler, to locate which one of the .cache.html files to use.
  4. The JavaScript code in .nocache.js then creates a hidden <iframe>, inserts it to the Host Page’s DOM, and loads the .cache.html file into that iframe.
  5. Once the .cache.html file is loaded, the actual program logic of the GWT application is executed.

GWT Compiler Output

The GWT compiler generates a series of, sometimes oddly named, files.

As of GWT version 1.4, you should typically see the following types of files:

  • <Module Name>.nocache.js (or <Module Name>-xs.nocache.js for cross-site script inclusion)
  • <Alphanumeric>.cache.html
  • <Alphanumeric>.gwt.rpc

.no-cache.js File

The “nocache.js” file is where Deferred Binding occurs. Before your GWT application can run, any dynamically-bound code must be resolved. This might include browser-specific versions of classes, Internationalization strings for the user’s selected language, etc. The “nocache.js” file includes a lookup table that maps Deferred Binding permutations to .cache.html filenames, e.g. “Firefox in German” and “Safari in English” would both be entries in the lookup table, pointing to different .cache.html files.

The file is named “.nocache.js” to indicate that it should never be cached, i.e. it must be re-downloaded and executed each time the browser starts your GWT application. The file must be re-downloaded each time is because the GWT Compiler regenerates it each time, but under the same file name. Allowing browsers to cache the file, would result in browsers not always downloading the latest version of the file when your application is recompiled and redeployed.

.cache.html Files

These are the files that actually contain your GWT application’s logic. A .cache.html file contains JavaScript code wrapped in a thin HTML wrapper. The GWT Compiler doesn’t simply output JavaScript (.js) files because certain browsers, under certain circumstances, do not properly handle compression of pure-JavaScript files. Wrapping the JavaScript in an HTML file solves the problem, and allows the GWT’s JavaScript output to be compressed.

Each .cache.html file uses the MD5 sum of its contents as its name. This guarantees deterministic behavior by the GWT Compiler. If you recompile your application without changing code, the output JavaScript code will not change, and so the MD5 sums (and the file names) will not change. If you do change your source code, the output JavaScript code will also change, and so the MD5 sums (and the file names) will change. Since these files will always have unique names, it is safe for browsers to cache them, hence the name “cache.html“.

.gwt.rpc File

As of GWT version 1.4, types that implement the interface now also qualify for serialization over RPC, but only if they are included in the .gwt.rpc file generated by the GWT compiler. The .gwt.rpc file serves as a serialization policy and indicates which types implementing are allowed to be serialized over the wire.

HTML Host Pages

Now that you know what the GWT compiler does and what it outputs (a bunch of JavaScript files) you might be wondering how any of this can be displayed in a web browser. This can be done by using a “Host Page”. Any HTML file with the proper set of tags can be used to display your GWT application.

Here is a sample HTML Host Page:

   1: <html>
   2:   <head>
   4:     <!-- Properties specified in meta tags are used to influence deferred binding        -->
   5:     <meta name='gwt:property' content='locale=en_US'>
   7:     <!-- Stylesheets are optional -->
   8:     <link rel="stylesheet" href="ExampleApp.css">
  10:     <!-- Titles are optional -->
  11:     <title>Example Application</title>
  13:   </head>
  14:   <body>
  16:     <!-- The fully-qualified module name, followed by 'nocache.js'                       -->
  17:     <script language="javascript" src="com.developerlife.example.ExampleApp.nocache.js"></script>
  19:     <!-- A history iframe must be included if you want to enable full GWT history support -->
  20:     <!-- The iframe id must be exactly as shown                                          -->
  21:     <iframe src="javascript:''" id="__gwt_historyFrame" style="width:0;height:0;border:0"></iframe>
  23:   </body>
  24:  </html>