GWT-to-Errai Tutorial

Overview

GWT

The Google Web Toolkit (GWT) is an open source project that allows developers to create their entire web applications in Java by cross-compiling Java to Javascript.

Errai

Errai is an open source project providing many enhancements to GWT, including HTML5 templates, a bi-directional message bus, an in-browser IoC and CDI container, and more.

Tutorial Prerequisites and Goals

GWT Concepts

The purpose of this tutorial is to demonstrate how Errai can be added to a pre-existing GWT application. Consequently, this tutorial assumes basic familiarity with the structure of a GWT project.

Important

Key GWT Concepts Before reading this tutorial you should be familiar with these parts of a GWT project: host page GWT module war file/directory

Required Tools

This tutorial will use the following tools:

• Eclipse IDE

• Maven2Eclipse Plugin

• Jboss Forge 2.1.1 plugin for Eclipse

• Errai Addon for Forge 2.0.

Note	Errai Addon Tutorial The Errai Addon GitHub repository contains detailed instructions on how to install the Forge plugin for Eclipse and the Errai Addon.

Tutorial

The GWT Project

For this tutorial we will be using the GWT Showcase sample project. The source for this sample project comes with the GWT SDK (which you can download here). However, you are encouraged to follow along with your own project!

1. Importing Your Project into Eclipse

1. In the Eclipse menu, go to File > New > Java Project.

   

2. Deselect Use default location and click Browse.

   

3. Find and select the root directory for your project and click Finish.

2. Convert Project to Maven

1. If your project is already a maven project then skip to step (3).

2. Right click on your project and select Configure > Convert to Maven Project.

   

3. Fill in the fields for your maven artifact and click Finish.

   

3. Configuring the Source, Resource, and War Source Folders

The current (2.0.0.Beta1) version of the plugin does not fully support dynamic project layouts. Until this is resolved it is necessary to have the following project layout:

• Source Folder: src/main/java

• Resource Folder: src/main/resources

• War Source Folder: src/main/webapp

If you know that your project follows this layout (for example, if you use the default Maven project layout) then you may skip to step (7).

4. Set the Source Directory to src/main/java

1. In your project’s pom.xml find the tag project > build > sourceDirectory and change it’s value to src/main/java.

5. Set the Resource Directories

1. In your project’s pom.xml find the tag project > build > resources and replace its contents with this:

       <resources>
         <resource>
           <directory>src/main/java</directory>
           <excludes>
             <exclude>**/*.java</exclude>
           </excludes>
         </resource>
         <resource>
           <directory>src/main/resources</directory>
           <excludes>
             <exclude>**/*.java</exclude>
           </excludes>
         </resource>
       </resources>

   

Note	Additional Resource Folders There is no problem with having additional resource folders defined here.

6. Move Resources to the Appropriate Folders

1. First you will need to create the folders:

   • src/main/java

   • src/main/resources

   • src/main/webapp

   For each of the items above in the list, select your project in the Package Explorer, right click, and select New > Folder from the context menu.

2. In the New Folder prompt select the root of your project and type in the path for the folder you are making before clicking Finish.

   

   Note	Folders as Packages You new folders may appear as packages, if for example your project previously used src as the source folder. In this case, you will need to right click on your project and go to Maven > Update Project…​ before proceeding.

3. Move your project files to the new folders you’ve created. In particular:

   1. Java source files and your GWT module should go in src/main/java.

   2. Your other classpath resources (such as *.properties files) should go in src/main/resources.

   3. The entire contents of your previous war source directory (such as your WEB-INF/web.xml) should go in src/main/webapp.

4. Right click on your project and go to Maven > Update Project…​ to do a Maven update before continuing. Eclipse should now show your src/main/java and src/main/resources folders as source folders.

7. Move Existing Maven Plugin Configurations

If your project was already a Maven project, then it is likely you already have configurations for these plugins:

• gwt-maven-plugin

• maven-war-plugin

• maven-clean-plugin

• maven-compiler-plugin

If the Errai Addon finds these plugins in the correct place, it will attempt to merge your pre-existing configurations with those required for Errai. To ensure this happens:

1. Make a new profile in your pom.xml with the id jboss7.

2. Make a plugins tag in the new profile, and cut and paste your entire maven-war-plugin setup into it.

3. The other plugins listed above should be located in your project > build > plugins tag.

8. Add Errai to the Project

1. Select your project in the Package Explorer and press Ctrl + 5 to activate Forge.

2. In the Forge pop-up select the Setup Errai in a Project option. This will start the start the setup wizard.

   

3. Select the version of Errai you would like to use and click Next.

   

4. Select your GWT module and click Next.

   

   Important

   Multiple GWT Modules This plugin currently does not support configuring multiple GWT modules in a project. If you have multiple GWT modules, you will need to select (or create) one to configure Errai in. If you experience issues with this, it is recommended that you move your GWT modules into separate Maven projects.

5. If your module has been renamed using the rename-to attribute, enter that name here. Otherwise you may enter a new name for your module, or nothing to use the module’s logical name.

   

6. Pick any Errai features you would like to add. You may also choose to do this at a later time. In this demonstration we will add Errai IOC. When you are finished selecting any features (if any), click Finish.

   

9. Fixing M2Eclipse Errors

At this point, Eclipse is likely showing errors in your pom.xml for the maven-dependency-plugin and the gwt-maven-plugin. To fix these:

1. Find each plugin in the pom.xml. The execution tag should have a red underline.

   

2. Press Ctrl + 1 and select Permanantly mark goal …​ as ignored in Eclipse build.

10. Fixing Dependency Issues

If your project was not initially a Maven project, it is possible that at this point you have some compile errors because of missing dependencies. At this point, you should take the time to add any missing dependencies to your pom.xml.

1. For the Showcase example, we will add the gwt-dev dependency by copying the following into the dependencies section of your pom.xml:

       <dependency>
         <groupId>com.google.gwt</groupId>
         <artifactId>gwt-dev</artifactId>
         <scope>provided</scope>
       </dependency>

   Note	GWT Version Note that no version is required because gwt-dev is a managed dependency under the configuration used by the Errai Addon.

2. After adding all missing dependencies, you will need to do another Maven Update of your project before proceeding.

11. Give it a Spin

You should now be ready to try running your project. The goal here is that your project should behave exactly as it did before, but using the Errai Development Mode setup with JBoss AS 7.

1. To do this from the command-line, open a terminal in your projects root directory and run this command:

   mvn clean gwt:run

2. To do this from Eclipse:

   1. Right click on your project and select Run As…​ > Maven Build…​ from the context menu.

      

   2. In the Edit Configuration dialog, enter clean gwt:run into the Goals text field.

      

   3. Click Apply and then Run.

Trouble Shooting

If you’ve arrived at this point and your application is not running, here are some things worth investigating:

• Check your web.xml to see if any of your application servlet-mappings have been overwritten.

• Check that your .class are appearing in src/main/webapp/WEB-INF/classes.

• If you are using server-side CDI, make sure any code that is client-side only is in a package that matches the pattern .client.local.. The issue here specifically is that the Development Mode CDI container will be able to see these classes, which can cause classloading issues.

And if none of that helps, you can always ask for help on the Errai forum.

12. Add More Features and Start Coding

1. To add more Errai features, open Forge (Ctrl + 5) and use the Add Errai Features command. Similarly, features can be removed with the Remove Errai Features command.

2. You should now be ready to start using Errai in your project. For example in the Showcase sample, having added Errai IOC, we can now change the com.google.gwt.sample.showcase.Showcase class to use the IOC org.jboss.errai.ioc.client.api.EntryPoint annotation, rather than the com.google.gwt.core.client.EntryPoint interface.

   

   

More Resources

To learn more about what you can do with Errai, check out our website, and our documentation.

If you have questions or comments check out our forum or go to the #errai IRC channel on freenode.