Debugging in Hosted Mode

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.

Launching an application in hosted mode

To launch a hosted mode session, from the command line run the <module>-shell script generated by applicationCreator. For a full list of command-line parameters, see Hosted Mode Shell Script.

Tip: If you are using Eclipse, you can also create a launch configuration file when creating a new project with applicationCreator by using the -eclipse flag.

If you didn't use applicationCreator to create an application-specific hosted mode shell script, you can manually run the main class in com.google.gwt.dev.GWTShell found (depending on your OS) in gwt-dev-windows.jar, gwt-dev-linux.jar, or gwt-dev-mac.jar.

Important: If you are not using the generated <module>-shell script, be aware that in hosted mode, the GWT development shell 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 GWT Development Shell

First the shell script creates a Development Shell window. The window is used to capture debugging logs and exceptions from the Hosted browser.

Serving the application

The first message logged to the Development Shell is about starting an HTTP session. By default, the development shell runs a Tomcat instance to serve your host page and host server-side Java functionality.

You can disable this internal server by passing the -noserver option to hosted mode and replace it with another web server or servlet container. See How do I use my own server in hosted mode instead of GWT's built-in Tomcat instance?

The Hosted browser

The Development Shell is the launching point for a hosted mode browsing session. 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.

Refreshing hosted mode

You do not need to restart hosted mode after modifying your source code. Instead, leave the application running in hosted mode, make and 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 loaded in the browser. Refreshing the Hosted browser is much faster than closing and restarting the application for every change.

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.

Generating debug messages in hosted mode: GWT.log()

Debugging messages are displayed within the Development Shell window. Some of these messages are from the GWT toolkit. 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 ClickListener results in a debug message displaying on the Development Shell window whenever the user clicks the button.

   import com.google.gwt.core.client.GWT;

   ...

   button.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {
        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 Development Shell window. The Development Shell highlights the exception 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.

Enabling internal GWT debug messages

The Development Shell window can display more verbose debugging 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.

For a full list of command-line parameters, see Hosted Mode Shell script.

Using an IDE in Hosted Mode

When using an IDE such as Eclipse, JBuilder, or IntelliJ, it is possible 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 GWT Basics tutorial, Debug in hosted mode.

See Also

• Tutorial: GWT Basics: Debug in Hosted Mode