Errai User Guide

The MessageBuilder is the heart of the messaging API in ErraiBus. It provides a fluent / builder API, that is used for constructing messages. All three major message patterns can be constructed from the MessageBuilder.

Components that want to receive messages need to implement the MessageCallback interface.

But before we dive into the details, let look at some use cases first.

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

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.

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 MessageBus
        private MessageBus bus = ErraiBus.get();

        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(bus);                          // (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:

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 MessageBus bus;

        @Inject                                         
        public HelloWorldService(MessageBus bus) {
            this.bus = bus;
        }

        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(bus);                          // (5)
            });
        }
    }   

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

If a client needs to receive messages that are "pushed" from the server side it needs to register a listener on a certain subject.

    public class HelloWorld implements EntryPoint {
        private MessageBus bus = ErraiBus.get();

        public void onModuleLoad() {
        [...]

        /**
        * Declare a local 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");
            }
        });

        [...]
    }
               

Conversations are message exchanges which are between a single client and a service. They are a fundmentally important concept in ErraiBus, since by default, a message will be broadcast to all client services listening on a particular channel.

When you create a conversation with an incoming message, you ensure that the message you are sending back is received by the same client which sent the incoming message. A simple example:

   @Service
    public class HelloWorldService implements MessageCallback {

        private MessageBus bus;

        @Inject
        public HelloWorldService(MessageBus bus) {
            this.bus = bus;
        }

        public void callback(CommandMessage message) {
                // Send a message to the 'HelloWorldClient' on the client that sent us the
                // the message.
                MessageBuilder.createConversation(message)
                    .toSubject("HelloWorldClient")
                    .signalling()
                    .with("text", "Hi There! We're having a conversation!")
                    .noErrorHandling()
                    .sendNowWith(bus);
            });
        }
    }

Note that the only difference between the example in the previous section (2.4) and this is the use of the createConversation() method with MessageBuilder.

MessageBuilder.createMessage()
       .toSubject("ObjectService").signalling()
       .with(MessageParts.ReplyTo, "ClientEndpoint")
       .noErrorHandling().sendNowWith(bus);

MessageBuilder.createConversation(message)
                .subjectProvided().signalling()
                .with("Records", records)
                .noErrorHandling().sendNowWith(bus);

Broadcasting messages to all clients listening on a specific subject is quite simple and involves nothing more than forgoing use of the conversation API. For instance:

MessageBuilder.createMessage().
                 .toSubject("MessageListener")
                 .with("Text", "Hello, from your overlords in the cloud")
                 .noErrorHandling().sendNowWith(bus);

If sent from the server, all clients currently connected, who are listening to the subject "MessageListener" will receive the message. It's as simple as that.

Communication from one client to another client is not directly possible within the bus federation, by design. This isn't to say that it's not possible. But one client cannot see a service within the federation of another client. We institute this limitation as a matter of basic security. But many software engineers will likely find the prospects of such communication appealing, so this section will provide some basic pointers on how to go about accomplishing it.

...
public void callback(Message message) {
    String sessionId = ServerBusUtils.getSessionId(message);

    // Record this sessionId somewhere.
    ...
}
...

MessageBuilder.createMessage()
    .toSubject("ClientMessageListener")
    .signalling()
    .with(MessageParts.SessionID, sessionId)
    .with("Message", "We're relaying a message!")
    .noErrorHandling().sendNowWith(bus);

ErraiBus provides facility to making asynchronous RPC calls on-top of the bus archhitecture without the need to explicitly declare services or any specific mapping or boilerplate code. This method of communicating with the server is straight-forward and utilizes the simple RemoteCall API.

Remote procedure calls can be be performed against against service class which has been annoted with the @Service annotation and the accompanying method which is being called has been annotated with the @Endpoint annotation, and the method has public access.

@Service
public class QueryService {
   private Map<String, String[]> dataMap;

   public QueryService() {
      setupMap();
   }

   private void setupMap() {
      dataMap = new HashMap<String, String[]>();
      dataMap.put("beer", new String[]{"Heineken", "Budweiser", "Hoogaarden"});
      dataMap.put("fruit", new String[]{"Apples", "Oranges", "Grapes"});
      dataMap.put("animals", new String[]{"Monkeys", "Giraffes", "Lions"});
   }

   @Endpoint
   public String[] getQuery(String queryString) {
      return dataMap.get(queryString.toLowerCase());
   }
}

Notice the @Endpoint annotation on the getQuery() method in the above figure. In this example, the method simply accepts a single String parameter and returns an array of Strings. The method can accept and return any serializable types that have been exposed to the bus within the rules of serializability as laid out in the section on Object Serialization.

Also note that in this example, the service class is not required to implement the MessageCallback interface and is a simple POJO class.

Calls to RPC endpoints are made using the RemoteCall API which is very similar to the MessageBuilder API, with a few key differences. Here is some code for calling the RPC endpoint we defined in section 3.1.

MessageBuilder.createCall()
           .call("QueryService")                                         // (1)
           .endpoint("getQuery", queryBox.getText())                     // (2)
           .respondTo(String[].class, new RemoteCallback<String[]>() {   // (3)
               public void callback(String[] resultsString) {
                   if (resultsString == null) {
                       resultsString = new String[]{"No results."};
                   }

                   /**
                    * Build an HTML unordered list based on the results.
                    */
                   StringBuffer buf = new StringBuffer("<ul>");
                   for (String result : resultsString) {
                       buf.append("<li>").append(result).append("</li>");
                   }
                   results.setHTML(buf.append("</ul>").toString());
               }
           })
           .noErrorHandling()
           .sendNowWith(bus);                                           // (4)

In this example we (1) send a call to the "QueryService" class with (2) the endpoint "getQuery", which is the name of the method which we annotated, along with the parameter we which to pass to the method. Note that you can send as many parameters as you want as the endpoint() method accepts varargs parameter.

Then (3) we declare a RemoteCallback to handle the response back from the server. We declare the response type to be that of String[] to correlate with the return type of the endpoint on the server and fill in handling code for the response. In this case we output an HTML unordered list manually.

Finally (4) we send the call.

Depending on what application server you are deploying on, you must provide an appropriate servlet implementation if you wish to use true, asynchronous I/O.

Here's a sample web.xml file:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
		  http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>ErraiServlet</servlet-name>
        <servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>ErraiServlet</servlet-name>
        <url-pattern>*.erraiBus</url-pattern>
    </servlet-mapping>

    <context-param>
        <param-name>errai.properties</param-name>
        <param-value>/WEB-INF/errai.properties</param-value>
    </context-param>

    <context-param>
        <param-name>login.config</param-name>
        <param-value>/WEB-INF/login.config</param-value>
    </context-param>

    <context-param>
        <param-name>users.properties</param-name>
        <param-value>/WEB-INF/users.properties</param-value>
    </context-param>

</web-app>

The ErraiService.properties file contains basic configuration for the bus itself.

Example Configuration:

##
## Request dispatcher implementation (default is SimpleDispatcher)
##
#errai.dispatcher_implementation=org.jboss.errai.bus.server.SimpleDispatcher
errai.dispatcher_implementation=org.jboss.errai.bus.server.AsyncDispatcher


#
## Worker pool size.  This is the number of threads the asynchronous worker pool should provide for processing
## incoming messages. This option is only valid when using the AsyncDispatcher implementation.
##
errai.async.thread_pool_size=5

##
## Worker timeout (in seconds).  This defines the time that a single asychronous process may run, before the worker pool
## terminates it and reclaims the thread.   This option is only valid when using the AsyncDispatcher implementation.
##
errai.async.worker.timeout=5

##
## Specify the Authentication/Authorization Adapter to use
##
#errai.authentication_adapter=org.jboss.errai.persistence.server.security.HibernateAuthenticationAdapter
#errai.authentication_adapter=org.jboss.errai.bus.server.security.auth.JAASAdapter

##
## This property indicates whether or not authentication is required for all communication with the bus.  Set this
## to 'true' if all access to your application should be secure.
##
#errai.require_authentication_for_all=true

The ErraiApp.properties is a marker file. It does not contain any configuration, but it is required that it be present in any module you wish Errai to scan for deployable extensions and services. It should be located as the top-level directory of any JAR or Directory-based module.

It's good to start with an explanation of the basic workspace concepts and terminlogy that we chose for it.

A workspace, in our term, is basically a collection of tools. Each tool serves a distinct purpose and can represent anything you like. The workspace manages the tools (or tool sets) and access to them. This includes loading and initialization, history, preferences and authorization amongst other things. Usually tools rely on the message bus for inter component communication as well as backend integration. But they are not tight to that. Workspaces makes no assumption about the implementation of your tool, it merely provides the glue to keep everything together.

Workspaces goes beyond simple API. It's not just another GWT module. It was designed to get you started quickly, without getting in your way. This includes the environment to build, deploy and test your tools. We've decided to use maven to provide these capabilities. It allows you to quickly get started (see Maven archetype), but more importantly, maven repositories are used to share tool implementations across workspace assemblies. This way you can easily combine your own and 3rd party tools as part of a custom workspace compilation.

Tools are declared through the @LoadToolSet annotation. This instructs the workspace to generate all the boiler plate to wire your tools with the workspace. A tool needs to implement the WidgetProvider interface. It's used by the workspace to instruct the tool to create it's UI widget when needed. This widget will then be embedded in the workspace.

@LoadTool(name = "Users", group = "Administration")                          (1)
public class UserManagement implements WidgetProvider
{

  public void provideWidget(final ProvisioningCallback callback) {           (2)
    callback.onSuccess(new UserManagementWidget());
  }

  class UserManagementWidget extends LayoutPanel                             (3)
  {
      [...]
  }
}
  

Workspaces relies on a authentication scheme similiar to JAAS. It ships with different authentication modules (i.e. Hibernate, JAAS) that enable role based access to tools on the client side and services on the server side.

@LoadTool(name = "Inventory", group = "Administration")                (1)
@RequireRoles({"admin"})                                               (2)
public class Inventory implements WidgetProvider
{

    public void provideWidget(final ProvisioningCallback callback)     (3)
    {
        [...]
    }

}

It's common to use the WidgetProvider API in a way that GWT 2.0 code splitting can kick in. This allows true lazy loading of tools upon demand, including all .js and resources necessary to run your tools:

@LoadTool(name = "Group Tasks", group = "Tasks")
public class OpenTasksModule implements WidgetProvider
{
    static OpenTasksView instance = null;

    public void provideWidget(final ProvisioningCallback callback)
    {
        GWT.runAsync(
            new RunAsyncCallback()
            {
              public void onFailure(Throwable err)
              {
                GWT.log("Failed to load tool", err);
              }

              public void onSuccess()
              {
                if (instance == null) {
                  instance = new OpenTasksView();  // your tool here
                }
                callback.onSuccess(instance);
              }
            }

        );
    }
}

The workspace registry (org.jboss.errai.workspaces.client.framework.Registry) is a simple all purpose lookup for common workspace API that is available to any workspace component:

AuthenticationContext authenticationContext =
    Registry.get(SecurityService.class).getAuthenticationContext();    

The workspace itself doesn't provide an authentication component. Instead it relies on the Authentication provided by errai bus. When the workspace is loaded two thing happen: The workspace checks if authentication is required and, after authentication if needed, loads the tool sets.

The bus component in charge is the SecurityService (org.jboss.errai.bus.client.security.SecurityService). It is available through workspace Registry. For people extending the workspace functionality it offers two intersting options:

The later is important of you want to provide your own way of authenticating users, but still use the role based authorization build into workspaces.

The LoginClient is the counter part of the SecurityService. It is instructed by the SecurityService to request the credentials upon demand. This typically happens when the workspace is initialized, but might also occur later on, when a particular service requires a different role set, then the one assigned initially. We call this elevation. Similiar to the operating system of your choice that demands administrator priviledges for certain operations.

After the initial authentication (or lack of) the LoginClient instructs the actual workspace to assemble the tool sets.

History is build into the workspace. It's wired to the main navigation and allows to use the browser navigation to switch between previously selected tools. In addition to that, the same mechanism can be used to perma link tools from external applications. I.e. when notifying users, using an email that contains a link back to a particular tool.

The workspace allows you to store simple key-value pairs as preferences. Like with other common API, you obtain the Preferences through the workspace Registry. The default implementation uses a cookie based approach, but it's easy to replace that one with a custom implementation in the module decriptor:

    
   <module>
    [...]
    <replace-with class="org.jboss.errai.workspaces.client.framework.CookiePreferences">
           <when-type-is class="org.jboss.errai.workspaces.client.framework.Preferences"/>
       </replace-with>
    </module>
    

You need Apache Maven and a JDK to get started.

The most simple (and least error prone) way to get started is using the maven archetype that we ship as part of errai. Simply follow the instructions in the quickstart section and return here when you are done.

Once you've created a project using the maven archetype, make yourself familiar with the directory structure:

Laika:gwt-app hbraun$ lstree
| pom.xml    
|-src
|---main
|-----java
|-------foo
|---------bar
|-----------client
|-----------server
|-war
|---WEB-INF

It basically follows the default GWT guidelines for breaking up code between client and server. Simply put tools (@LoadToolSet) into the client subpackage and services (@Service) into the server subpackages. Make sure you are familiar with the Workspace API before you continue.

Several configuration files drive a workspace build and the final application. Make sure to include all of them when porting the archetype example to a different GWT application:

 ./src/main/java/ErraiApp.properties
 ./src/main/java/ErraiService.properties
 ./src/main/java/my/app/App.gwt.xml   

If you followed the steps above, and did build your application stub using the maven archetype, then you should be launch the GWT hosted mode with the following commands:

  mvn gwt:run

 (alternatively)   
  mvn gwt:debug