Google Web Toolkit (GWT) is a major step forward in the creation of dynamic Java™Script applications that run in users' Web browsers. Using GWT, developers can design the user interface (UI) and event model using familiar Java techniques while GWT does the hard work of making the code friendly for all the major browsers. Learn the basics of GWT in this first article in a series, including how GWT lets you create an Asynchronous JavaScript + XML (Ajax) application and still write your code in the Java language. Discover how to create and run a small sample GWT application -- a hot new Web 2.0 business called Slicr, which sells pizza online.

GWT makes building a rich Ajax browser client interface even easier than building traditional Java GUI interfaces. As fabulous as GWT is, however, it can't create an entire Web application by itself. You must still have a data store on the server and some kind of framework for converting that data into Java objects that GWT can pass from the server to its client. In this series of articles, you'll use Apache Derby, a 100% pure Java database that you can embed in the same Java Virtual Machine (JVM) as the rest of your server-side code.

The first article in this series focuses on GWT. Here you'll learn how to set up GWT and create a simple client interface that responds to user actions. Future articles will show you how to set up the Derby database and connect the GWT front end to the Derby-based back end. Finally, you'll learn how to deploy your system outside of your development environment.

Check out the Ajax resource center, your one-stop shop for information on the Ajax programming model, including articles and tutorials, discussion forums, blogs, wikis, events, and news. If it's happening, it's covered here.

What is Google Web Toolkit?

With GWT, you can develop Ajax applications in the Java programming language. The hallmark of an Ajax application is a rich, interactive environment more often associated with traditional UI applications. Figure 1 shows a sample GWT interface that mimics a desktop e-mail application. This demo is visible at the GWT Web site.

GWT's most unique feature is that you can create your Ajax application and still write your code in the Java language. You can use your favorite Java integrated development environment (IDE) and, even better, you can debug your client in that Java IDE. You can communicate between the client and server using Java objects, and it's all much lighter weight in the client than a Java applet would be.

At base, GWT is a compiler. It converts the Java code you write into JavaScript code that is then inserted into the HTML page and used to run the client side of your application. This functionality frees you from the details of supporting JavaScript code on multiple browsers, allowing you to focus on the interface and interaction of your program.

Of course, if the compiler were the only thing GWT had to offer, that wouldn't be very exciting. Luckily, there's more. With GWT, the compiler is just a mechanism for delivering an entire client/server application architecture. The features include:

• A set of standard UI widgets that look good, are flexible, and are already tuned to work in all the major browsers (including Safari and Opera).
• An event mechanism for catching and responding to events completely on the client side.
• A framework for managing the asynchronous calls between your Web application and the server.
• A mechanism for creating stateful browser history so that your Ajax application doesn't mess with expected Back button behavior.
• A test framework for using JUnit to write unit tests for your client application.

This series will examine many of these features. But let's start with downloading and installing GWT.

Acquire GWT

As of this writing, the current version of GWT is version 1.2. (See Resources at the end of this article for links to the download site.) GWT is fully supported under Microsoft® Windows® XP, Windows 2000, Linux® systems that run GTK+ 2.2.1 or later, and Mac OS X.

Your download is a compressed file. Extract it, and then place the resulting directory somewhere convenient. The details of the distribution vary slightly among the versions, but the basic elements are:

• Three .jar files: The one that contains the user classes that you'll need in your project classpath is called gwt-user.jar, while the one that contains the bulk of the compiler code is called either gwt-dev-windows.jar or gwt-dev-linux.jar. The third file, gwt-servlet.jar, is used in deployment.
• Three command-line utilities: applicationCreator, junitCreator, and projectCreator. (On Windows, they have a .cmd suffix.) More about these in a moment.
• A directory of sample code.

As you use GWT, some other files are placed in the GWT home directory to manage your temporary files.

Create a project

Now that everything is downloaded, your first order of business is to create a project. You're going to be building an online site for a hot new Web 2.0 business called Slicr, which sells pizza online. The exact details of how to set up your GWT project differ depending on whether you plan to use an IDE. For your purposes, you'll be using Eclipse because it's free and also directly supported by the GWT command-line utilities.

Start by using those command-line utilities to create your Eclipse project:

1. Create a new directory called slicr in any convenient place on your hard drive.
2. Open a command prompt in the new slicr directory.
3. Type the following command (you'll need to convert the slashes and whatnot to conform to your operating system choice):

This command creates the minimum needed for a GWT project. The result is a new src subdirectory and new .project and .classpath files.

You can start with just the project as it stands right now, but GWT expects some further structure, which you can set up with the following command:

The -eclipse slicr argument is the name of the Eclipse project and must be the same as what you used in projectCreator. (If it's not, you'll have trouble launching your GWT application from inside Eclipse.) The final argument is the fully qualified class name of what will be your application's main class. You want the lowest-level package to be named client, but beyond that, you're on your own.

This command sets up a few files. The .java file is your main class (and all the parent directories it must create). You get a public directory at the same level as the client directory, and this directory contains a file called Slicr.html. The directory above contains an important file called Slicr.gwt.xml. GWT also creates a Slicr.launch file that Eclipse uses as well as a couple of shell scripts.

Move the project into Eclipse

Almost there. Now, you must get the project into Eclipse.

1. Open Eclipse, and then click File > Import.
2. In the window that appears, expand the General tree, and then select Existing Projects into Workspace.
3. Click Next, and then click Browse to select the Slicr root directory.
4. Select the project, and make sure that the Copy projects into workspace option is not set; you don't want to move the project.

This process places your code into Eclipse, where you can take a good look at it. GWT has created three important files. The first is in the com.ibm.examples package and is called slicr.gwt.xml. This is your XML configuration file. Right now, it looks like Listing 1.

	
<module>
    <inherits name='com.google.gwt.user.User'/>
    <entry-point class='com.ibm.examples.client.Slicr'/>
</module>

In this XML document, you can define the modules for your GWT application. The module is the basic unit of your GWT code and is referenced by the HTML pages that your client uses.

The second file of interest is the Slicr.html file created in the public directory. This is the .html file that is actually sent to the client as the front page of your Web application. The default contains a lot of comments that you really don't need. The guts of the file are shown in Listing 2.

	
<html>
    <head>
        <title>Wrapper HTML for Slicr</title>
        <meta name='gwt:module' 
            content='com.ibm.examples.Slicr'>
    </head>
    <body>
        <script language="javascript" 
            src="gwt.js"></script>
        <iframe id="__gwt_historyFrame" 
            style="width:0;height:0;border:0"></iframe>
        <h1>Slicr</h1>
        <p>
            This is an example of a host page for 
            the Slicr application. 
        </p>
        <table align=center>
            <tr>
                <td id="slot1"></td>
                <td id="slot2"></td>
            </tr>
        </table>
    </body>
</html>

The most important thing to realize about this is that at the end of the day, it's an ordinary .html file. Include any arbitrary HTML you want. There are four elements in this .html file that identify it as a file used by GWT. They are:

• The meta tag: The name attribute must be as shown, and the content attribute is the fully qualified logical name of your module. (It's the package containing the XML module file and then the file name of the XML without the extensions.) This tag associates your HTML page with a specific module. Invoking the page starts the module. (Specifically, all the entry point classes in that module are initialized.)
• The script tag: This tag loads a file called gwt.js, which is one of the files created when you convert your GWT Java code to JavaScript code. Because this file controls the loading of all your client code, including it is rather important to the running of your program.
• The iframe tag: Including this tag exactly -- precisely as written -- allows your Web application to remember history and state, meaning that your GWT application will not disable a user's Back button.
• The td tags: These tags in this particular .html file contain JavaScript identifiers. There's nothing particularly unusual about that, but as you'll see in a moment, GWT uses those identifiers as a place to put elements.

The boilerplate Java startup class

GWT also creates a boilerplate Java startup class for you, as shown in Listing 3.

	
public class Slicr implements EntryPoint {

  public void onModuleLoad() {
    final Button button = new Button("Click me");
    final Label label = new Label();
    button.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {
        if (label.getText().equals(""))
          label.setText("Hello World!");
        else
          label.setText("");
      }
    });
    RootPanel.get("slot1").add(button);
    RootPanel.get("slot2").add(label);
  }
}

Just a couple of things to note about this class right now. The Java class is in your client package, meaning that it's intended to be compiled by GWT into JavaScript code. This places certain limitations on what can be in this file, but for the most part, it's just basic Java 1.4 code. The class that is created implements the interface EntryPoint, which only defines the one method, onModuleLoad(). GWT automatically invokes this method when an HTML page referencing this module is loaded.

This particular EntryPoint is simple. It defines a button and a label in the first two lines. In the last two lines, it associates these widgets with specific elements of the HTML page by using the RootPanel.get() method. The argument to this method is the JavaScript ID of the element as defined in the HTML page.

Between those lines, you define an event listener using an idiom similar to what you would use to bind an event in Swing. In this case, the ClickListener is called when your button is clicked and simply toggles the text in the label widget back and forth.

Document options <tr valign="top"><td width="8"><img alt="" height="1" width="8" src="//www.ibm.com/i/c.gif" /></td><td width="16"><img alt="" width="16" height="16" src="//www.ibm.com/i/c.gif" /></td><td class="small" width="122"><p><span class="ast">Document options requiring JavaScript are not displayed</span></p></td></tr> Print this page E-mail this page Rate this page Help us improve this content

Level: Intermediate

Noel Rappin ( This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ), Senior Software Engineer, Motorola, Inc.

05 Dec 2006

Google Web Toolkit (GWT) is a major step forward in the creation of dynamic Java™Script applications that run in users' Web browsers. Using GWT, developers can design the user interface (UI) and event model using familiar Java techniques while GWT does the hard work of making the code friendly for all the major browsers. Learn the basics of GWT in this first article in a series, including how GWT lets you create an Asynchronous JavaScript + XML (Ajax) application and still write your code in the Java language. Discover how to create and run a small sample GWT application -- a hot new Web 2.0 business called Slicr, which sells pizza online.

GWT makes building a rich Ajax browser client interface even easier than building traditional Java GUI interfaces. As fabulous as GWT is, however, it can't create an entire Web application by itself. You must still have a data store on the server and some kind of framework for converting that data into Java objects that GWT can pass from the server to its client. In this series of articles, you'll use Apache Derby, a 100% pure Java database that you can embed in the same Java Virtual Machine (JVM) as the rest of your server-side code.

The first article in this series focuses on GWT. Here you'll learn how to set up GWT and create a simple client interface that responds to user actions. Future articles will show you how to set up the Derby database and connect the GWT front end to the Derby-based back end. Finally, you'll learn how to deploy your system outside of your development environment.

Check out the Ajax resource center, your one-stop shop for information on the Ajax programming model, including articles and tutorials, discussion forums, blogs, wikis, events, and news. If it's happening, it's covered here.

What is Google Web Toolkit?

With GWT, you can develop Ajax applications in the Java programming language. The hallmark of an Ajax application is a rich, interactive environment more often associated with traditional UI applications. Figure 1 shows a sample GWT interface that mimics a desktop e-mail application. This demo is visible at the GWT Web site.

GWT's most unique feature is that you can create your Ajax application and still write your code in the Java language. You can use your favorite Java integrated development environment (IDE) and, even better, you can debug your client in that Java IDE. You can communicate between the client and server using Java objects, and it's all much lighter weight in the client than a Java applet would be.

At base, GWT is a compiler. It converts the Java code you write into JavaScript code that is then inserted into the HTML page and used to run the client side of your application. This functionality frees you from the details of supporting JavaScript code on multiple browsers, allowing you to focus on the interface and interaction of your program.

Of course, if the compiler were the only thing GWT had to offer, that wouldn't be very exciting. Luckily, there's more. With GWT, the compiler is just a mechanism for delivering an entire client/server application architecture. The features include:

• A set of standard UI widgets that look good, are flexible, and are already tuned to work in all the major browsers (including Safari and Opera).
• An event mechanism for catching and responding to events completely on the client side.
• A framework for managing the asynchronous calls between your Web application and the server.
• A mechanism for creating stateful browser history so that your Ajax application doesn't mess with expected Back button behavior.
• A test framework for using JUnit to write unit tests for your client application.

This series will examine many of these features. But let's start with downloading and installing GWT.

Acquire GWT

As of this writing, the current version of GWT is version 1.2. (See Resources at the end of this article for links to the download site.) GWT is fully supported under Microsoft® Windows® XP, Windows 2000, Linux® systems that run GTK+ 2.2.1 or later, and Mac OS X.

Your download is a compressed file. Extract it, and then place the resulting directory somewhere convenient. The details of the distribution vary slightly among the versions, but the basic elements are:

• Three .jar files: The one that contains the user classes that you'll need in your project classpath is called gwt-user.jar, while the one that contains the bulk of the compiler code is called either gwt-dev-windows.jar or gwt-dev-linux.jar. The third file, gwt-servlet.jar, is used in deployment.
• Three command-line utilities: applicationCreator, junitCreator, and projectCreator. (On Windows, they have a .cmd suffix.) More about these in a moment.
• A directory of sample code.

As you use GWT, some other files are placed in the GWT home directory to manage your temporary files.

Create a project

Now that everything is downloaded, your first order of business is to create a project. You're going to be building an online site for a hot new Web 2.0 business called Slicr, which sells pizza online. The exact details of how to set up your GWT project differ depending on whether you plan to use an IDE. For your purposes, you'll be using Eclipse because it's free and also directly supported by the GWT command-line utilities.

Start by using those command-line utilities to create your Eclipse project:

1. Create a new directory called slicr in any convenient place on your hard drive.
2. Open a command prompt in the new slicr directory.
3. Type the following command (you'll need to convert the slashes and whatnot to conform to your operating system choice):

This command creates the minimum needed for a GWT project. The result is a new src subdirectory and new .project and .classpath files.

You can start with just the project as it stands right now, but GWT expects some further structure, which you can set up with the following command:

The -eclipse slicr argument is the name of the Eclipse project and must be the same as what you used in projectCreator. (If it's not, you'll have trouble launching your GWT application from inside Eclipse.) The final argument is the fully qualified class name of what will be your application's main class. You want the lowest-level package to be named client, but beyond that, you're on your own.

This command sets up a few files. The .java file is your main class (and all the parent directories it must create). You get a public directory at the same level as the client directory, and this directory contains a file called Slicr.html. The directory above contains an important file called Slicr.gwt.xml. GWT also creates a Slicr.launch file that Eclipse uses as well as a couple of shell scripts.

Back to top

Move the project into Eclipse

Almost there. Now, you must get the project into Eclipse.

1. Open Eclipse, and then click File > Import.
2. In the window that appears, expand the General tree, and then select Existing Projects into Workspace.
3. Click Next, and then click Browse to select the Slicr root directory.
4. Select the project, and make sure that the Copy projects into workspace option is not set; you don't want to move the project.

This process places your code into Eclipse, where you can take a good look at it. GWT has created three important files. The first is in the com.ibm.examples package and is called slicr.gwt.xml. This is your XML configuration file. Right now, it looks like Listing 1.

<module>
    <inherits name='com.google.gwt.user.User'/>
    <entry-point class='com.ibm.examples.client.Slicr'/>
</module>

In this XML document, you can define the modules for your GWT application. The module is the basic unit of your GWT code and is referenced by the HTML pages that your client uses.

The second file of interest is the Slicr.html file created in the public directory. This is the .html file that is actually sent to the client as the front page of your Web application. The default contains a lot of comments that you really don't need. The guts of the file are shown in Listing 2.

<html>
    <head>
        <title>Wrapper HTML for Slicr</title>
        <meta name='gwt:module' 
            content='com.ibm.examples.Slicr'>
    </head>
    <body>
        <script language="javascript" 
            src="gwt.js"></script>
        <iframe id="__gwt_historyFrame" 
            style="width:0;height:0;border:0"></iframe>
        <h1>Slicr</h1>
        <p>
            This is an example of a host page for 
            the Slicr application. 
        </p>
        <table align=center>
            <tr>
                <td id="slot1"></td>
                <td id="slot2"></td>
            </tr>
        </table>
    </body>
</html>

The most important thing to realize about this is that at the end of the day, it's an ordinary .html file. Include any arbitrary HTML you want. There are four elements in this .html file that identify it as a file used by GWT. They are:

• The meta tag: The name attribute must be as shown, and the content attribute is the fully qualified logical name of your module. (It's the package containing the XML module file and then the file name of the XML without the extensions.) This tag associates your HTML page with a specific module. Invoking the page starts the module. (Specifically, all the entry point classes in that module are initialized.)
• The script tag: This tag loads a file called gwt.js, which is one of the files created when you convert your GWT Java code to JavaScript code. Because this file controls the loading of all your client code, including it is rather important to the running of your program.
• The iframe tag: Including this tag exactly -- precisely as written -- allows your Web application to remember history and state, meaning that your GWT application will not disable a user's Back button.
• The td tags: These tags in this particular .html file contain JavaScript identifiers. There's nothing particularly unusual about that, but as you'll see in a moment, GWT uses those identifiers as a place to put elements.

The boilerplate Java startup class

GWT also creates a boilerplate Java startup class for you, as shown in Listing 3.

public class Slicr implements EntryPoint {

  public void onModuleLoad() {
    final Button button = new Button("Click me");
    final Label label = new Label();
    button.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {
        if (label.getText().equals(""))
          label.setText("Hello World!");
        else
          label.setText("");
      }
    });
    RootPanel.get("slot1").add(button);
    RootPanel.get("slot2").add(label);
  }
}

Just a couple of things to note about this class right now. The Java class is in your client package, meaning that it's intended to be compiled by GWT into JavaScript code. This places certain limitations on what can be in this file, but for the most part, it's just basic Java 1.4 code. The class that is created implements the interface EntryPoint, which only defines the one method, onModuleLoad(). GWT automatically invokes this method when an HTML page referencing this module is loaded.

This particular EntryPoint is simple. It defines a button and a label in the first two lines. In the last two lines, it associates these widgets with specific elements of the HTML page by using the RootPanel.get() method. The argument to this method is the JavaScript ID of the element as defined in the HTML page.

Between those lines, you define an event listener using an idiom similar to what you would use to bind an event in Swing. In this case, the ClickListener is called when your button is clicked and simply toggles the text in the label widget back and forth.

Back to top

Run your GWT program

Now you can try to run the sample program that GWT has created. There are two different ways to run a GWT program: Web mode and hosted mode. Web mode is the full deployment mode; it's what you would use after you compile your GWT program to JavaScript code.

You use hosted mode during development; it's an emulator with which you can simulate both client and server code at once, dramatically simplifying deployment while you are developing. (Hosted mode doesn't currently work in Mac OS X.) If you're using an IDE with a debugger, you can run your GWT program in hosted mode under the debugger, which allows you to set breakpoints and variable watches even on the client part of your code that is going to be compiled into JavaScript code. This is, of course, very cool and really useful. As you work in GWT, you'll be spending a lot of time in hosted mode.

You can invoke hosted mode in any of several ways. The applicationCreator script that you ran earlier created a Slicr-shell script that you can invoke from the command line to start hosted mode. Earlier in the article, you saw how to import your GWT project into Eclipse. From your Eclipse project, you can choose either Debug or Run from the Run menu or the toolbar. In the window that appears, click Java Application to see the Slicr option. This option is made possible by a Slicr.launch file that GWT created and that you imported into Eclipse with the rest of the project. The launch file describes the classpath and start class for Eclipse. Of course, after you run the launcher once, it will be the default when you click the toolbar button. Figure 2 shows what that window looks like in practice.

When you run in hosted mode, two windows come up. (Note that it takes a minute or so for the hosted mode setup to initialize, especially when run for the first time.) The first window, shown in Figure 3, is named Google Web Toolkit Development Shell / Port 8888. This window contains error and log messages from GWT. Using the toolbar, you can open a new hosted browser as well as expand, contract, and clear your on-screen log.

The second window, shown in Figure 4 is the simulated browser. As you can see, it contains the static HTML from your slicr.html page as well as the button widget created in your Slicr.java EntryPoint class. Clicking the button toggles the label. If you've done something wrong in the setup steps, you won't see this window; instead, you'll get an error message in the shell. Verify that all your names are correct. (In particular, look in the .launch file, and verify that it specifies the correct project directory.)

Set up a simple client

For this article, you focus on getting widgets on the screen and a bit of interactivity. You'll end up with the screen shown in Figure 5, which can charitably be described as plain but functional.