For the past eight(8) years Schalk Neethling has been working as a freelance developer under the pseudo of Volume4 and is now the president of Overt Strategy Consulting. During this period he has completed over 300 projects ranging from full web application development to complete branding. As president and lead developer of Overt Strategy Consulting, Schalk Neethling and his team has released a 100% Java standards based content management system called AlliedBridge and business document exchange and review system, called Doc-Central. Schalk Neethling is also actively involved on a daily basis in the open source, web standards and accessibility areas and is a current active member of the Web Standards Group. Schalk is also the co-founder and president of the non-profit The South Web Standards and Accessibility Group, which aims to actively educate and raise awareness of web standards and accessibility to both the developer society as well as business large and small. Schalk also has a long relationship with DZone and is currently zone leader for both the web builder, css.dzone.com, as well as the .NET zone, dotnet.dzone.com, and you can find a lot of his writing there as well as on his blog located at schalkneethling.alliedbridge.com. Schalk is constantly expanding on his knowledge of various aspects of technology and loves to stay in touch with the latest happenings. For Schalk web development and the internet is not just a job, it is a love, a passion and a life style. Schalk has posted 173 posts at DZone. View Full User Profile

GWT Basic Project Structure And Components

07.14.2008
| 25392 views |
  • submit to reddit

The core of every GWT project is the project layout and the basic components required—host pages, entry points, and modules. To begin a GWT project, you need to create the default layout and generate the initial files. The easiest way to do this is to use the provided ApplicationCreator tool.

Generating a project

ApplicationCreator is provided by GWT to create the default starting points and layout for a GWT project. ApplicationCreator, like the GWT shell, supports several command-line parameters, which are listed in table 1.

ApplicationCreator [-eclipse projectName] [-out dir] [-overwrite] [-ignore] className

Table 1 ApplicationCreator command-line parameters

Parameter Description
-eclipse Creates a debug launch configuration for the named eclipse project
-out The directory to which output files will be written (defaults to the current directory)
-overwrite Overwrites any existing files
-ignore Ignores any existing files; does not overwrite
className The fully qualified name of the application class to be created

To stub out an example calculator project, we’ll use ApplicationCreator based on a relative GWT_HOME path, and a className of com.manning.gwtip.calculator.client.Calculator, as follows:

mkdir [PROJECT_HOME]
cd [PROJECT_HOME]
[GWT_HOME]/applicationCreator com.manning.gwtip.calculator.client.Calculator

GWT_HOME

It is recommended that you establish GWT_HOME as an environment variable referring to the filesystem location where you have unpacked GWT. Additionally, you may want to add GWT_HOME to your PATH for further convenience. We use GWT_HOME when referencing the location where GWT is installed and PROJECT_HOME to refer to the location of the current project.

PATH SEPARATORS

For convenience, when referring to filesystem paths, we'll use forward slashes, which work for two-thirds of supported GWT platforms. If you are using Windows, please adjust the path separators to use backward slashes. Running ApplicationCreator as described creates the default src directory structure and the starting-point GWT file resources.

The standard directory structure

Even though it's quite simple, the GWT layout is very important because the toolkit can operate in keeping with a Convention over Configuration design approach. As we’ll see, several parts of the GWT compilation process make assumptions about the default layout. Because of this, not everything has to be explicitly defined in every instance (which cuts down on the amount of configuration required). Taking a look at the output of the ApplicationCreator script execution, you will see a specific structure and related contents, as shown in listing 1. This represents the default configuration for a GWT project.

Listing 1 ApplicationCreator output, showing the default GWT project structure:

src
src/com
src/com/manning
src/com/manning/gwtip
src/com/manning/gwtip/calculator
src/com/manning/gwtip/calculator/Calculator.gwt.xml
src/com/manning/gwtip/calculator/client
src/com/manning/gwtip/calculator/client/Calculator.java
src/com/manning/gwtip/calculator/public
src/com/manning/gwtip/calculator/public/Calculator.html
Calculator-shell.sh
Calculator-compile.sh

The package name, com.manning.gwtip.calculator, is represented in the structure as a series of subdirectories in the src tree. This is the standard Java convention, and there are notably separate client and public subdirectories within.

The client directory is intended for resources that will be compiled into JavaScript . Client items are translatable, or serializable, and will ultimately be downloaded to a client browser—these are Java resources in the source. The client package is known in GWT terminology as the source path.

The public directory denotes files that will also be distributed to the client, but that do not require compilation and translation to JavaScript . This typically includes CSS, images, static HTML, and any other such assets that should not be translated, including existing JavaScript. The public package is known as the public path.

Note that our client-side example does not use any server resources, but GWT does include the concept of a server path/package for server-side resources.

Figure 1 illustrates this default GWT project layout.

ApplicationCreator generates the structure and a required set of minimal files for a GWT project. The generated files include the XML configuration module definition, the entry point Java class, and the HTML host page. These are some of the basic GWT project concepts.

Along with the module definition, entry point, and host page, some shortcut scripts have also been created for use with the GWTShell and GWTCompiler tools. These scripts run the shell and compiler for the project. Table 2 lists all of the files created by ApplicationCreator: the basic resources and shortcut scripts needed for a GWT project.

Table 2 ApplicationCreator-generated initial project files that serve as a starting point for GWT applications

File Name Purpose
GWT module file ProjectName.gwt.xml Defines the project configuration
Entry point class ProjectName.java Starting class invoked by the module
Host page ProjectName.html Initial HTML page that loads the module
GWTShell shortcut invoker script ProjectName-shell.sh Invokes GWTShell for the project
GWTCompiler shortcut invoker script ProjectName-compile.sh Invokes GWTCompiler for the project

The starting points ApplicationCreator provides essentially wire up all the moving parts for you and stub out your project. You take it from there and modify these generated files to begin building a GWT application. If the toolkit did not provide these files via ApplicationCreator, getting a project started, at least initially, would be much more time consuming and confusing. Once you are experienced in the GWT ways, you may wind up using other tools to kick off a project: an IDE plugin, a Maven “archetype,” or your own scripts. ApplicationCreator, though, is the helpful default. The contents and structure that ApplicationCreator provides are themselves a working GWT “hello world” example. You get “hello world” for free, out of the box.

"Hello world", however, is not that interesting. The connection of all the moving parts is what is really important; how a host page includes a module, how a module describes project resources, and how an entry point invokes project code. These concepts are applicable to all levels of GWT projects—the basic ones and beyond. Understanding these parts is key to gaining an overall understanding of GWT. Next, we’ll take a closer look at each of these concepts, beginning with the host page.

Host pages

A host page is the initial HTML page that invokes a GWT application. A host page contains a script tag that references a special GWT JavaScript file, Module.nocache.js. This JavaScript file, which the toolkit provides when you compile your project, kicks off the GWT application loading process.

Along with the script reference that loads the project resources, you can also specify several GWT-related tags in the host page. These tag options are not present in the default host page created by ApplicationCreator, but it’s still important to be aware of them. The GWT tags that are supported in a host page are listed in table 3, as a reference.

Table 3 GWT tags supported in host pages

Meta tag Syntax Purpose
gwt:module <meta name="gwt:module" content="_module-name_">
(Legacy, pre GWT 1.4.) Specifies the module to be loaded
gwt:property <meta name="gwt:property" content="_name_=_value_">
Statically defines a deferred binding client property
gwt:onPropertyErrorFn <meta name="gwt:onPropertyErrorFn" content="_fnName_">
Specifies the name of a function to call if a client property is set to an invalid value (meaning that no matching compilation will be found)
gwt:onLoadErrorFn <meta name="gwt:onLoadErrorFn" content="_fnName_">
Specifies the name of a function to call if an exception happens during bootstrapping or if a module throws an exception out of onModuleLoad(); the function should take a message parameter

Thus, a host page includes a script reference that gets the GWT process started and refers to all the required project resources. The required resources for a project are assembled by the GWT compilation process, and are based on the module configuration.

Modules

GWT applications inhabit a challenging environment. This is partly because of the scope of responsibility GWT has elected to take on and partly because of the Internet landscape. Being a rich Internet-based platform and using only the basic built-in browser support for HTML, CSS, and JavaScript makes GWT quite elegant and impressive, but this combination is tough to achieve. Browsers that are “guided” by standards, but that don’t always stick to them, add to the pressure. Couple that environment with an approach that aims to bring static types, code standards, profiling and debugging, inheritance, and reuse to the web tier, and you have a tall order.

To help with this large task, GWT uses modules as configuration and execution units that handle discreet areas of responsibility. Modules enable the GWT compiler to optimize the Java code it gets fed, create variants for all possible situations from a single code base, and make inheritance and property support possible.

One of the most important resources generated by the ApplicationCreator is the Module.gwt.xml module descriptor for your project. This file exists in the top-level directory of your project’s package and provides a means to define resource locations and structure.

In a default generated module file, there are only two elements: and . An element simply includes the configuration for another named GWT module in the current definition, and defines a class that kicks things off and moves from configuration to code. Table 4 provides an overview of the most common GWT module descriptor elements.

Table 4 A summary of the most common elements supported by the GWT module descriptor

Module element Description
<inherits>
Identifies additional GWT modules that should be inherited into the current module
<entry-point>
Specifies which EntryPoint class should be invoked when starting a GWT project
<source>
Identifies where the source code that should be translated into JavaScript by the GWT compiler is located
<public>
Identifies where assets that are not translatable source code, such as images and CSS files, are located
<script>
Injects a script element into a GWT module, ensuring it is present when inherited
<stylesheet>
Injects a stylesheet into a GWT module, ensuring it is present when inherited
<servlet>
Specifies the path to GWT RPC Service Servlet resources
<define-property>
Initially defines properties
<set-property>
Sets property values; for example, it is used in the UserAgent module to define the set of supported browsers
<extend-property>
Specifies property value extensions; often used to specify locale information
<replace-with>
Replaces components at runtime based on a decision process, such as different implementations for different browser versions

The calculator module file is a simple default module file, with the addition of an injected stylesheet via the <stylesheet> tag. By using either the <script> or <stylesheet> tags, you can guarantee that those resources will be available with your module when it’s deployed. The difference between resource injection and simply adding a stylesheet reference, or script, to the HTML on your host page is that the module is in control. If you build libraries with GWT, or share entire projects, the host page is not distributed with your project. Users of your library will, therefore, not be using the same host page, and will not link to the same stylesheet. Script and stylesheet elements in host pages do work, but they are not certain to be present when others use your modules—injected resources are. Modules can bring other resources along with them, if needed.

Though the three lines of configuration in listing 1 may seem very simple, there is a bit more going on than meets the eye. GWT modules understand several default values for important properties. For example, the source path and public path locations are, by default, the client and public packages on the classpath, respectively. Because no other configuration is explicitly specified, our calculator example uses these defaults.

Modules are therefore significant on a number of fronts. In addition to setting configuration and properties, they also provide resources for projects, enable inheritance, give the compiler hints, and play a central role in the bootstrapping process. Once the bootstrap determines the correct permutation of an application, via the nocache script for a particular module, an entry point is invoked.

Entry points

An entry point class, as we have learned, is simply the first project-specific code every GWT application invokes. This is generally where the first browser-based element is accessed, and it’s typically done with the static RootPanel.get() method. The RootPanel is a default container that is inserted directly before the HTML tag. With a reference to this panel, you can then compose your project and insert other elements from there.

The entry point class of our calculator example is a default EntryPoint implementation with the template "hello world" code removed, and a new custom widget added.

With an entry point in place, our calculator project can now go from the HTTP request on the host page, through the configuration provided by the module descriptor, to additional JavaScript code (built from Java) included in the module.

This process is the same for every GWT project. Whether you are building an entire application with multiple module inheritance, or just a single widget in a single module, the bootstrap we have discussed, from configuration to code, is the same.

This article is excerpted from Chapter 1 of GWT in Practice, by Robert Cooper and Charlie Collins, and published in May 2008 by Manning Publications.
Published at DZone with permission of its author, Schalk Neethling.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Steven Baker replied on Mon, 2008/07/14 - 6:31pm

why do these kindof books have such stupid pictures...

Tunde Adeyemi replied on Tue, 2008/07/15 - 5:34am

Very good tutorial. Beginners can get started with this with little fuss. The section on GWT module descriptors was quite informative for me. Thanks.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.