A module in GWT is best described as a set of classes that are bound by a single module configuration file. The module configuration defines what classes are a part of the module, what other modules that the module depends on, as well as rules for deferred binding, resource injection, and everything else that the GWT compiler and shell needs to know about your module.
A module configuration file is located in the GWT project, with an extension of ".gwt.xml". The location on the classpath and the module configuration file name determine the full module name.
Module Name = Java Package + Module File Name (-gwt.xml)
For example, if you have a module configuration file named Demo.gwt.xml, in the java package com.gwtsandbox.demo, the module name would be com.gwtsandbox.demo.Demo.
The module configuration is only used at design and compile-time, it is not used at run-time. This is a common mistake for new GWT developers.
Simple Module Configuration
A simple module configuration must inherit the User module and specify a single entry point. The entry point is the class that implements the EntryPoint interface and acts as the starting point for the application.
From the basic module configuration you can build on it by adding additional elements to inherit additional modules, change the default source path, add servlet mappings, and add deferred binding rules.
Inheriting Modules
If your GWT project needs to reference external GWT modules you must explicitly inherit them in your module configuration. The core GWT libraries are split into several modules, each of which is listed here. You will always need to include the User module, and optionally one or more of the others.
GWT widgets and core utilities
RequestBuilder and associated classes
Internationalization tools and date/number formatting
Tools for using RPC with JavaScript Object Notation
XML parser and associated classes
Source Path
The source path is a relative path name used to override the default location of the client-side Java source destined to be compiled into JavaScript. The source path you specify is appended to the path where the module configuration file resides, and you may specify multiple source paths.
By default the source path is "client". So by way of example, if your GWT module configuration file is located at com.example.MyApp.gwt.xml, then the default path of "client" will dictate that your client-side Java source will be located in the Java package com.example.client.*, as well as all packages below this one.
All source code in the source path(s) must be able to be compiled to JavaScript with the GWT compiler. This implies that only classes from the JRE emulation library and GWT user library be used. For example, you can not include Java servlets or use the java.sql.* classes under this path.
Public Path
The public path is used to store non-Java files that need to be included in the application. This includes HTML files, JavaScript files, images, CSS, and anything else. By default this will be the "public" directory below where the module configuration is stored.
You can override the default by using the <public> tag in the module configuration.
You may specify multiple public paths if required for your project.
Defining GWT-RPC Servlets
You can use the <servlet> tag in the module configuration to define your GWT-RPC servlets.
The path specified should be absolute.
These servlet mappings are for the benefit of hosted-mode use only, and does not imply that these mappings will be carried over to your production environment. For that you would set them up in the deployment descriptor, just as you would with any other servlet.
Resource Injection
You can have external JavaScript and CSS files automatically injected into the hosting web page. By injecting the resources you avoid the need to have the hosting HTML page explicitly include them with %lt;link> and <script> tags. Resources loaded in this way will be loaded prior to the executing of the GWT application.
To inject a resource you can either place the JavaScript or CSS file into the public package of the GWT module (see above), referencing it with a relative path, or reference an external CSS file by using a full URL.
Deferred Binding
In some cases you need to write low-level functionality that differs based on the client browser, or you need to trigger a generator to generate code at compile time. For these functions you use deferred binding. Deferred binding allows you to write code to an interface and have the concrete class determined at compile-time.
For example, you may be familiar with GWT's RPC mechanism. You use the GWT.create() method to return a concrete class that can serialize and send your data to the server.
When this code is compiled the compiler examines the argument passed to the create method, then attempts to match the target class to a set of rules that reside in the module configuration.
Using Generate-With to Trigger Generators
In this case the compiler rule is specified in the module com.google.gwt.user.RemoteService, which is inherited from your module when using GWT-RPC.
This rule states that when the target class of the GWT.create() is assignable to RemoteService, that the generator ServiceInterfaceProxyGenerator is executed. The generator then creates the code and returns the name of the class that should be returned by the create method.
Using Replace-With to Trigger Class Replacement
The other use of deferred binding is to specify a alternate class to be returned by GWT.create() based on available properties. The most common use of this is to use an alternate class depending on the client browser. The property that can be examined to determine this is "user.agent".
For example, the DOM class in GWT is used to perform low-level functions, where the browser implementations can differ. In order to allow for different browsers the following rule can be found in the com.google.gwt.user.DOM module.
In the DOM class the following code is used to "create" the correct implementation of the DOM class.
When the user.agent property is "ie6" the replace-with rule specified above will return a DOM implementation that is specifically designed for Internet Explorer.
Generate-With and Replace-With Expressions
The following expression tags can be used within generate-with and replace-with tags. When any of the expression tags within the rule returns a true value, the code generation or class replacement is performed.
Returns true when the value of the property matches the specified value. For details on setting properties, see the Setting Properties section.
The target class is tested to see if it can be assigned to the specified assignable type.
Similar to when-type-assignable, except that the class must be an exact match.
Use these expression tags to group other expression tags. The <all> tag implies that all of the tags contained within it must be true. The <any> tag requires only one of the containing expressions to be true. The <none> tag requires that all contained expression tags return false.
Setting Properties
Property names and their possible values can be defined in the module configuration.
Creates a new property and comma separated list of the possible values. For example, you could use the following to define a view property that could be used to define three unique view types for the application.
Extends the possible values for a property that has already been defined.
Sets the value of a defined property. The value must be one of the possible values as defined by the <define-property> tag or one of the extended values as defined by the <extended-property> tag.
Property values can be set at run-time by supplying a property provider. The contents of the <property-provider> tag is a block of JavaScript that returns the property value. The JavaScript code must be placed in a CDATA block to avoid parsing errors.
The JavaScript block can utilize the __gwt_getMetaProperty() method to get the value of GWT property defined in a <meta> tag in the HTML page, and can use __gwt_isKnownPropertyValue() to test that it is an allowed value. Here's an example of using the HTML <meta> tag to set the view as "extended".
