Errai Reference Guide

Since Errai is an end-to-end framework, in that, parts of the framework run and operate within the client and parts run and operate within the server, there is a set of various technologies upon which Errai relies. This section will detail the basic core technologies which you’ll need to be familiar with.

You have two options to set up an Errai application. You can start by copying an existing example application (i.e. the errai tutorial demo) or by building an app with the Errai Forge Addon:

// 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!");

  }

}

GWT’s development mode allows for code-refresh development cycles. Simply change a client-side class and refresh the browser to see your changes. You can also debug client and server side code in your IDE of choice.

Change into the newly created 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 running on Windows.

Figure 1.1. GWT Development Mode running on Windows

Figure 1.2. Missing plugin error

Once you have configured your browser for development with GWT, and after loading the app with the Launch Default Browser button, you should see the application load.

If you are using errai-tutorial, you should see a page with a complaint form.

If you followed the instructions for using the Errai Forge plugin, there should be a blank page with an alert saying "Hello World!".

That’s it! You’ve got your first Errai Application up and running. In the next section we’ll setup your IDE.

Errai CDI as its namesake implies is based on, and is in fact, a partial implementation of the CDI (Contexts and Dependency Injection) specification. Errai CDI covers most of the programming model but omits the CDI SPI, instead replacing it with it a custom set of APIs which are more appropriate for the client programming model of Errai.

These differences aside, using Errai CDI in conjunction with CDI on the server will provide you with a uniform programming model across the client and server code of your application.

This guide does not assume any past experience with CDI. However, you may wish to consider reading the the Weld Documentation in addition to this guide.

public class Foo {

  public String getName() {

    return "Mr. Foo";

  }

}

@ApplicationScoped

public class Bar {

  public String getName() {

    return "Mr. Bar";

  }

}

@ApplicationScoped

public class Bar {

  @Inject Foo foo;


  public String getName() {

    return "Mr. Bar";

  }

}

public class Foo {

  @Inject Bar bar;


  public String getName() {

    return "Mr. Foo";

  }

}

assert fooInstance.bar.foo == fooInstance

@ApplicationScoped

public class Bar {

  @Inject Foo foo;

  @Inject MessageBus bus;


  public String getName() {

    return "Mr. Bar";

  }

}

In order to send a message from a client you need to create a Message and send it through an instance of MessageBus . In this simple example we send it to the subject HelloWorldService.

public class HelloWorld implements EntryPoint {


  // Get an instance of the RequestDispatcher

  private RequestDispatcher dispatcher = ErraiBus.getDispatcher();


  public void onModuleLoad() {

    Button button = new Button("Send message");


    button.addClickHandler(new ClickHandler() {

      public void onClick(ClickEvent event) {

        // Send a message to the 'HelloWorldService'.

        MessageBuilder.createMessage()

          .toSubject("HelloWorldService") // (1)

          .signalling() // (2)

          .noErrorHandling() // (3)

          .sendNowWith(dispatcher); // (4)

        });


        [...]

      }

   }

}

In the above example we build and send a message every time the button is clicked. Here’s an explanation of what’s going on as annotated above:

Every message has a sender and at least one receiver. A receiver is as it sounds—it receives the message and does something with it. Implementing a receiver (also referred to as a service) is as simple as implementing our standard MessageCallback interface, which is used pervasively across, both client and server code. Let’s begin with server side component that receives messages:

@Service

  public class HelloWorldService implements MessageCallback {

    public void callback(Message message) {

      System.out.println("Hello, World!");

    }

  }

Here 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.

In the following example we extend our server side component to reply with a message when the callback method is invoked. It will create a message and address it to the subject ' HelloWorldClient ':

@Service

public class HelloWorldService implements MessageCallback {


  private RequestDispatcher dispatcher;


  @Inject

  public HelloWorldService(RequestDispatcher dispatcher) {

    dispatcher = dispatcher;

  }


  public void callback(CommandMessage message) {

    // Send a message to the 'HelloWorldClient'.

    MessageBuilder.createMessage()

      .toSubject("HelloWorldClient") // (1)

      .signalling()                  // (2)

      .with("text", "Hi There")      // (3)

      .noErrorHandling()             // (4)

      .sendNowWith(dispatcher);      // (5)

    });

  }

}

The above example shows a service which sends a message in response to receiving a message. Here’s what’s going on:

Messages can be received asynchronously and arbitriraily by declaring callback services within the client bus. As ErraiBus maintains an open COMET channel at all times, these messages are delivered in real time to the client as they are sent. This provides built-in push messaging for all client services.

public class HelloWorld implements EntryPoint {


  private MessageBus bus = ErraiBus.get();


  public void onModuleLoad() {

     [...]


     /*

      * Declare a service to receive messages on the subject

      * "BroadcastReceiver".

      */

     bus.subscribe("BroadcastReceiver", new MessageCallback() {

       public void callback(CommandMessage message) {

         /*

          * When a message arrives, extract the "text" field and

          * do something with it

          */

          String messageText = message.get(String.class, "text");

        }

     });


     [...]

  }

}

In the above example, we declare a new client service called "BroadcastReceiver" which can now accept both local messages and remote messages from the server bus. The service will be available in the client to receive messages as long the client bus is and the service is not explicitly de-registered.

On the client or the server, you can create a local receiver which only receives messages that originated on the local bus. A local server-side service only receives messages that originate on that server, and a local client-side service only receives messages that originated on that client.

To create a local receiver using the declarative API, use the @Local annotation in conjunction with @Service:

@Local

@Service

  public class HelloIntrovertService implements MessageCallback {

    public void callback(Message message) {

      System.out.println("Hello, me!");

    }

  }

To create a local receiver using through programmatic service registration, use the subscribeLocal() method in place of subscribe() :

public void registerLocalService(MessageBus bus) {

  bus.subscribeLocal("LocalBroadcastReceiver", new MessageCallback() {

    public void callback(Message message) {

       String messageText = message.get(String.class, "text");

     }

  });

}

Both examples above work in client- and server-side code.

The essential architectural thing you’ll need to do is create a relay service that runs on the server. Since a service advertised on the server is visible to all clients and all clients are visible to the server, you might already see where we’re going with this.

By creating a service on the server which accepts messages from clients, you can create a simple protocol on-top of the bus to enable quasi peer-to-peer communication. (We say quasi, because it still needs to be routed through the server)

While you can probably imagine simply creating a broadcast-like service which accepts a message from one client and broadcasts it to the rest of the world, it may be less clear how to go about routing from one particular client to another particular client, so we’ll focus on that problem. This is covered in the next chapter.

You may need to detect problems which occur on the bus at runtime. The client bus API provides a facility for doing this in the org.jboss.errai.bus.client.framework.ClientMessageBus using the addTransportErrorHandler() method.

A TransportErrorHandler is an interface which you can use to define error handling behavior in the event of a transport problem.

For example:

messageBus.addTransportErrorHandler(new TransportErrorHandler() {

  public void onError(TransportError error) {

    // error handling code.

  }

});

The TransportError interface represents the details of an an error from the bus. It contains a set of methods which can be used for determining information on the initial request which triggered the error, if the error occurred over HTTP or WebSockets, status code information, etc. See the JavaDoc for more information.

The lifescyle of a session is bound by the underlying HTTP session. It is also bound by activity thresholds. Clients are required to send heartbeat messages every once in a while to maintain their sessions with the server. If a heartbeat message is not received after a certain period of time, the session is terminated and any resources are deallocated.

One of the things Errai offers is the concept of session and local scopes.

public class TestService implements MessageCallback {

  public void callback(final Message message) {

    // obtain a reference to the session context by referencing the incoming message.

    SessionContext injectionContext = SessionContext.get(message);


    // set an attribute.

    injectionContext.setAttribute("MyAttribute", "Foo");

  }

}

public class TestService implements MessageCallback {

  public void callback(final Message message) {

    // obtain a reference to the local context by referencing the incoming message.

    LocalContext injectionContext = LocalContext.get(message);


   // set an attribute.

    injectionContext.setAttribute("MyAttribute", "Foo");

  }

}

All wire messages sent across are assumed to be JSON arrays at the outermost element, contained in which, there are 0..n messages. An empty array is considered a no-operation, but should be counted as activity against any idle timeout limit between federated buses.

[

  {"ToSubject" : "SomeEndpoint", "Value" : "SomeValue" },

  {"ToSubject" : "SomeOtherEndpoint", "Value" : "SomeOtherValue"}

]

{

  "ToSubject" : "TopicSubscriber",

  "CommandType" : "Subscribe",

  "Value " : "happyTopic",

  "ReplyTo" : "MyTopicSubscriberReplyTo"

}

There is no real distinction in the J.REP protocol between communication with the server, versus communication with the client. In fact, it assumed from an architectural standpoint that there is no real distinction between a client and a server. Each bus participates in a flat-namespaced federation. Therefore, it is possible that a subject may be observed on both the server and the client.

One in-built assumption of a J.REP-compliant bus however, is that messages are routed within the auspices of session isolation. Consider the following diagram:

Figure 2.1. Topology of a J.REP Messaging Federation

Federation between buses requires management traffic to negotiate connections and manage visibility of services between buses. This is accomplished through services named ClientBus and ServerBus which both implement the same protocol contracts which are defined in this section.

Activating the sideband server is as simple as adding the following to the ErraiService.properties file:

errai.bus.enable_web_socket_server=true

The default port for the sideband server is 8085. You can change this by specifying a port with the errai.bus.web_socket_port property in the ErraiService.properties file.

This is an alternative approach to the sideband server described in the previous chapter. Make sure to NOT configure both! It is currently necessary to use the native connector in JBoss AS for WebSockets to work. So the first step is to configure your JBoss AS instance(s) to use the native connector by changing the domain/configuration/standalone.xml or domain/configuration/domain.xml file as follows:

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">

to:

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="true">

You will then need to configure the servlet in your application’s web.xml which will provide WebSocket upgrade support within AS7.

Add the following to the web.xml :

<context-param>

  <param-name>websockets-enabled</param-name>

  <param-value>true</param-value>

</context-param>



<context-param>

  <param-name>websocket-path-element</param-name>

  <param-value>in.erraiBusWS</param-value>

</context-param>

This will tell the bus to enable web sockets support. The websocket-path-element specified the path element within a URL which the client bus should request in order to negotiate a websocket connection. For instance, specifying in.erraiBusWS as we have in the snippit above, will result in attempted negotiation at http://<your_server>:<your_port>/<context_path>/in.erraiBusWS. For this to have any meaningful result, we must add a servlet mapping that will match this pattern:

<servlet>

  <servlet-name>ErraiWSServlet</servlet-name>

  <servlet-class>org.jboss.errai.bus.server.servlet.JBossAS7WebSocketServlet</servlet-class>

  <load-on-startup>1</load-on-startup>

</servlet>



<servlet-mapping>

  <servlet-name>ErraiWSServlet</servlet-name>

  <url-pattern>*.erraiBusWS</url-pattern>

</servlet-mapping>

    <dependency>

        <groupId>org.jboss.errai</groupId>

        <artifactId>errai-bus-jboss7-websocket</artifactId>

        <version>${errai.version}</version>

    </dependency>

By default, Errai’s client-side message bus attempts to connect to the server as soon as the ErraiBus module has been loaded. The bus will stay connected until a lengthy (about 45 seconds) communication failure occurs, or the web page is unloaded.

The application can affect bus communication through two mechanisms:

To resume server communication after a call to ClientMessageBus.stop() or after communication with the server has exceeded the bus' retry timeout, call ((ClientMessageBus) ErraiBus.get()).init(). You can use a BusLifecycleListener to monitor the success or failure of this attempt. See the next section for details.

In a perfect world, the client message bus would always be able to communicate with the server message bus. But in the real world, there’s a whole array of reasons why the communication link between the server and the client might be interrupted.

On its own, the client message bus will attempt to reconnect with the server whenever communication has been disrupted. Errai applications can monitor the status of the bus' communication link (whether it is disconnected, attempting to connect, or fully connected) through the BusLifecycleListener interface:

class BusStatusLogger implements BusLifecycleListener {


  @Override

  public void busAssociating(BusLifecycleEvent e) {

    GWT.log("Errai Bus trying to connect...");

  }


  @Override

  public void busOnline(BusLifecycleEvent e) {

    GWT.log("Errai Bus connected!");

  }


  @Override

  public void busOffline(BusLifecycleEvent e) {

    GWT.log("Errai Bus trying to connect...");

  }


  @Override

  public void busDisassociating(BusLifecycleEvent e) {

    GWT.log("Errai Bus going into local-only mode.");

  }

}

To attach such a listener to the bus, make the following call in client-side code:

ClientMessageBus bus = (ClientMessageBus) ErraiBus.get();

bus.addLifecycleListener(new BusStatusLogger());

In Errai IOC, all client types are valid bean types if they are default constructable or can have construction dependencies satisfied. These unqualified beans belong to the dependent pseudo-scope. See: Dependent Psuedo-Scope from CDI Documentation

Additionally, beans may be qualified as @ApplicationScoped, @Singleton or @EntryPoint. Although @ApplicationScoped and @Singleton are supported for completeness and conformance, within the client they effectively result in behavior that is identical.

public void MyDependentScopedBean {

  private final Date createdDate;


  public MyDependentScopedBean {

    createdDate = new Date();

  }

}

@ApplicationScoped

public void MyClientBean {

  @Inject MyDependentScopedBean bean;


  // ... //

}

As Errai IOC provides a container-based approach to client development, support for Errai services are exposed to the container so they may be injected and used throughout your application where appropriate. This section covers those services.

@Service

public class MyService implements MessageCallback {

  public void callback(Message message) {

    // ... //

  }

}

@Service @Local

public class MyLocalService implements MessageCallback {

  public void callback(Message message) {

    // ... //

  }

}

The IOC container, by default, provides a set of default injectable bean types. They range from basic services, to injectable proxies for RPC. This section covers the facilities available out-of-the-box.

@Inject MessageBus bus;

@Inject RequestDispatcher dispatcher;

public void MyClientBean {

  @Inject

  private Caller<MyRpcInterface> rpcCaller;


  // ... ///


  @EventHandler("button")

  public void onButtonClick(ClickHandler handler) {

    rpcCaller.call(new RemoteCallback<Void>() {

      public void callback(Void void) {

        // put code here that should execute after RPC response arrives

      }

    ).callSomeMethod();

  }

}

  @Inject

  @ToSubject("ListCapitializationService")

  Sender<List<String>> listSender;


  // ... ///


  @EventHandler("button")

  public void onButtonClick(ClickHandler handler) {

    List<String> myListOfStrings = getSelectedCitiesFromForm();

    listSender.send(myListOfStrings, new MessageCallback() {

      public void callback(Message reply) {

        // do stuff with reply

      }

    );

  }

  @Inject

  @ToSubject("ListCapitializationService")

  @ReplyTo("ClientListService")

  Sender<List<String>> listSender;


  // ... ///


  @EventHandler("button")

  public void onButtonClick(ClickHandler handler) {

    List<String> myListOfStrings = getSelectedCitiesFromForm();

    listSender.send(myListOfStrings);

  }


  @Singleton

  @Service

  public static class ClientListService implements MessageCallback {

    @Override

    public void callback(Message message) {

      // do stuff with message

    }

  }

A problem commonly associated with building large applications in the browser is ensuring that things happen in the proper order when code starts executing. Errai IOC provides you tools which permit you to ensure things happen before initialization, and forcing things to happen after initialization of all of the Errai services.

@Singleton

public class MyClientBean {

  @Inject InitBallot<MyClientBean> ballot;


  @PostConstruct

  public void doStuff() {

    // ... do some work ...


    ballot.voteForInit();

  }

}

@Singleton

public class MyClientBean {

  @AfterInitialization

  public void doStuffAfterInit() {

    // ... do some work ...

  }

}

The @Timed annotation allows scheduling method executions on managed client-side beans. Timers are automatically scoped to the scope of the corresponding managed bean and participate in the same lifecycle (see Bean Lifecycle for details).

In the following example the updateTime method is invoked repeatedly every second.

@Timed(type = TimerType.REPEATING, interval = 1, timeUnit = TimeUnit.SECONDS)

private void updateTime() {

  timeWidget.setTime(System.currentTimeMillis);

}

For delayed one-time execution of methods type = TimerType.DELAYED can be used instead.

Looking up beans can be done through the use of the lookupBeans() method. Here’s a basic example:

public MyManagedBean {

  @Inject SyncBeanManager manager;


  public void lookupBean() {

    IOCBeanDef<SimpleBean> bean = manager.lookupBean(SimpleBean.class);


    if (bean != null) {

      // get the instance of the bean

      SimpleBean inst = bean.getInstance();

    }

  }

}

MyQualifier qual = new MyQualifier() {

  public annotationType() {

    return MyQualifier.class;

  }

}


MyOtherQualifier qual2 = new MyOtherQualifier() {

  public annotationType() {

    return MyOtherQualifier.class;

  }

}


// pass qualifiers to ClientBeanManager.lookupBeans

IOCBeanDef<SimpleBean> bean = beanManager.lookupBean(SimpleBean.class, qual, qual2);

Not all beans that are available for injection are available for lookup from the bean manager by default. Only beans which are explicitly scoped are available for dynamic lookup. This is an intentional feature to keep the size of the generated code down in the browser.

It may be desirable to have multiple matching dependencies for a given injection point with the ability to specify which implementation to use at runtime. For instance, you may have different versions of your application which target different browsers or capabilities of the browser. Using alternatives allows you to share common interfaces among your beans, while still using dependency injection, by exporting consideration of what implementation to use to the container’s configuration.

Consider the following example:

@Singleton @Alternative

public class MobileView implements View {

  // ... //

}

and

@Singleton @Alternative

public class DesktopView implements View {

  // ... //

In our controller logic we in turn inject the View interface:

@EntryPoint

public class MyApp {

  @Inject

  View view;


  // ... //

}

This code is unaware of the implementation of View, which maintains good separation of concerns. However, this of course creates an ambiguous dependency on the View interface as it has two matching subtypes in this case. Thus, we must configure the container to specify which alternative to use. Also note, that the beans in both cases have been annotated with javax.enterprise.inject.Alternative.

In your ErraiApp.properties for the module, you can simply specify which active alternative should be used:

errai.ioc.enabled.alternatives=org.foo.MobileView

You can specify multiple alternative classes by white space separating them:

errai.ioc.enabled.alternatives=org.foo.MobileView \
                               org.foo.HTML5Orientation \
                               org.foo.MobileStorage

You can only have one enabled alternative for a matching set of alternatives, otherwise you will get ambiguous resolution errors from the container.

Similar to alternatives, but specifically designed for testing scenarios, you can replace beans with mocks at runtime for the purposes of running unit tests. This is accomplished simply by annotating a bean with the org.jboss.errai.ioc.client.api.TestMock annotation. Doing so will prioritize consideration of the bean over any other matching beans while running unit tests.

Consider the following:

@ApplicationScoped

public class UserManagementImpl implements UserManagement {

  public List<User> listUsers() {

     // do user listy things!

  }

}

You can specify a mock implementation of this class by implementing its common parent type ( UserManagement ) and annotating that class with the @TestMock annotation inside your test package like so:

@TestMock @ApplicationScoped

public class MockUserManagementImpl implements UserManagement {

  public List<User> listUsers() {

     // return only a test user.

     return Collections.singletonList(TestUser.INSTANCE);

  }

}

In this case, the container will replace the UserManagementImpl with the MockUserManagementImpl automatically when running the unit tests.

The @TestMock annotation can also be used to specify alternative providers during test execution. For example, it can be used to mock a Caller<T>. Callers are used to invoke RPC or JAX-RS endpoints. During tests you might want to replace theses callers with mock implementations. For details on providers see Container Wiring.

@TestMock @IOCProvider

public class MockedHappyServiceCallerProvider implements ContextualTypeProvider<Caller<HappyService>> {


  @Override

  public Caller<HappyService> provide(Class<?>[] typeargs, Annotation[] qualifiers) {

    return new Caller<HappyService>() {

      ...

    }

}

Beans under management of Errai IOC, of any scope, can be explicitly destroyed through the client bean manager. Destruction of a managed bean is accomplished by passing a reference to the destroyBean() method of the bean manager.

public MyManagedBean {

  @Inject SyncBeanManager manager;


  public void createABeanThenDestroyIt() {

    // get a new bean.

    SimpleBean bean = manager.lookupBean(SimpleBean.class).getInstance();


    bean.sendMessage("Sorry, I need to dispose of you now");


    // destroy the bean!

    manager.destroyBean(bean);

  }

}

@Dependent

public class SimpleBean {

   @Inject @New AnotherBean anotherBean;


   public AnotherBean getAnotherBean() {

     return anotherBean;

   }


   @PreDestroy

   private void cleanUp() {

     // do some cleanup tasks

   }

}

public MyManagedBean {

  @Inject SyncBeanManager manager;


  public void createABeanThenDestroyIt() {

    // get a new bean.

    SimpleBean bean = manager.lookupBean(SimpleBean.class).getInstance();


    // destroy the AnotherBean reference from inside the bean

    manager.destroyBean(bean.getAnotherBean());

  }

}

public MyManagedBean {

  @Inject @New SimpleBean myNewSimpleBean;

  @Inject Disposer<SimpleBean> simpleBeanDisposer;


  public void destroyMyBean() {

    simpleBeanDisposer.dispose(myNewSimpleBean);

  }

}

The CDI container in Errai is built around the Errai IOC module, and thus is a superset of the existing functionality in Errai IOC. Thus, all features and APIs documented in Errai IOC are accessible and usable with this Errai CDI programming model.

A server can address a single client in response to an event annotating event types as @Conversational. Consider a service that responds to a subscription event.

@ApplicationScoped

public class SubscriptionService {


  @Inject

  private Event<Documents> welcomeEvent;


  public void onSubscription(@Observes Subscription subscription) {

    Document docs = createWelcomePackage(subscription);

    welcomeEvent.fire(docs);

 }

}