Software Design UK

Home Page
Contact Us
About Us

Ajax Tutorial
GWT concepts
GWT Tutorial

Client Login
GWT concepts
Home Page > Training > Tutorials > Web 2.0 > GWT concepts

This tutorial sets out everything you need to know before you start to use GWT. It is VERY highly recommended to be read before plunging into GWT, due to the VERY large numbers of "Gotchas" that float around the GWT development for those who have not yet worked out how to use the system. It is suggested that the 15 minutes or so it will take to read this section will save at least one full day's work searching for answers to the questions that are answered below. (Guess how long I feel I wasted on this!!!!!)

The next section sets out what you need to know about the Java programs to achieve the website functionality and content you desire.

What is GWT

Google Web Toolkit is a comprehensive suite of programs developed by Google, which it provides free to the open source community (under the Apache 2.0 license) to implement Ajax.

Program code is written by the programmer. The programming language is Java. Whereas this may appear to be an obstacle to non-Java programmers, a large number of example programs are available and most experienced programmers should find their way fairly easily around the code to modify what they need, without too much difficulty.

When the programmer is ready to "compile" the Java code, the google "compiler" program takes the code and converts it to a series of html and javascript files that can be displayed on most browsers.

The key advantage to using the GWT is the sheer weight of functionality that Google has opened up to programmers, such as response to mouse movement, uploading and downloading files, a whole series of "Widgets" such as rtf edit boxes, check boxes, selectable input boxes etc, Ajax speed and very much more to give the user the experience that the program is a local program, despite being run through/over the internet. Despite its vast scope, there are still many circumstances that GWT is not an appropriate solution. So check below for an outline of some of the many web functions that continue to require conventional web techniques.

Where can GWT be downloaded from

GWT is the series of code that takes a programmers Java code and produces HTML/Javascript code. It is also a great many example programs that can be easily modified to create webpages of a great diversity of style and functionality.

GWT can be downloaded free from:

Is there anything else recommended for download

In order to create Java code, programmers can use any simple text editor, such as Kate (Linux) or Notepad (Windows). The problem is that Java code is fairly strict and easy to muddle, particularly for relative novices to Java. So the recommendation is to download the free Java editor "Eclipse", which highlights syntax errors as soon as you type them.

The colossal Java SDK and Eclipse (over 100MB for the two) can be downloaded for free as follows:
Java runtime environment (if needed) :

Eclipse SDK 3.2.1

TIP : For Edge Eft Ubuntu (6.10) linux users, a number of users have expressed difficulty in getting Eclipse to work. Having run the update manager to ensure I had all the latest programs, I went into Synaptics Package Manage to install both the "Sun Java" package and also the "Eclipse" package, following which everything loaded and ran without hitch. Prior to installing the "Sun Java" package, I had all sorts of unexplained problems getting Eclipse to run.

Once the html/javascript files have been created, they can be run. Whereas Google have done a great job to ensure everything will run smoothly, programming logic errors where the syntax is perfect (such as calling an object that has not been created) will cause the javascript to fail. Errors manifest themselves simply by the html page failing to load. Errors of this sort can be notoriously difficult to track down. There is a great plugin (or "Add-on" or "Extension") to Firefox called Firebug, that tracks Javascript programs and reports where errors have arisen.

Firebug can be downloaded for free from:

The GWT directory structure

Strange as it may seem, the standard GWT directory structure is a little complex. The purpose of this section is to help you find the files you need. It is not intended to be sufficiently complete to enable the structure to be set up by hand.

It is likely you will waste time trying to work within a different structure - partly because the GWT "compiler" assumes default locations.

When you set up a new project, you need to create a directory structure. You can do it by hand (unwise), or you can use the GWT "launcher" program "applicationCreator" (wise), which will create all the directories you need. (See below for more detailed instructions)

There are two base locations, the GWT code itself and your application code.

For the purposes of discussion, I will assume the GWT code has been extracted to a directory called ~/download/GWT. I will assume that the Java code you create for a client application is in a directory called ~/clients/gbpAjax (where the "clients" directory is where we keep our client files and "gbpAjax" is the client for whom we are writing the application).

Directory : ~/download/GWT

In ~/download/GWT are:
Directory : samples
File : gwt-user.jar

The "gwt-user.jar" is the file that contains many of the source java programs that comprise GWT. They include many base classes that you use in your own code (such as the Button.class for buttons or FilesUpload.class for uploading files from a web browser's local computer to a GWT application.) For those who like to poke around, the most useful section giving clues about how to code your Java is in the section "" within the "gwt-user.jar" file.

The samples directory contains several sample programs. Each program is independent of the other and has its own directory structure that follows the GWT "client" directory structure described below.

Directory : ~/clients/gbpAjax

When a program has been "compiled", the main directory will contain:

Directory : bin
Directory : src
Directory : www

The "bin" directory is a repository for GWT to place files it works on to create the final html/javascript. Many of its subdirectories are empty. This path can happily be ignored.

The "www" directory is where GWT places the output html/javascript files.

Directory : ~/clients/gbpAjax/www/com.sduk.gbpAjax

This directory contains gbpAjax.html, which is the file to open as the final "website". The directory also contains all the files that had been in the public "src" file (see below). It also contains a number of randomly named javascript and xml files. There is at least one javascript file for each of the main browsers that Google GWT provides for. (For example, there is a Javascript file for Mozilla browsers, another for Opera, another for Safari and at least one for Windows). The main gbpAjax.html file has some simple Javascript code to identify the visitor's browser and then select the appropriate javascript file that will work for that visitor.

TIP : When you upload the output files to your website, remember to upload every one of the randomly named files. Remember also that each time you "compile" the website, all the files are regenerated, with newly generated random names. So you may want to delete the previous random names before uploading the new ones.

The "src" directory is where you keep your source Java and HTML files as follows.

Directory : ~/clients/gbpAjax/src/com/sduk/client
Java files. If you are setting up a program called "gbpAjax", there will be at least three files as follows:
These three files give you an empty html page with no links and no text, but primed ready to take extra pages. Note that each additional web page you generate needs both a link to the page in the main "" file an additional "java" program that defines the content of the additional page.

Directory : ~/clients/gbpAjax/src/com/sduk/public
gbpAjax.css (optional)
other files/directories (optional)
The files and directories in this "public" directory are used by GWT. The gpbAjax.html file is used as the template by GWT for the final html file generated by GWT. GWT simply adds its html/javascript to the end of the gpbAjax.html file. This allows you to enter a "title" and "css location", for example, along with any Javascript you want to hard code. It also allows you to fill in a logo and any fixed text that you want to appear at the top of every page. Simply edit this file with anything you want to appear in the final version.

On "compilation", GWT copies the entire contents of the "public" directory to the final output directory. The only file it modifies is the main gbpAjax.html file, and the only modification made is the addition of the html/javascript needed to fill in the "java" generated web site to the end of the html file.

TIP : You are probably better off always editing files in this "src/../public" directory and then "recompiling" instead of updating files directly in the "www/com.sduk.gbpAjax". Otherwise, the next time you recompile, the old "public" files will overwrite the updated "www" files.

What is the GWT command to set up the directory structure

If you are not using the editor Eclipse, follow these instructions. Otherwise, see the "Eclipse Tips" below.

The GWT command to set up the directory structure is "applicationCreator", found in the GWT directory. In our example, move to the directory above which you want to create the new directory (eg. cd ~/clients), then run the command in a Terminal:
~/download/GWT/applicationCreator com.[YourCompany].client.[YourApplicationName]

In our example, we have used the command:
~/download/GWT/applicationCreator com.sduk.client.gbpAjax

Eclipse Tips

Eclipse is a massive editor that handles Java code. It identifies Java syntax errors (for which non-Java programmers should be truly grateful). Its use is relatively instinctive. The following tips may make life much easier in connection with the GWT.

When creating the directory structure (see above), precede the creation of directories with creation of a project.

Move to the directory above which you want to create the new directory (eg. cd ~/clients), then run the command in a Terminal:
~/download/GWT/projectCreator -eclipse [ProjectName]

In our example, we used the command:
~/download/GWT/projectCreator -eclipse gbpAjax

Then set up the directories, using the option "-eclipse [ProjectName]" in the command described in the previous section as follows:
~/download/GWT/applicationCreator -eclipse gbpAjax com.sduk.client.gbpAjax

When launching eclipse, you are asked for the "home" directory. You should select the main clients directory (eg. ~/clients). Then, to open the newly created project file:

In eclispe, select File, Import, (if the "General" line is collapsed, open it up), Existing Projects Into Workspace.

You should then see the newly created project. When you click it, you will see all the newly created files and the full directory structure. You will also see the component GWT files in the "jar" file, which you can look at by double clicking.

You never need to compile a project within Eclipse.

When Eclipse compiles a Java program, it converts the Java code to binary code. When GWT "compiles" Java code, it translates the Java code to html/javascript. Compiling the code within Eclipse is entirely irrelevant to the process.

How do I "compile" the Java code into a web site?

Traditionally, compilers take programming code and convert it to machine based binary. GWT works differently in that it translates the Java code into a combination of html and javascript.

When you use "applicationCreator" as described above, GWT creates two additional executable files. One is "gbpAjax-compile", the other is "gbpAjax-shell". Both files are found in the ~/clients/gbpAjax directory

To "compile" the programs, run:

Once compiled, open the main html file in the output directory (eg. ~/clients/gbpAjax/www/com.sduk.clients/gbpAjax.html) with your browser to see the end product.

However, there is a far sleeker command which, in one command, allows you both to "compile" the programs and then immediately open the main html file in a virtual browser, designed by Google, called "Tomcat". This dual function is effected with the command:

Does GWT handle every browser

GWT produces a single html file which contains and calls a good deal of Javascript. Every time a new page is clicked by the visitors, Javascript updates the single html page in the browser.

Of course, if a browser has Javascript turned off, the GWT will output nothing driven by Javascript. Typically, the browser will display just the text in the html file that was originally in the "public" directory, to which GWT adds its Javascript.

Further, every browser has a slightly different version of Javascript. Google handles five or six different browsers - but not all of them. I have seen successful GWT output on IE7 and Firefox 2. But it failed to display on Konqueror or IE5.

When is GWT suitable for an application

GWT is truly wonderful. Google deserves every bit of the enormous praise and respect it has generated by making this code available to the open source community.

It is invaluable for many "single function" applications, such as a Word Processor or Spreadsheet.

But there are a number of constraints that make GWT unsuitable in a number of instances.

Firstly, I have not been able to integrate GWT with an existing website. You use either GWT or conventional techniques. This is partly because GWT works through a single webpage. If each Java program was capable of defining its own html template for that page alone, rather than having to depend on the single, central html file set out in the "public" directory, it would hugely enhance the applications for which GWT was suited.

Secondly, under present search engine functionality, websites created with GWT will not be included by search engines. I have seen a message from one user that creating a google web site map allows google to incorporate the javascript generated text - but I have not seen it work in practice. I have also seen messages from several users to duplicated the entire site in conventional html, just for search engine purposes. But where an application has no interest in being indexed by the search engines (such as a membership data entry form), then this restriction is irrelevant.

Thirdly, Javascript is not the fastest of systems. Where relatively small changes are being made to a webpage (such as changing an image, or filling a form with orders), the Javascript is so fast that it comes close to the speed of a desktop application. But where there is a large amount of text and images that is being displayed, such as this page, then Javascript will add quite a time delay to the visitor's experience.

Fourthly, GWT is still being developed. The documentation available is wonderful if you know what you are doing, but woeful if not. If you come across problems, do not expect to find much in the way of solutions for the time being. So simple applications are likely to work well. Complex ones may have you tearing your hair out.

Fifthly, GWT pages are generated on "compilation". As far as I am aware, this means you can not decide which page to display depending on the activities of a visitor. For error checking of input from a user, this may not be a problem because GWT provides a far better mechanism of allowing you to highlight errors in the page before submission. But if the error checking is too sophisticated for simple Javascript or if you need to display different pages depending on a user's input (eg. providing different menu and response for a manager to that provided to a sales person), GWT does not seem to be able to handle this. (I have not used GWT enough to know if this is a valid problem, or if the problem is simply that I have not worked out how to do it).