Let's start with the core principle of GWT development:
The rest of this section introduces hosted mode and web mode and explains how and when to use each.
You will spend most of your development time running your application in hosted mode, which means that you are interacting with your GWT application without it having been translated into JavaScript. Anytime you edit, run, and debug applications from a Java integrated development environment (IDE), you are working in hosted mode. When an application is running in hosted mode, the Java Virtual Machine (JVM) is actually executing the application code as compiled Java bytecode, using GWT plumbing to automate an embedded browser window. This means that the debugging facilities of your IDE are available to debug both your client-side GWT code and any server-side Java code as well. By remaining in this traditional "code-test-debug" cycle, hosted mode is by far the most productive way to develop your application quickly.
To launch a hosted mode session, from the command line run ant hosted, assuming you have an Ant build.xml file generated by webAppCreator.
Tip: If you are using Eclipse, you can instead run the <app>.launch configuration file created by webAppCreator using the Run or Debug menus.
If you didn't use webAppCreator, you can manually run the main class in com.google.gwt.dev.HostedMode found in gwt-dev-windows.jar, gwt-dev-linux.jar, or gwt-dev-mac.jar, depending on your OS.
Important: If you are not using a generated launch config, be aware that GWT hosted mode looks for modules (and therefore client-side source) using the JVM's classpath. Make sure to add your source directories first in your classpath.
The first window you'll see is the Hosted Mode main window. The window is used to capture debugging logs and exceptions from the hosted browser.
The first message in the log window is about starting an HTTP session. By default, hosted mode runs an internal Jetty instance to serve your web application. This embedded Jetty instance serves directly out of your project's war directory.
You can disable this internal server by passing the -noserver option to hosted mode and instead run your own external server. See FAQ "How do I use my own server in hosted mode instead of GWT's built-in server?"
Hosted browsers are typically opened automatically via the -startupUrl command line option. You can also open a new hosted browser from the Hosted Mode main window. The hosted browser displays your application and gives you the standard controls of a web browser, plus a Compile/Browse button to compile the client-side code to JavaScript and run the application in web mode.
You do not need to restart hosted mode after modifying your source code. Instead, with Hosted Mode still running, edit client code or resources, save your changes, then click the Refresh button in the hosted browser. On Refresh, your code is recompiled with the changes and the new version is loaded into the browser. Refreshing the hosted browser is much faster than closing and restarting Hosted Mode.
You might notice that sometimes your changes take effect even if you do not refresh hosted mode. This behavior is a result of the way hosted mode interacts with the compiled code, but it is not always reliable. Specifically, it only happens when you make minor changes to existing functions. To ensure your changes are included, make it a habit to always refresh the hosted mode browser after making changes.
Similarly, the Restart Server button in the Hosted Mode main window allows you to restart the embedded Jetty server without having to close and restart Hosted Mode. This is useful when you have made configuration or code changes to your server side code. All server side classes will be reloaded from scratch with fresh code for your war/WEB-INF/classes and war/WEB-INF/lib folders. If you are getting an IncompatibleRemoteServiceException in hosted mode while using RPC, try restarting the server and refreshing the client.
Debugging messages are displayed within the Hosted Mode log window. Some of these messages are from GWT. However, you can generate your own debug messages by using calls to GWT.log().
For example, modifying the standard project to emit a debug message inside the ClickHandler results in a debug message displaying on the log window whenever the user clicks the button.
|
import com.google.gwt.core.client.GWT;
...
button.addClickHandler(new ClickHandler() {
public void onClick(ClickEvent event) {
GWT.log("User Pressed a button.", null); // Added debugging message
if (label.getText().equals(""))
label.setText("Hello World!");
else
label.setText("");
}
});
Calls to GWT.log() are intended just for use while debugging your application. They are optimized out in web mode. For example, consider the following change to the onClick() method intended to intentionally trigger an exception:
public void onClick(Widget sender) {
GWT.log("User pressed a button.", null);
Object nullObject = null;
nullObject.toString(); // Should cause NullPointerException
When the hosted application encounters an exception, a message is printed on the log window. The exception is highlighted with a red icon. In this example, when you click on the button in the browser window, a NullPointerException is triggered and the back trace for the exception displays in the status area below the log area. Clicking on the exception message or icon displays the full text of the exception in the message area below.
The log window can display more verbose debugging if you invoke it by specifying the -logLevel command-line argument. Specifying the level of SPAM turns on many messages inside of the GWT engine. These messages are displayed in a hierarchical tree which can be manipulated by clicking on individual lines or by using the Expand All and Collapse All icons in the toolbar.
When using an IDE such as Eclipse, JBuilder, or IntelliJ, it is easy to use the IDE's built-in Java debugger to debug your module. Simply set a breakpoint somewhere inside your code, (such as the onModuleLoad() entry point) where you want the debugger to stop and let you inspect the state of your program. For an example of debugging in hosted mode using the Eclipse IDE, see the Getting Started tutorial, Debugging a GWT Application.
Let's look behind the scenes when you launch your GWT application in hosted mode. To run hosted mode, you start a Java VM using the main class com.google.com.gwt.dev.HostedMode. If you look inside a generated ant build.xml, you'll find something like this:
<target name="hosted" depends="javac" description="Run hosted mode">
<java failonerror="true" fork="true" classname="com.google.gwt.dev.HostedMode">
<classpath>
<pathelement location="src"/>
<path refid="project.class.path"/>
</classpath>
<jvmarg value="-Xmx256M"/>
<arg value="-startupUrl"/>
<arg value="Hello.html"/>
<!-- Additional arguments like -style PRETTY or -logLevel DEBUG -->
<arg value="com.google.gwt.sample.hello.Hello"/>
</java>
</target>
This is similar to running the following command on the command line:
java -Xmx256M -cp "src;war/WEB-INF/classes;\gwt-windows-1.6.0\gwt-user.jar;\gwt-windows-1.6.0\gwt-dev-windows.jar" com.google.gwt.dev.HostedMode -startupUrl Hello.html com.google.gwt.sample.hello.Hello
The -startupUrl parameter tells Hosted Mode which URL(s) to launch in the hosted mode browser when it starts up. If the value excludes the domain, the domain is assumed to be localhost. The port is assumed to be the port running the embedded server. In the example above, this address is http://localhost:8888/Hello.html.
The final parameter (the one at the end with no flag preceding it) is the module or set of modules we care about. This value is required in order to correctly initialize the war directory with bootstrap scripts for any GWT modules you may wish to run.
After you have your application working well in hosted mode, you will want to try out your application in your target web browsers; that is, you want to run it in web mode. This is as easy as clicking the Compile/Browse button in the toolbar of the Hosted Mode browser.
After you click the Compile/Browse button, Hosted Mode pauses while the GWT compiler translates your Java source code (plus the source code of the GWT library and any third party libraries) into optimized JavaScript. If the compilation runs into errors, they will be displayed in the log window. After the compilation completes successfully, an external browser window opens displaying your HTML host page and your application. (Or, an existing browser session might display your application in a new tab.)
Running your application in web mode allows you to test your application as it is deployed. If you have a servlet component specified in your web.xml file, your GWT RPC calls will also be served to the browser. You can also take a different browser or a browser running on another machine and point it at the same URL (substitute the hostname or IP address of your workstation for localhost in the URL.)
Running in web mode is a good way to test:
Hosted mode uses a special engine to run your app as a mix of both Java bytecode and native JavaScript. If your code makes many calls back and forth between Java and and JavaScript, your code may seem slower in hosted mode than it will actually be in web mode. This can be particularly true of UI code. On the other hand, intense algorithmic pure Java code will tend to run faster in hosted mode, since the JVM outperforms most JavaScript engines.
If your application displays lots of data or has a large number of widgets, you will want to confirm that performance will be acceptable when the application is finally deployed.
The heart of GWT is a compiler that converts Java source into JavaScript, transforming your working Java application into an equivalent JavaScript application.
The GWT compiler supports the vast majority of the Java language. The GWT runtime library emulates a relevant subset of the Java runtime library. If a JRE class or method is not supported, the compiler will emit an error.
You can run the compiler with the name of the module you want to compile in one of the following manners:
Once compilation completes sucessfully, directories will be created containing the JavaScript implementation of your project. The compiler will create one directory for each module it compiles.
C:\gwt-windows-1.6.0\samples\Hello>ant
Buildfile: build.xml
libs:
javac:
gwtc:
[java] Compiling module com.google.gwt.sample.hello.Hello
[java] Compiling 5 permutations
[java] Permutation compile succeeded
[java] Linking into war
[java] Link succeeded
[java] Compilation succeeded -- 20.313s
build:
BUILD SUCCESSFUL
Total time: 22 seconds
After running the GWT compiler your war directory should look something like this:
C:\gwt-windows-1.6.0\samples\Hello>\bin\find war war war\hello war\hello\18EEC2DA45CB5F0C2050E2539AE61FCE.cache.html war\hello\813B962DC4C22396EA14405DDEF020EE.cache.html war\hello\86DA1DCEF4F40731BE71E7978CD4776A.cache.html war\hello\A37FC20FF4D8F11605B2C4C53AF20B6F.cache.html war\hello\E3C1ABB32E39A126A9194DB727F7742A.cache.html war\hello\14A43CD7E24B0A0136C2B8B20D6DF3C0.cache.png war\hello\548CDF11D6FE9011F3447CA200D7FB7F.cache.png war\hello\9DA92932034707C17CFF15F95086D53F.cache.png war\hello\A7CD51F9E5A7DED5F85AD1D82BA67A8A.cache.png war\hello\B8517E9C2E38AA39AB7C0051564224D3.cache.png war\hello\clear.cache.gif war\hello\hello.nocache.js war\hello\hosted.html war\Hello.html
In the above example, war/hello/hello.nocache.js is the script you would include in a host HTML page to load the Hello application. In this case, the host HTML page is located at war/Hello.html and loads the GWT startup script through the relative URL hello/hello.nocache.js.
You may have noticed in the compilation target in the build.xml file generated by the webAppCreator uses the war output directory as both an input and output source. This doesn't have to be the case, and you can easily configure the war directory as the output directory only, while using other directories as source directory paths by adding build targets to copy static resources from the source to the final output directory. See this FAQ for more details.
The other thing you may have noticed is that there are a number of other files generated along with the GWT compiler output. Of these there are a few that are key to deploying your application.
After running the GWT compiler, you'll find the output in the WAR, or Web Archive, folder with the following structure:
If you've worked with GWT prior to the 1.6 release, the files in the war/hello directory are familiar to you. The only difference is where these files are now generated, and the fact that the host HTML page and CSS files are not in the same directory as the rest of the .cache.html/png files. The path where these files are generated is controlled by the GWT module XML file. These are the key applications files to deploy you GWT application on your web server.
The host HTML page is the first page your clients should visit when they browse to your application and is also where the rest of your application files are loaded from. To load your application, the host HTML page must contain a <script> tag referencing your GWT application bootstrap file (described below). You would typically include a <link> tag referencing your application CSS file as well, unless you inject the stylesheet directly by adding the <stylesheet> tag to your module XML file.
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link type="text/css" rel="stylesheet" href="Hello.css">
<title></title>
</head>
<body>
<script type="text/javascript" language='javascript' src='hello/hello.nocache.js'></script>
<!-- Along with page title and table headers defined -->
</body>
</html>
You may have noticed that one of the generated files is named after your module, followed by a .nocache.js suffix. This is the GWT bootstrap file. Similar to the output subdirectory war/<app_name>, the name of this file is also controlled by the rename-to attribute in your module XML file. This file is responsible for choosing the correct version of your application to load for your client based on their browser and locale, or any other custom selection rule (see Deferred Binding). The various versions of your application compliant to each browser / locale are the <md5>.cache.html application files (discussed below).
The host HTML page references this file so that clients visiting your page first download the bootstrap, and the bootstrap script in turn figures out which browser environment it is running in and determines the appropriate version of your application to load. See the documentation on the bootstrap process for more details.
The <md5>.cache.html files generated in the war/<app_name> directory, along with the bootstrap script, are the most important part of the generated fileset. They represent one version of your application tailored to a specific browser (or locale). These are the application files that the bootstrap script selects after it determines which browser it's running on.
Another generated application file that isn't strictly necessary to deploy your GWT application, but required if you're using GWT RPC and the support for the Serializable interface for types transferred through RPC, is the <md5>.gwt.rpc file. The serialization policy file must be accessible by your RPC RemoteServiceServlet via the ServletContext.getResource() call.
All public resources, such as image files, stylesheets or XML files, can be placed anywhere under the war directory or any subdirectory therein during development. As long as references to these resources in your GWT application code hold when deployed, you can expect your application to work properly in production. In GWT 1.6, the <public> tag is still respected, so you can place public resources in a public directory, as defined in your module XML file, and these resources will be copied into the war/<app_name> folder. However, the best practice would be to place public resources in the war directory and work with them from that location. This complies with the standard Servlet 2.5 API specification, and makes it easier to deploy your application if you're planning to deploy on a servlet container.
If you're using ImageBundles in your application, the generated image bundles are placed in the war/<app_name> directory after compilation. In GWT 2.0, the concept of ImageBundles has been generalized for any static resource. This is called the ClientBundle, and respects the same rules as the ImageBundle.
Among other optimization and performance improvement techniques, GWT also offers the concept of "Perfect Caching", which you can take advantage of if you deploy your application correctly.
You may have noticed that the bootstrap script filename contains a .nocache.js suffix, whereas the rest of the GWT application files contain a .cache.html suffix. These are meant as indicators that you can use to configure your web server to implement perfect caching. The bootstrap script is named after a well-known application name (<app_name>.nocache.js), while the GWT application files all contain md5 sums in their names. Those md5 sums are computed from your GWT codebase at the time of compilation. The bootstrap script contains a lookup table that selects the right <md5>.cache.html file when your client first visits your site and loads up your GWT application. The bootstrap process is explained in greater detail here.
The fact that the application filenames will always change if your codebase changes means that your clients can safely cache these resources and don't need to refetch the GWT application files each time they visit your site. The resource that should never be cached is the bootstrap script, since it contains the logic necessary to lookup the correct application file. If you were to configure these rules on an Apache HTTP server, you might get something like this in your .htaccess config file:
<Files *.nocache.*>
ExpiresDefault "access"
</Files>
<Files *.cache.*>
ExpiresDefault "now plus 1 year"
</Files>
You could also leave out the rule for the .nocache.js bootstrap script, since by default most browsers won't cache resources that don't have cache headers set on the response.