Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

Working with the Google Web Toolkit

by Robert Cooper
SEO + Web Traffic = Money

The Google Web Toolkit (GWT) was rolled out for JavaOne 2006 at an innocuously titled session. Due to what I assume was a timing miscommunication, the Google Blog scooped the presentation, but the impact was no less felt.

GWT is, in essence, a JavaScript generator. The interesting thing is what this JavaScript is generated from: Java. GWT takes Java code written against a special API and converts it into browser-runnable Ajax code. If that weren't enough to make it cool, it also includes a test harness (see Figure 1) that will execute the Java code inline with a test browser, allowing you to step-through debug (see Figure 2), profile and unit test your Ajax front end in your favorite IDE or at the command line.

Google Web Toolkit console window
Figure 1. GWT includes a console window with hierarchical logging.

Debugging in NetBeans
Figure 2. Java execution in the test browser allows for step-through debugging of code.

As they say, "But wait! There's more!" GWT also includes a basic RPC framework for making calls back to your server application in the form of a servlet. The RemoteServiceServlet allows you to implement service methods on an implementation and expose these to your generated Ajax application. This is done by simply adding new public methods to the servlet, and the GWT will handle serialization and deserialization to and from the client. How much would you pay for a framework like this? Don't answer yet!

GWT also includes a set of core DOM mapped classes and layouts that are more familiar to desktop application developers, such as the dock panel and horizontal panel. Prefabbed widgets such as PopupPanel for context popups, DialogBox for popup blocker friendly dialogs, and StackPanel for Outlook-bar style displays. There is also a URI and History management system for maintaining a bookmarkable and "back buttonable" state through your application.

Getting Started

GWT is really just an executable Java application with some hooks into Tomcat and either Mozilla or MSIE under Linux and Windows, respectively (sorry Mac users, you are out of luck for now). When you download the GWT, it comes with several sample projects, including "KitchenSink," the GWT equivalent of SwingSet. You can run the batch file in the samples/KitchenSink directory to see it run. Two things will pop up: the GWT server monitor application and browser window where you can see the application run. Executing java com.google.gwt.dev.GWTShell --help with your platform's *dev.jar and gwt-user.jar will show you the options available:

Google Web Toolkit 1.0.20
GWTShell [-port port-number] [-noserver] [-logLevel level] 
    [-gen dir] [-out dir] [-style style] [-notHeadless] [url]

  -port         Runs an embedded Tomcat instance on the specified
                port (defaults to 8888)
  -noserver     Prevents the embedded Tomcat server from running,
                even if a port is specified
                TRACE, DEBUG, SPAM, or ALL
  -gen          The directory into which generated files will be
                written for review
  -out          The directory to write output files into 
                (defaults to current)
                or DETAILED (defaults to OBF)
  -notHeadless  Causes the log window and browser windows to be
                displayed.  Useful for debugging.
  url           Automatically launches the specified URL

Google includes an applicationCreator script that will generate a set of batch files, scaffolding classes, and directories for a new GWT project. For our purposes here, however we are going to bypass this and start from scratch. First you will want the GWT Maven plugin installed. You can install this by unzipping the plugin project and typing maven plugin:install-now. Also, you will want to copy the gwt-user.jar to ~/.maven/repository/com.google.gwt/jars/ manually. Since this JAR needs to be included in your final WAR file, it needs to be registered as a dependency in the Maven POM file.

Search Engine Optimization

Essential Reading

Search Engine Optimization
Building Traffic and Making Money with SEO
By Harold Davis




Read Online--Safari
Search this book on Safari:

Code Fragments only

Project Basics

GWT uses a basic structure that might seem a little alien at first, so let's take a quick tour. The code we will be using is available as a ready-to-run application in the Resources section. It provides an implementation of a simple Table class that will toggle a CSS element on a selected row and an RPC call to fetch information for the table from the server.

First is the [Module].gwt.xml file. This is an XML marker in your project that maps to an EntryPoint class for a particular module. Think of a module as being a self contained display, like a JFrame. In "Table.gwt.xml," our module is as follows:


 <inherits name='com.google.gwt.user.User'/>

 <entry-point class='com.totsp.gwt.client.TableEntryPoint'/>

Next, to start up our module, we need a root HTML document to run. Here we are using src/java/com/totsp/gwt/public/Table.html. To embed your entry point into your HTML document, you need to include two things. First, add a meta tag that indicates what the module you want to include is:

<meta name='gwt:module' 

Second, at the point in the HTML where you want the GWT to start rendering, you include the gwt.js boilerplate JavaScript file:

<script type="text/javascript" 

This will then run a default script and inspect the gwt:module value to decide what it needs to start up. Also notice that you place your HTML host page, CSS files, and graphic assets in the public package of your Java source tree, not in the web app. This is a little counter-intuitive, but the GWTShell and the GWTCompile steps expect to load them out of here. You can't, however, really put them in the web app folder, because GWT will clobber them with defaults if you do.

Pretty simple so far. Now we need to start actually writing our classes. The first one is our EntryPoint implementation. This is what actually starts rendering stuff.

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.user.client.Window;
import com.google.gwt.user.client.ui.RootPanel;
import com.google.gwt.user.client.ui.Widget;

public class TableEntryPoint implements EntryPoint {
  private Table table;

  public void onModuleLoad() {
    table = new Table( null, "myTable" );
    getData(); //just ignore this for the moment.

Looking over these classes, we have a few things here. First is the Window class. This maps, roughly, to what you would think of as the JavaScript window object. It exposes alert() and getClientWidth() among other things. The RootPanel is a singleton class that returns the root for placing widgets via get(). This singleton methodology is pretty convenient for working with, so we are going to add this to our classes. Next is Widget. This is the base class for widgets and is used for event handlers, such as the following from the "Hello" example:

  public void onClick(Widget sender) {
    Window.alert("Hello, Ajax");

To start up our EntryPoint class, we need to override the onModuleLoad() method with our code to build our display. For the purposes of this article, we are only going to use our simple Table class.

The Table class contains a very simple operation. It extends FlexTable, then adds itself as a listener to itself. When a table row is clicked that isn't the header row (if there is one), it adds a CSS style name postfixed with -selected to that row. Everything else is done in the CSS.

public void onCellClicked(SourcesTableEvents sender, 
            int row, int cell) {
        .removeStyleName(selectedRow, selectedStyle);
    if ((source.getHeaderRow() == null) || (row > 0)) {
            .addStyleName(row, selectedStyle);
        selectedRow = row;

The table also has a method for populating data from a TableDataSource. Let's look at that next.

Building the Table

Our table class here just does a pretty simple thing: draw a table from a TableDataSource implementation, then toggle a stylesheet class on the selected row so we can highlight it. To do this, we are going to extend the GWT's FlexTable class. This is a class that represents an HTML table, but lets the author create table cells on the fly. To populate our table we are going to use a very simple TableDataSource that we can fetch from our RPC servlet. For now, lets just look at the code.

The first step is to build your service interface. Ours is pretty simple:

public interface DataService extends RemoteService {    
    public Person[] getData();

Next, we need to create an Async interface for the service. This is done entirely with naming conventions. You need to create an interface that matches the service interface and all methods. However, instead of return types, every method is void and the last argument is an AsyncCallback implementation, thusly: public void myMethod( Param p..., AsyncCallback callback). Finally, the interface class name should match the RemoteService interface name, postfixed with Async.

For our simple service, it looks like this:

public interface DataServiceAsync {
    public void getData(AsyncCallback callback);   

Next, you need your service implementation. This needs to extend the GWT's RemoteServiceServlet servlet and implement your service interface.

public class DataServlet 
    extends RemoteServiceServlet implements DataService {
    public Person[] getData(){

Whew. Almost there. Now we want to add the servlet to both the web.xml (so it will be there when we deploy the war) and we want to add a declaration to our Table.gwt.xml file. This second entry tells the GWTShell to load the servlet and also mounts it in the testbed Tomcat and generates client stubs for you.

<servlet path="/DataService" 

Now, we are ready to deal with the call itself. GWT only supports Asynchronous calls. There are a number of technical reasons for this, notably that the most obvious path to do a synchronous call would be to spin waiting for the response. Unfortunately, many browsers will not actually fire the XmlHttpRequest event until said spinning is done. But hey, this is Ajax, not Sjax. Right?

Now we add the getData() method to our EntryPoint class. To do this, we need to get a DataServiceAsync implementation from the GWT class, then create an AsyncCallback handler. This is a simple interface that just has an onSuccess() and onFailure() method to handle the return state of the callback.

private void getData(){
    DataServiceAsync dataService = 
       (DataServiceAsync) GWT.create( DataService.class );
    ServiceDefTarget endpoint = (ServiceDefTarget) dataService;
    dataService.getData(new AsyncCallback(){
        public void onSuccess(Object result) {
                new SimpleDataSource( (Person[]) result ) );

        public void onFailure(Throwable caught) {
            Window.alert("Unable to get data from server: "



Notice the unfortunate cast to ServiceDefTarget. Why they couldn't have made a GWT.create(Class clazz, String url) method is a bit beyond me, but you gotta do it.

Now, we simply call the setSource() method on our table object and voila, the table will render itself with the new data. Also notice that our objects that move from the server to the JavaScript world have to implement IsSerializable. This also supports arrays and basic collections, although in my experience, collections are sometimes sketchy and may give you cryptic errors. It's best to avoid them where possible for the moment.

Revisionist History

As anyone who has used (most) Ajax or RIA apps knows, the back button can be the bane of your existence. Fortunately, GWT includes a means of dealing with it. The History class allows you to store a single String token that you can use to capture the display state and redraw as needed. This is accomplished by inserting the token into the anchor part of the URL on the page and writing the location.history as needed.

Let's modify our simple example to support the back button. First, we want to capture state changes and store them in the History object. To do this, we will add a new TableEventListener to our table in our onModuleLoad():

//Add a new listener to record the row history
table.addTableListener( new TableListener(){
    public void onCellClicked(SourcesTableEvents sender, 
        int row, int cell) {
        History.newItem( ""+row );

Now, we want to capture changes to the back button and update our selection on our table appropriately. So we will make our EntryPoint a HistoryListener:

public class TableEntryPoint 
    implements EntryPoint, HistoryListener {

    public void onHistoryChanged(String historyToken){
        table.onCellClicked( table, 
            Integer.parseInt( historyToken ), 0);

Now, whenever you click the back button, it will track back to the last selected item. The last step is to make sure our initialization works in case the page is bookmarked or gets a hard reload. To do this, we go back to our getData() method on the EntryPoint and modify the onSuccess() handler of the AsyncCallback. This will check to see if there is a stored token in the History object and reset the state of the table to the selected row stored in the history token.

public void onSuccess(Object result) {
    table.setSource( new 
        SimpleDataSource( (Person[]) result ) );
    if(History.getToken().length() != 0){
        table.onCellClicked( table, 
            Integer.parseInt( History.getToken()), 0);

The final step is to go back and modify our HTML host page with a hidden iframe that the GWT script uses for history manipulation:

<iframe id="__gwt_historyFrame" 

This is a pretty primitive example, but hopefully you understand enough to make use of the History class in a more complicated application. Figure 3 shows the sample application's table display.

Figure 3. Our finished table widget in the GWT browser.

That's Not All!

There is still more coolness in the GWT. There is still more not covered here, included a JavaDoc based-annotation system for typing collections (Java SE 5 generics aren't supported for IsSerializable), JUnit testing frameworks, and lots of cool widgets to use and extend. Also, be sure to check out the GWT provided examples. Although I admit I find some of the programming idioms a bit strange -- and it may simply be my history as "Not a GUI developer guy" -- they definitely give you a feel for what can be done with the framework. In fact the DynaTable example is a much more robust version of what we have built here.

The Maven Module

The GWT Maven module provided with this article gives you a few options for working with the Google Web Toolkit in a Maven project. You will notice in the sample code provided the following set in the project.properties:


The first line is the path to your GWT installation. The second is the target you want the GWTShell to start with when you call the gwt goal. This will run the shell and open the test browser. compiletarget is the module declaration you want to use when you call gwt:compile. Finally, logLevel is the log level to show in the GWTShell when you are testing. You can look at the Mevenide properties panel in your project properties to see the rest of the settings. They pretty much map one-to-one with the command-line arguments for GWT.

The final target is gwt:debug. This will start the GWTShell in debug mode allowing you to step trough your Java code. Once you call this target, the debugger will come up and wait for a connection before anything is rendered. In NetBeans, you can click on "Attach To Debugger," select your local machine, and port 8888 to connect. You can then set breakpoints in your code and move through the web app in the debug browser! This is by far the greatest feature of the GWT. Debugging JavaScript -- even with Venkman -- always felt a little lacking. GWT lets you keep using the same tools you're used to with no changes.

Lastly, you want to make sure you have a gwt:compile executed before your war:war Maven goal. You can accomplish this by adding in the project maven.xml:

<preGoal name="war:war">
 <attainGoal name="gwt:compile"/>

License Concerns

How much would you pay for all this? Well, it is free. However, it is not under any OSI license you might be familiar with. Google has terms available -- basically you are free to use it, but not redistribute it outside your organization. Now, I am no lawyer, but I am seriously troubled by this clause, however:

you may not distribute Google Web Toolkit Development Tools or any services or software associated with or derived from them, or modify, copy, license, or create derivative works from Google Web Toolkit Development Tools, unless you obtain Google's written permission in advance.

One thing that GWT seems built to do is allow people to build new and interesting components. Indeed, when I first saw it, it screamed "whole new community" of GWT-based widgets. It would seem to me, however, that this is forbidden as a derivative work. It is also worth noting an interesting part of the privacy notice on the download page:

Privacy notice: When you use the Google Web Toolkit's hosted web browser, the application sends a request back to Google's servers to check to see if you are using the most recent version of the product. As a part of this request, Google will log usage data including a timestamp of the date and time you downloaded the Google Web Toolkit and the IP address for your computer.


Robert Cooper is an independent Java developer in the Atlanta area, working with J2EE technologies and web/web service projects.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.