Errai quickstart tutorial

Errai is a GWT (Google Web Toolkit) based framework for building rich web applications using next-generation API such as CDI and JPA. Built on-top of ErraiBus, the framework provides a unified infrastructure with true, uniform, asynchronous messaging across the client and server.

 

What is ErraiBus ?
ErraiBus is the backbone of the Errai framework's which enables connecting the client and the server using a fluent messaging API that can suit even complex messaging scenarios such as instant messaging clients, stock tickers or monitoring instruments.

 

Now let's get started. The simplest way to get our hands dirty is using the Errai Maven archetype which provides a simple skeleton project to get started.  So have Maven installed and launch the following archetype creation:

 

mvn archetype:generate \
-DarchetypeGroupId=org.jboss.errai.archetypes \
-DarchetypeArtifactId=bus-quickstart \
-DarchetypeVersion=2.2.0.Final \
-DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/

After a while the archetype will end up with a standard gwt project skeleton:

 

C:\MAVEN\ERRAI\GWT-APP
¦   pom.xml
¦
+---src
¦   +---jboss5
¦   ¦   +---WEB-INF
¦   ¦           web.xml
¦   ¦
¦   +---jboss6
¦   ¦   +---WEB-INF
¦   ¦           web.xml
¦   ¦
¦   +---jboss7
¦   ¦   +---WEB-INF
¦   ¦           web.xml
¦   ¦
¦   +---jetty
¦   ¦   +---WEB-INF
¦   ¦           web.xml
¦   ¦
¦   +---main
¦   ¦   ¦
¦   ¦   +---java
¦   ¦   ¦   +---com
¦   ¦   ¦       +---sample
¦   ¦   ¦           ¦   App.gwt.xml
¦   ¦   ¦           ¦
¦   ¦   ¦           +---client
¦   ¦   ¦           ¦   +---local
¦   ¦   ¦           ¦           HelloWorldClient.java
¦   ¦   ¦           ¦
¦   ¦   ¦           +---server
¦   ¦   ¦                   HelloWorldService.java
¦   ¦   ¦
¦   ¦   +---resources
¦   ¦   ¦       ErraiApp.properties
¦   ¦   ¦       ErraiService.properties
¦   ¦   ¦       log4j.properties
¦   ¦   ¦
¦   ¦   +---webapp
¦   ¦       ¦   App.css
¦   ¦       ¦   App.html
¦   ¦       ¦
¦   ¦       +---WEB-INF
¦   ¦           ¦   web.xml
¦   ¦           ¦
¦   ¦           +---classes
¦   ¦           +---deploy
¦   ¦           ¦
¦   ¦           +---lib
¦   ¦
¦   +---test
¦   ¦   +---java
¦   ¦   +---resources
¦   ¦           ErraiApp.properties
¦   ¦
¦   +---tomcat
¦       +---WEB-INF
¦               web.xml
¦
+---target

 To launch the GWT development mode, move into the project directory and type:

mvn gwt:run

Deploy on JBoss AS 7

If you want to deploy the target artifact on JBoss AS 7, you need to use the Maven Profile named jboss 7 and copy the artifact on the JBoss AS 7 folder:

mvn -Pjboss7 clean install
cp target/gwt-app.war $JBOSS_HOME/standalone/deployments

Importing the Project into Eclipse

Once you are satisfied with your first steps, it's time to import the project into Eclipse. In order to manage your project from within Eclipse you need to download the GWT plugin for Eclipse.
Install the GWT plugin for Eclipse Juno:
Start Eclipse, then select Help > Install New Software... In the dialog that appears, enter the update site URL into the Work with text box:

http://dl.google.com/eclipse/plugin/4.2

The required component is Google Plugin for Eclipse. Select the checkbox next to Google Plugin for Eclipse(required). Next it's required also that you install also the Google App Engine Java SDK, select the checkbox next to Google App Engine Engine Java SDK.

Once done with the GWT plugin, restart Eclipse and import the Errai project as Maven project:

errai tutorial

Examining the Client and the Server

This even simple application contains the core of Errai Messaging funtionalities: it is composed of a Client and a Server class. In order to send a message from a client you need to create a Message and send it through an instance of MessageBus.
So here's our HelloWorldClient which is declared as EntryPoint for your GWT application and gets injected an instance of the MessageBus:

@EntryPoint
public class HelloWorldClient extends VerticalPanel {

  @Inject
  private MessageBus bus;

  private final Label responseLabel = new Label();
  private final Button button = new Button("Send");
  private final TextBox message = new TextBox();

  @PostConstruct
  public void buildUI() {

      button.addClickHandler(new ClickHandler() {
          public void onClick(ClickEvent event) {
              System.out.println("Handling click event!");
              sendMessage();
          }
      });

      HorizontalPanel horizontalPanel = new HorizontalPanel();
      horizontalPanel.add(message);
      horizontalPanel.add(button);
      horizontalPanel.add(responseLabel);

      RootPanel.get().add(horizontalPanel);
      
      System.out.println("UI Constructed!");
  }
  
   void sendMessage() {
    MessageBuilder.createMessage()
        .toSubject("HelloWorldService")
        .withValue("Hello, There!")
        .done()
        .repliesTo(new MessageCallback() {
          public void callback(Message message) {
            System.out.println("Got a Response!");
            responseLabel.setText("Message from Server: " + message.get(String.class, MessageParts.Value));
          }
        })
        .sendNowWith(bus);
  }


  Label getResponseLabel() {
    return responseLabel;
  }
}


Notice that this class uses a javax's @PostContruct annotation to initialize the components, instead of the J2SE constructor approach. Within the page a set of GWT components are added: most important for us is the Button which contains both a clickHandler and a MessageCallback, into the sendMessage method.

Coding the server is even easier: all it needs is implementing the MessageCallback interface and coding the callback method:

@Service
public class HelloWorldService implements MessageCallback {

  public void callback(Message message) {
    MessageBuilder.createConversation(message)
      .subjectProvided()
      .withValue("Hello, World! The server's time is now " + new Date() + ".")
      .done().reply();
  }
}


He we declare an extremely simple service. The @Service annotation provides a convenient, meta-data based way of having the bus auto-discover and deploy the service.

Configuring Eclipse to run the example. If you want to use the sample application using the GWT plugin functionalities, you need just to set a couple of settings: at first you need to specify the application Entry point via the Properties | Google | WebToolkit settings:

errai tutorial

Next we need to instruct Eclipse to run the project from the WAR directory, which (being a Maven project) is disabled by default.

errai tutorial

That's all. Run the application using Run As Web application icon

errai tutorial

And here's your first Errai application in action:

errai tutorial

Follow us on Twitter