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:

Package	Purpose
com/example/app	Root project package. This package contains all the module files. No code can be placed in the root project package.
com/example/app/client	Sub-package containing all the client-side source code.
com/example/app/server	Sub-package containing all the server-side source code
com/example/app/public	Static resources

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.

Configuring a module

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

GWT descriptor file element	Purpose
<inherits name=”logical-module-name“/>	Inherits all the settings from the specified module. There is no limit to the number of modules that can be inherited.
<entry-point class=”classname“/>	Specifies an entry point class. There is no limit to the number of entry point classes that can be added. The onModuleLoad() for each of the entry point classes will be called one after the other in the in which they are listed here.
<source path=”path“/>	Adds packages to the source path by combining the package in which the module XML is found with the specified path to a sub-package. Any Java source files appearing in the source path are assumed to be translatable. If no <source> element is defined in a module XML file, the client sub-package is added to the source path by default.
<public path=”path“/>	Adds packages to the public path by combining the package in which the module XML is found with the specified path to identify the root of a public path entry. Any files appearing in the public path will be treated as a publicly-accessible resource. The <public> element supports pattern-based filtering that allows you to control which resources get copied into the output directory during a GWT compile. It follows the same rules as Ant’s FileSet element. If no <public> element is defined in a module XML file, the public sub-package is added to the public path by default.
<servlet path=”url-path” class=”classname“/>	This element loads a servlet mounted at the specified URL path. This allows for convenient RPC testing. The URL path should be absolute and have the form of a directory, e.g. /example/path. Your client code then specifies this URL mapping in a call to ServiceDefTarget.setServiceEntryPoint(String). There is no limit to the number of servlets that can be loaded.
<script src=”js-url“/>	Automatically injects the external JavaScript file located at the location specified. This is a convenient way of automatically associating external JavaScript files with your module.
<stylesheet src=”css-url“/>	Automatically injects the external CSS file located at the location specified. This is a convenient way to automatically attach a CSS file to the HTML Host Page.
<extend-property name=”client-property-name” values=”comma-separated-values“/>	Allows you to extend existing client properties with specified values. There is no limit to the number of values that can be added. Client property values accumulate through inherited modules. This element is particularly useful for specifying locales in internationalization.

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.

Comments and Discussions

If you want to comment on this tutorial, please click here.

Training Services

Want to learn from the best in the business? We have training programs available for BlackBerry development, Android development, rich desktop apps, and UX design. We can give your development team a competitive edge, and make them experts in these technologies. Contact us if you are interesting in learning more about our training services & schedule.

Consulting Services

If you need help building web, mobile, and desktop apps that are all connected to the cloud, we can help. We can empower your business by bringing your ideas to life. Contact us if you have a project you need our help with and we will consider taking you on as a client.

Our expertise: architecture, UX design, graphic design, and implementation services for BlackBerry, Android, GWT, desktop Java, and cloud computing. Our specialties: crafting stunning UXes, LBS, real-time collaboration and syncing between services and web/mobile/desktop apps, location based mobile e-commerce, and location based mobile advertising.

This entry was posted on Tuesday, December 4th, 2007 at 6:16 pm and is filed under GWT. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.