Where is the sample

The easiest way to use the sample is to checkout maven-googlewebtoolkit-sample and then run "maven gwt." This will run the sample in Hosted Mode. (You can also use "maven gwt:war" to create a deployable war file, but keep in mind the included setup creates a context.xml for use with Tomcat 5.0.x, by design, if you use a newer Tomcat, or a different container, you need to change the setup accordingly.)

You can also step through the sample here, without checking it out, and glean a lot of useful info.

What is in the sample

The sample is provided to demonstrate using GWT-Maven version 1.x (maven-googlwebtoolkit-plugin) with an example project. Other projects can be setup in the same manner as the sample to get things rolling (use the sample as a template).

The sample, however, is also more than that. It additionally provides a useful overview of GWT RPC in general with an example of using a DataSource along with GWT RPC, which works in Hosted Mode and when deployed. (It's a valuable reference even if you are not using Maven.)

The sample is a simple GWT web app with a single form element where you enter your name. That entry is then sent to the server via GWT RPC and it is stored in an HSQL database along with a timestamp. Then the results of all the entries (since the server was last started, mem db) are returned to the client and displayed on the page.

This demonstrates configuring the GWT-Maven plugin along with * context.xml * and * web.xml * in order to setup a container managed DataSource and have that setup matter in the "Tomcat Lite" that is used in GWT Hosted Mode. (Notes about using the -noserver option with an external container are also included below.)

Running the sample project using the GWT-Maven plugin

The point of the GWT-Maven (1.x) plugin is to let you easily control the GWTShell, GWTCompiler, create WAR files, and work with your GWT projects.



Dependencies and properties are defined in the Maven POM manner and are therefore automatically available to all of your project anytime you change them (you can re-use your setup easily, and do not have to edit shell scripts with each change). In addition automated builds and continuous integration are of course possible.



The plugin supports several special features with regard to the "Hosted Mode." Primarily you can define project specifc context.xml and web.xml resources, which will matter BOTH in Hosted Mode and when deployed as a WAR. The plugin allows you to invoke the GWTShell and run against your project (DataSources, other Servlets, etc, all available even in Hosted Mode) and also allows you to create a deployable WAR resource in one *single simple step* (maven gwt:war).



In addition the plugin also easily supports the -noserver option if you wish to use an external container instance (See the -noserver configuration page).



In order to use the maven-googlewebtoolkit-sample project you first need to have the maven-googlwebtoolkit-plugin installed (along with of course Maven itself, Java, so on).



Then you also will need to setup a project that mirrors the sample code . Basically you need the structure shown in the sample, and a project.xml file (POM) and a project.properties file.



Next you will need to set your project properties accordingly.



You need to edit the "google.webtoolkit.home" value, and the maven.jar.gwt-dev-platform location at a minimum. These denote where where you have GWT installed, and what platform the GWT "dev" jar is for respectively. These values can also be set (actually more appropriately) in Maven wide build.properties on a per machine basis - either way they must be addressed.



Once you have a project with said structure and configuration, the plugin itself, and have set the appropriate platform properties you then can invoke the following:

maven gwt

maven gwt:war

Step by Step GWT RPC in the sample

STEP 1:

Create a CLIENT side service interface which extends GWT RemoteService. This is demonstrated in the sample MyService.java class.



STEP 2:

Create a CLIENT side ASYNC service interface with the SAME NAME and the suffix "Async" as the initial client side class that extends RemoteService. This class should be identical to the RemoteService interface with several exceptions: the return type of each method should be void, and an additional AsyncCallBack object should be the last parameter of each method. This is demonstrated in the sample MyServiceAsync.java class.



STEP 3:

Still within CLIENT side code create the service object with a defined endpoint (path) and invoke the methods. This is demonstrated in the sample MyProjectEntryPoint.java class.



Note that the service object is created with the GWT static create method: MyServiceAsync service = (MyServiceAsync) GWT.create(MyService.class); and that the endpoint assigned to the service is set using the "moduleBaseURL" path: endpoint.setServiceEntryPoint(GWT.getModuleBaseURL() + "MyService"); . This ensures that the service path will be accessible BOTH in Hosted Mode with GWTShell and when later deployed to a servlet container.



Also note the RPC handling. The Button object has a ClickListener that invokes a method named callMyService which calls the MyService implementation on the server. The method has both onSuccess and onFailure methods in the anonymous AsynCallBack object that it passes in to the server method. These handle the resulting server callback when things work and do not work respectively.



STEP 4:

Create a SERVER side implementation of the client side side service interface which extends GWT RemoteServiceServlet. This is demonstrated in the sample MyServiceImpl.java class.



Note that this sample class retrieves a DataSource via JNDI and then uses a small self created HSQL database to store and retrieve data.

How to use -noserver (with or without the plugin)

See the -noserver configuration page.

How to configure Hosted Mode Tomcat Lite (if you are not using the plugin)

See the Tomcat Lite configuration page.