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.
Comparison with Vaadin
At first sight it might seem that Errai overlaps with some other frameworks like Vaadin which provides a rich set of components built on the top of GWT. However the difference is that Errai is not a superset of GWT components but a communication framework for GWT. It can be used for passing messages back and forth between server and client, so it’s not a replacement for Vaadin; rather it overlaps with the RPC implementation in GWT itself.
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:
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:
Next we need to instruct Eclipse to run the project from the WAR directory, which (being a Maven project) is disabled by default.
That’s all. Run the application using Run As Web application icon
And here’s your first Errai application in action:
