Please make sure you read our Introduction to GWT before reading this tutorial.
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.
|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|
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
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.
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.|
|<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
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.
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.