Screaming Penguin - Source Does Matter

The GWTShell -noserver option has caused some confusion on the GWT forums. This option is intended to allow you to run an external Java servlet container instance (be it Tomcat or anything else) while doing development and using the GWTShell with "Hosted Mode."

Getting this option to work, despite any initial confusion, can be very helpful. For example, if you are working with an external container, you can setup DataSources, Security Realms, Servlet Filters, and anything else your container provides, such as container managed resources (EJBs, JMS queues) - and have it all there in Hosted Mode.

Before I get to the heart of the matter though, and outline a working -noserver setup, I should first mention that this approach is not the only way to work with server resources in hosted mode. You can also "munge" the provided Tomcat instance, if you need simpler resources such as servlets and filters, and have that work in Hosted Mode too. The easiest way to do that, is to let the GWT-Maven Maven plugin handle it. (See the docs there, for details on that approach - and note the maven plugin *also* has a google.webtoolkit.noserver property.)

So on to the -noserver information. Let's do this in a step by step fashion, with a simple app that has no RPC code, first. For our example purposes we will call this GWT module "com.package.Module."

1. Get your app to work in normal hosted mode. Use ApplicationCreator to create the scaffolding for your app, and then launch the shell using the -shell script provided, make sure things work as expected.

$GWT_HOME/applicationCreator com.mypackage.client.Module
Module-shell{.cmd/.sh}

Verify things work, then exit the shell.

2. Setup a container context for use with your app. This of course is container specific, for example we will use Tomcat 6.0.x (and assume it is running on localhost:8080).

• Create a "$CATALINA_HOME/webapps/com.mypackage.Module" directory.
• Create a test "index.html" file in that same location (whatever in it, just "Test" is fine, plain HTML).
• Restart Tomcat, browse to localhost:8080/com.package.Module/ and ensure there are no errors (you can load the test plain HTML page).

3. Compile your application with the GWTCompiler. You can use the provided -compile script (if you used ApplicationCreator) or the "compile/browse" button in the shell to accomplish this. The default output location of your files will be $PROJECT/www.

4. Move a minimum of FOUR files to your container hosted webapp location. Copy the host page, cache.html, hosted.html and gwt.js files into the external container document root for your webapp ($CATALINA_HOME/webapps/com.package.Module). These files are created by the GWTCompiler, as shown in the previous step - the default location to find them will be $PROJECT/www.

• Module.html (host page)
• com.package.Module.nocache.html (application nocache script for bootstrapping)
• hosted.html (core GWT - hosted mode hook)
• gwt.js (core GWT - non app specific - js script)

Any other public path "static" content that you have, should also be placed in the external container location. When using -noserver, the shell is designed to look for static content on the remote server. (Whereas when not using noserver, the shell will look for such content on the classpath.)

5. Edit the script or tool you use to start the shell to include the -noserver option and the port for your external container. For example you can edit the default ApplicationCreator provided Module-shell script, or you can use something such as GWT-Maven, or the following (which is Mac specific, but easily edited/understood for other platforms):

#!/bin/sh
ENTRY_POINT=com.mypackage.Module
HOST_PAGE=Module.html
APPDIR=`dirname $0`;
CPGWT=$APPDIR/src
CPGWT=$CPGWT:$GWT_HOME/gwt-user.jar
CPGWT=$CPGWT:$GWT_HOME/gwt-dev-mac.jar  
java -XstartOnFirstThread -cp $CPGWT com.google.gwt.dev.GWTShell -logLevel 
/DEBUG -noserver -port 8080 "$@" $ENTRY_POINT/$HOST_PAGE

6. Launch the shell and you should be running against the external container instance. With this setup you can edit src CLIENT files, and then refresh and things will be updated, as expected, even though you are running against the external server (the shell uses the container to boot things, and of course for server side resources, but client java code is executed directly - not translated to Javascript - while in the shell).

Try it, edit $PROJECT/src/com/mypackage/client/Module.java, and something simple such as a, Panel, a TextField and a response Label so that when the user enters input and clicks the button that input is echoed back:

package com.mypackage.client;
import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.user.client.ui.Button;
import com.google.gwt.user.client.ui.ClickListener;
import com.google.gwt.user.client.ui.Label;
import com.google.gwt.user.client.ui.HTML;
import com.google.gwt.user.client.ui.RootPanel;
import com.google.gwt.user.client.ui.VerticalPanel;
import com.google.gwt.user.client.ui.TextBox;
import com.google.gwt.user.client.ui.Widget;

public class Module implements EntryPoint {

  public void onModuleLoad() {
   
    final VerticalPanel panel = new VerticalPanel();
    final Label inputLabel = 
        new Label("Enter something clever so GWT can echo it:");
    final Label responseLabel = new Label();
    final TextBox input = new TextBox();
    final Button button = new Button("Submit");

    panel.add(inputLabel);
    panel.add(input);
    panel.add(button);
    panel.add(new HTML("<br /><br />"));
    panel.add(responseLabel);
    
    button.addClickListener(new ClickListener() {
      public void onClick(Widget sender) {  
	  responseLabel.setText(input.getText());
      }
    });

    RootPanel.get().add(panel);
  }
}

Then hit "refresh" in the Hosted Mode browser, voila! Without restarting the shell, or doing anything other than editing the source file and refreshing the browser, the code is updated and the external container, because of noserver, is doing the hosting.

Click to enlarge.

DONE!

With an example working, and the minimum required to use -noserver now understood, you can really make this configuration useful by placing server side resources, as you need them, in your external server instance.

This can include GWT RPC RemoteServiceServlets, other servlets, filters, data sources, or anything else you need the container to handle. One thing to note with GWT service servlets is that you will have to create a WEB-INF/web.xml deployment descriptor for your external instance, and populate it as required (with specific servlet entries for each servlet, GWT related or not, as you would with any standard container context), in addition you will need to include any required dependencies in WEB-INF/lib (or on the containers classpath elsewhere, again, standard stuff now that you are dealing with an external container).

There is also some GWT documentation on this in the GWT FAQ: http://code.google.com/support/bin/answer.py?answer=55200&topic=10454.

And - in case it helps - I have compiled some other GWT resources, including tooling parameters JavaDocs, and notable third party projects: http://www.screaming-penguin.com/GWTResources.