GWT is a toolkit built around a Java-to-JavaScript compiler. It provides a JRE emulation library, abstraction of browser quirks, a development mode runtime, and tools for native JavaScript integration.

Errai uses GWT to accomplish the translation of concepts such as CDI into the browser, which enables a consistent client and server programming experience.

CDI is a standard part of the Java EE 6.0 stack, and is defined in the JSR-299 specification. CDI is the main programming model explored in this guide. As such, the basic concepts of CDI will be introduced in this guide, so pre-existing knowledge is not strictly necessary.

Errai’s support for CDI is two-fold. For the server-side, Errai has integration with Weld, which is the reference implementation (RI) of the JSR-299 specification. The client-side integration for CDI is provided by the Errai CDI extension. Errai CDI implements a subset of the JSR-299 specification to provide the CDI programming model within client code.

JAX-RS is an API which provides a standardized programming model for specifying web services based around the concept of the Representational State Transfer (REST) architecture. REST has by and far become the preferred way of developing web services, and is used pervasively in modern web applications. Errai provides a set of tools to make working with JAX-RS easier.

ErraiBus is an underlying transport technology which provides true, bidirectional, asynchronous messaging between the client and the server. It powers a myriad of technologies throughout the Errai framework, from RPC to CDI Events.

Simply download and unzip this demo. Check out the README file and continue with running the app in GWT’s development mode and importing the project into Eclipse .

Another way to start a new project with Errai is to use Forge and the Errai Forge Addon. To use this method, follow the instructions here to install the Errai Forge Addon and create a new project.

In the upcomming sections, we will demonstrate how to run your app in GWT Development Mode through the command line and eclipse, so it would be nice to have something to run so that you are able to verify that everything is working. Here is a sample class you can use that displays an alert when the app loads:

// Add the package declaration here


import javax.annotation.PostConstruct;

import org.jboss.errai.ioc.client.api.EntryPoint;

import com.google.gwt.user.client.Window;


@EntryPoint

public class App {


  @PostConstruct

  public void onLoad() {

    Window.alert("Hello World!");

  }

}

For this code to run properly, you must use the Errai Forge Addon Add Errai Features command to install Errai IOC.

Create new subfolder, client/local, under the folder containing your GWT module file. Then create a file, App.java, in this new package and copy the above sample code (making sure to replace the top comment with the package declaration).

Change into your web app’s project directory and type the following:

mvn clean gwt:run

This will begin the download of all the dependencies required to develop with and run Errai. It may take a few minutes to complete the download.

When it is finished, you should see the GWT Development Mode runtime window appear as shown in Figure 1.

Figure 1.1. GWT Development Mode

To debug your app using GWT’s development mode, you will need to start a remote debugger separately and run the following command in your project directory:

mvn clean gwt:debug

This section will walk you through using Maven tooling for running and debugging your app within Eclipse. If you have not already installed m2e in Eclipse, you will want to do so now.

To install the Maven tooling, use the following steps:

Once you have completed the installation of the prerequisites from the previous section, you will now be able to go ahead and import the Maven project you created in the first section of this guide. We will use the errai-tutorial project as an example.

Follow these steps to get the project setup:

This will start the GWT Development Mode exactly as running mvn clean gwt:run from the command line.

This method requires the Google Plugin for Eclipse (GPE). You can find the instructions to download and install it here.

Here are the steps to setup a run/debug configuration using the embedded WildFly launcher:

That’s it! To debug your application within Eclipse, simply select your debug configuration and hit Debug. This will start GWT’s dev mode as well as the debugger within Eclipse.

The Ultimate Edition for Intellij IDEA comes with a built-in GWT plugin that allows you to run and debug GWT apps specifically. We can configure the plugin to use the embedded WildFly launcher for debugging ease, in order to debug both server and client-side code in one debug session. This section describes how to set up a GWT run/debug configuration within Intellij IDEA:

To run or debug your app, select this configuration in the top right corner of Intellij IDEA and click the Run or Debug buttons next to it. Your app should start up in Dev Mode within Intellij automatically and you should be able to use Intellij’s own debugger to debug your code.

Now that you have everything set up, it’s time to move on to coding!

A bean in CDI is merely a POJO (Plain Old Java Object), for the most part. In the context of CDI, any plain, default constructable class is a member of the dependent scope . Don’t worry too much about what that means for now. Let’s just go ahead and make one:

public class Foo {

  public String getName() {

    return "Mr. Foo";

  }

}

That was an easy, if uninteresting, exercise. But despite this class' worthy distinction as a dependent-scoped bean, it’s actually quite a useless dependent scope beaned. Well, maybe not so much useless as it is unused.

Well, how would we use this bean? To answer that question we’re going to need to introduce the concept of scopes in more detail.

Scopes, put simply, are the context within which beans live. Some scopes are short-lived and some are long-lived. For instance, there are beans which you may only want to create during a request, and beans which you want to live for as long as the application is running.

It turns out that CDI includes a set of default scopes which represent these very things.

We’ll start by taking a look at the application scope, which is lovingly represented by the annotation @ApplicationScoped. An application-scoped bean is a bean which will live for the entire duration of the application. In this sense, it is essentially like a singleton. And it’s generally okay to think of it in that way.

So let’s declare an application-scoped bean:

@ApplicationScoped

public class Bar {

  public String getName() {

    return "Mr. Bar";

  }

}

That was almost as easy as making the last bean. The difference between this bean and the last, is Bar will actually be instantiated by the container automatically, and Foo will not.

So what can we do with Foo ? Well, let’s go ahead and get familiar with dependency injection, shall we?

@ApplicationScoped

public class Bar {

  @Inject Foo foo;


  public String getName() {

    return "Mr. Bar";

  }

}

We have added a field of the type Foo which we declared earlier, and we have annotated it with javax.inject.Inject. This tells the container to inject an instance of Foo into our bean. Since our Foo bean is of the dependent scope, the bean manager will actually create a new instance of Foo and pass it in.

This scope of the newly instantiated Foo is dependent on the scope that it was injected into. In this case, the application scope. On the other hand, if we were to turn around an inject Bar into Foo, the behaviour is quite different.

public class Foo {

  @Inject Bar bar;


  public String getName() {

    return "Mr. Foo";

  }

}

Here, every time a new instance of Foo is created, the same instance of Bar will be injected. That is to say: this pseudo-code assertion is now always true:

assert fooInstance.bar.foo == fooInstance

In the case of an Errai application, there are a bunch of application scoped beans which come built-in for common services like ErraiBus. Thus, in an Errai application which uses the message bus, we can inject a handle to the MessageBus service into any of our beans. Let’s go ahead and do that in our Bar class:

@ApplicationScoped

public class Bar {

  @Inject Foo foo;

  @Inject MessageBus bus;


  public String getName() {

    return "Mr. Bar";

  }

}

If working with dependency injection is new to you, then this is where you’ll start seeing some practical benefit. When you need a common service in your client code, you ask the container for it by injecting it. This frees you from worrying about the proper APIs to use in order to access a service; we need to use the message bus in our Bar bean, and so we inject it.

Now that we’re getting the gist of how dependency injection works, let’s go back to our sample project.

In the App class that was created you may have noticed that the bean’s scope is @EntryPoint.

The @EntryPoint annotation is an annotation which provides a an analogue to the GWT EntryPoint concept within the context of CDI in Errai. Basically you want to think of @EntryPoint beans as the Errai CDI-equalivalent of main() methods. But as of Errai 2.2., that might actually be going a little far. In fact, you might be asking what is the real difference between @ApplicationScoped and @EntryPoint in practice. The short answer is: nothing.

When Errai IOC, the technology which powers Errai’s client-side CDI, was first built, it lacked the concept of scopes. To create entry point objects into the application which would automatically run, this annotation was added.

If you’re not convinced, try running this example with the mvn clean gwt:run command (described above).