GWT Module
The GWT deployment module generates the server-side and client-side libraries used to support a
GWT RPC API. There is also support for invoking the
GWTCompiler to compile a set a GWT applications that can be included in the generated Enunciate web
application.
The order of the GWT deployment module is 0, as it doesn't depend on any artifacts exported
by any other module.
This documentation is an overview of how to use Enunciate to build your GWT-RPC API and (optional)
associated GWT application. The reader is redirected to the
documentation for the GWT for instructions on how to use GWT.
You may also find the petclinic sample application useful as an illustration. The sample petclinic application
is included with the Enunciate distribution.
Steps
generate
The "generate" step generates all source code for the GWT-RPC API.
compile
During the "compile" step, the GWT module compiles the code that was generated. It is also during the "compile" step that
the GWTCompiler is invoked on any GWT applications that were specified in the configuration.
build
The "build" step assembles the client-side GWT jar.
Configuration
The GWT module is configured by the "gwt" element under the "modules" element of the
enunciate configuration file. The GWT module is disabled by default because of the
added constraints applied to the service endpoints. To enable GWT, be sure to specify
disabled="false" on the "gwt" element.
The "gwt" element supports the following attributes:
- The "rpcModuleName" attribute must be supplied. The RPC module name will also be used to
determine the layout of the created module. The module name must be of the form "com.mycompany.MyModuleName".
In this example, "com.mycompany" will be the module namespace and all client code will be generated into
a package named of the form [module namespace].client (e.g. "com.mycompany.client"). By default, in order to provide
a sensible mapping from service code to GWT client-side code, all service endpoints, faults, and JAXB beans must
exist in a package that matches the module namespace, or a subpackage thereof. Use the "enforceNamespaceConformance"
attribute to loosen this requirement.
- The "enforceNamespaceConformance" attribute allows you to lift the requirement that all classes must exist in a package
that matches the module namespace. If this is set to "false", the classes that do not match the module namespace will
be subpackaged by the client namespace. NOTE: You may not like this because the package mapping might be ugly. For example,
if your module namespace is "com.mycompany" and you have a class "org.othercompany.OtherClass", it will be mapped to a client-side GWT class
named "com.mycompany.client.org.othercompany.OtherClass".
- The "label" attribute is used to determine the name of the client-side artifact files. The default is the Enunciate project label.
- The "clientJarName" attribute specifies the name of the client-side jar file that is to be created.
If no jar name is specified, the name will be calculated from the enunciate label, or a default will
be supplied.
- The "clientJarDownloadable" attribute specifies whether the GWT client-side jar should be included as a
download. Default:
false
.
- The "gwtHome" attribute specifies the filesystem path to the Google Web Toolkit home directory.
- The "gwtCompilerClass" attribute specifies the FQN of the GWTCompiler. Default: "com.google.gwt.dev.GWTCompiler".
- The "enforceNoFieldAccessors" attribute specifies whether to enforce that a field accessor cannot be used for GWT mapping.
Note: whether this option is enabled or disabled, there currently MUST be a getter and setter for each accessor. This option only
disables the compile-time validation check.
- The "useWrappedServices" attribute specifies whether to use wrapped GWT client services. This is an artifact from when GWT 1.4 was supported
and the generic types were unavailable. Default: false
- The "disableCompile" attribute prevents Enunciate from compiling its generated client source files.
The "war" element
The "war" element under the "gwt" element is used to configure the webapp that will host the GWT endpoints and GWT applications. It supports
the following attributes:
- The "gwtSubcontext" attribute is the subcontext at which the gwt endpoints will be mounted. Default: "/gwt/".
- The "gwtAppDir" attribute is the directory in the war to which the gwt applications will be put. The default is the root of the war.
The "facets" element
The "facets" element is applicable to the GWT module to configure which facets are to be included/excluded from the GWT artifacts. For
more information, see API Facets
The "app" element
The GWT module supports the development of GWT AJAX apps. Each app is comprised of a set of GWT modules that will be compiled into JavaScript.
The "app" element supports the folowing attributes:
- The "name" attribute is the name of the GWT app. Each app will be deployed into a subdirectory that matches its name. By default,
the name of the application is the empty string (""). This means that the application will be deployed into the root directory.
- The "srcDir" attribute specifies the source directory for the application. This attribute is required.
- The "javascriptStyle" attribute specified the JavaScript style that is to be applied by the GWTCompiler. Valid values are "OBF", "PRETTY",
and "DETAILED". The default value is "OBF".
Each "app" element may contain an arbitrary number of "module" child elements that specify the modules that are included in the app.
The "module" element supports the following attributes:
- The "name" attribute specifies the name of the module. This is usually of the form "com.mycompany.MyModule" and it always has a corresponding
".gwt.xml" module file.
- The "outputDir" attribute specifies where the compiled module will be placed, relative to the application directory. By default, the
outputDir is the empty string (""), which means the compiled module will be placed at the root of the application directory. Note: as of GWT 1.6,
a new "war" directory structure is supported, along with support to control the directory where the GWT compiler puts the compiled application. Because
of this, the "outputDir" attribute will only be honored if not using GWT 1.6 or above.
- The "shellPage" attribute specifies the (usually HTML) page to open when invoking the shell for this module (used to generate the shell script). By
default, the shell page is the [moduleId].html, where [moduleId] is the (short, unqualified) name of the module.
The "gwtCompileJVMArg" element
The "gwtCompileJVMArg" element is used to specify additional JVM parameters that will be used when invoking GWTCompile. It supports a single
"value" attribute.
The "gwtCompilerArg" element
The "gwtCompilerArg" element is used to specify additional arguments that will be psssed to the GWT compiler. It supports a single
"value" attribute.
Example Configuration
As an example, consider the following configuration:
<enunciate>
  <modules>
    <gwt disabled="false"
        rpcModuleName="com.mycompany.MyGWTRPCModule"
        gwtHome="/home/myusername/tools/gwt-linux-1.5.2">
      <facets>
        ...
      </facets>
      <app srcDir="src/main/mainapp">
        <module name="com.mycompany.apps.main.MyRootModule"/>
        <module name="com.mycompany.apps.main.MyModuleTwo" outputDir="two"/>
      </app>
      <app srcDir="src/main/anotherapp" name="another">
        <module name="com.mycompany.apps.another.AnotherRootModule"/>
        <module name="com.mycompany.apps.another.MyModuleThree" outputDir="three"/>
      </app>
      ...
    </gwt>
  </modules>
</enunciate>
The configuration enables the GWT Enunciate module and will publish the web service endpoints under the module name
"com.mycompany.MyGWTRPCModule".
There are also two GWT applications defined. The first is located at "src/main/mainapp". Since there is
no "name" applied to this application, it will be generated into the root of the applications directory. This
first application has two GWT modules defined, the first named "com.mycompany.apps.main.MyRootModule" and the second
named "com.mycompany.apps.main.MyModuleTwo". "MyRootModule", since it has to output path defined, will be generated
into the root of its application directory (which is the root of the main applications directory). "MyModuleTwo", however,
will be generated into the subdirectory "two".
The second application, rooted at "src/main/anotherapp", is named "another", so it will be generated into the "another"
subdirectory of the main applications directory. It also has two modules, one named "com.mycompany.apps.another.AnotherRootModule",
and another named "com.mycompany.apps.another.MyModuleThree". "AnotherRootModule" will be generated into the root of its application
directory ("another") and "MyModuleThree" will be generated into "another/three".
All modules are defined by their associated ".gwt.xml" module definition files. After the "compile" step of the GWT module, the
main applications directory will look like this:
|--[output of com.mycompany.apps.main.MyRootModule]
|--two
|----[output of com.mycompany.apps.main.MyModuleTwo]
|--another
|----[output of com.mycompany.apps.another.AnotherRootModule]
|----three
|------[output of com.mycompany.apps.another.MyModuleThree]
For a less contrived example, see the "petclinic" sample Enunciate project bundled with the Enunciate distribution.
Artifacts
- The "gwt.client.jar" artifact is the packaged client-side GWT jar.
- The "gwt.client.src.dir" artifact is the directory where the client-side source code is generated.
- The "gwt.server.src.dir" artifact is the directory where the server-side source code is generated.
- The "gwt.app.dir" artifact is the directory to which the GWT AJAX apps are compiled.
- The "[appName].[moduleName].shell" artifact is the GWT shell script used to invoke the gwt shell for the module [moduleName] in app [appName].
Script is different from the alternative in that it assumes a server is already running before invoking the GWTShell.