Anatomy of a GWT Project – Tutorial

Posted by

Introduction

Please make sure you read our Introduction to GWT before reading this tutorial.

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

The first step in writing any GWT application is setting up a GWT Project. This tutorial will introduce you to the ins and outs of GWT projects.

Typical GWT Projects follow a structure that looks very similar to the Java package structure. The default GWT package tries to make it easy to differentiate client-side source code (code that will be translated to JavaScript and executed in a web-browser) from server-side code (code that will be executed on a server as is). A typical GWT package layout will look something like this:

Each GWT project can be made up of one or more GWT Modules.

What is a GWT Module?

According to Google, “A GWT ‘module’ is simply an encapsulation of functionality”. A module bundles together all the configuration needed to use use your code in a GWT project. While a GWT module shares some similarities with a Java package it is not the same thing. GWT modules follow the Java package dotted-path naming convention, e.g. most of the standard GWT modules are located under “com.google.gwt”. The naming convention is where the similarities end. If you want to add new classes, you can’t just add them anywhere.

GWT modules are defined using XML descriptor files ending with the .gwt.xml extension. The concept of a GWT module descriptor is similar to deployment descriptors in Tomcat and other application servers. The contents of the XML descriptor files are use to specify:

  • Inherited modules
  • An entry point application class name (optional)
  • Source Path entries
  • Public Path entries

Inherited Modules

Modules from which settings and code will be inherited.

Entry Point Classes

A module entry point is any class that implements the EntryPoint interface. When a module is loaded, each entry point class listed in the .gwt.xml file is instantiated and its onModuleLoad() method is called. It is possible to create a module with more than one entry point. It is also possible to create a module with no entry points. If you wish to make a re-usable GWT code library, you should package it as a GWT module that contains no entry point classes. This module could then be inherited by other GWT modules.

Source Path

Source Path entries can be used to specify which sub-packages contain translatable source code. Only files found on the source path are candidates to be translated into JavaScript. When modules are inherited by other modules, the source paths are combined so that each module will have access to the translatable source it requires. The client sub-package is included in the source path by default.

Public Path

Public Path entries can be used to specify which sub-packages are public. All the files found on the public path will be copied to the module’s output directory when your application is compiled. When modules are inherited by other modules, the public paths are combined so that each module will have access to the static resources it expects. The public sub-package is included in the public path by default.

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

Configuring a module

The following are all the configuration options that can be specified in a .gwt.xml descriptor file:

Module Package Restrictions

While GWT modules may appear anywhere in your classpath and use Java’s package naming convention, there are restrictions as to where source code can be placed inside of a GWT module. If you want to add some new classes, you can’t just add them anywhere. Java classes must be placed in the client sub-package, in a package that is listed in the source path, or in the server sub-package. The placement of code into these packages is not arbitrary, it is dependent on what you intend to do with your classes.

Client-side code must always be included in either the client sub-package or in a package listed in the source path

Client-side code is code that you expect to be translated into JavaScript and executed in a web-browser. For example, if you create a GWT UI for your application, all the GWT UI classes and the classes they interact with are considered to be client-side code since they must be translated to JavaScript before you can access them through a web-browser. Any code that needs to be translated to JavaScript and executed on the client side must always be included in either the client sub-package or in a package listed in the source path. You also need to ensure that this client-side source code is compatible with Java 1.4.2 or older and only uses classes provided by the GWT JRE Emulation library.

Server-side code must always be included in the server sub-package

Server-side code is code that you expect to be executed on a server computer. This code is executed as is. For example, server side implementations of GWT RPC services, or any other classes that interacts with the GWT RPC services are considered to be server-side code since they execute on a server. Any code that executes on a server as part of a GWT application must always be included in the server sub-package. None of the client-side language restrictions apply to server-side code.

NOTE: If you have classes that you wish to use in both client and server-side code, these classes need to be translated to JavaScript for use in the client. Therefore classes that you wish to use in both client and server-side code should be included in either the client sub-package or in a package listed in the source path. All client-side code language restrictions apply to these classes.

How to setup a GWT Project

Most people will probably use the command line tools that come with GWT to setup their projects. If you use Eclipse, you can use the command line tools to setup an Eclipse project and then import them into Eclipse. There are also plugins for Eclipse that will help to streamline that process. To find out how to use GWT’s built-in tools here.

If you are using IntelliJ IDEA 6 you can download a GWT plugin, and use that to setup your GWT project. IntelliJ IDEA 7 has built-in support for GWT. If you use IDEA 7, you can learn how to setup a GWT Project here.