Errai: The browser as a platform

Monday, October 7, 2013

More Errai Basics -- Climb on the Magic Message Bus!

In my last post, I talked about Errai CDI Events and began showing how they can be used to implement part of a typical lobby page for a multiplayer web-game. Near the end we encountered a typical use case that could not be handled by Events. As promised, I will now discuss how the Errai Message Bus can be used by the server to target a subset of the connected clients.

The Problem

To quickly recap: we have a set of clients in a game room lobby. We want Client A to invite Client B to a game. We've already figured out how to send an invitation event from Client A to the server, but we need a way to relay this invitation to Client B without broadcasting it to all the other clients.

Some Message Bus Basics

Service Endpoints

The Errai Message Bus is used to send messages between service endpoints. Defining a service endpoint requires only two things:
  1. Subject: A string (not necessarily unique), used by senders to address messages to this endpoint
  2. Callback: A method to be invoked by Errai when a message to this endpoint is received
When an endpoint is created we say that code has subscribed to the given subject. It is possible to dynamically define service endpoints, but as with most features of the framework the declarative syntax is preferable. Here is an example declaring a service in Errai.

It is also possible to annotate methods, such that a class may offer multiple services.

Sending a Message

To send a message we construct it with the MessageBuilder and then send it with the MessageBus like so.

It is possible to send objects with a message by adding parts. In the following example we will send a Greeting object to everyone subscribed to the subject "LonelyPeople".

Message Visibility

As with Errai CDI Events, there is only one degree of visibility of message. If the server sends a message to the subject "ErraiLovers", every subscriber to this subject will receive the message. But if a client sends a message to "ErraiLovers", only subscribers on that same client and the server will receive it.

Back to the Lobby

As you may have already guessed, a simple way to deliver messages to a single client is to dynamically subscribe them to a unique service endpoint.

Using Unique Ids

Here is the simple model used in Errai Block Drop that can be used to establish a direct line of communication to a single client.
  1. When a client first joins the lobby in Block Drop, they fire a CDI Event to the server
  2. The server generates a unique id and adds the client to the lobby
  3. The server fires back the unique id using a Conversational Event (which will only be observed by the original client)
  4. The client observes the event and subscribes to the subject "clientid" where id is the unique id received from the server
(For those who prefer the concrete, here are the implementations of this pattern in block-drop: server sideclient side, and shared code. You'll note that the client side code uses dynamic subscription, since the client's unique id cannot be known at compile time.)

Finishing the Invitation

With services based on unique ids setup for each player, it is now possible for server to target individual players in an invitation by accessing their unique ids. The relayed invitations are sent using the MessageBuilder as previously demonstrated. (Once again, here is the Block Drop implementation.)

Final Note

I hope this helps you to understand the power and flexibility that the Errai Bus provides. This is just one example out of the plethora of potential use cases that the Message Bus could fulfill. When you want the loose-coupling of CDI Events, but need a more fine-grained (or dynamic) control over recipients, Errai Messaging might be the right fit for the job.


  1. Latest version of the errai-tutorial does not work for "Code and Refresh" model. The command "mvn gwt:run" does not actually start the web server in windows 8 PC. Please help me get started with Errai!

    1. Gopinath, I encourage you to try asking for help on our community forum ( If you are able to offer some more details of what you've tried there, it's much more likely that I or someone else will be able to assist you.

  2. Very interesting information here I can find. This article interested me very much.

    Accommodation in world

  3. I'm very happy being Herpes free now. It was a sad incident that was announced to me after the check up in the hospital and I was diagnosed of HSV 2. I thank God now for using Dr.odey Abang to cure my virus. I'm not ashamed to say this because no virus of such can be detected in me. I'm Charlotte from Columbia. I thought about it many Times when I heard about this Herbal cures for Herpes. I was really happy when I came across blogs of comments of Doctors who run cures sicknesses and was comfortable to try Dr. Abang from patients testimony I came across here on my online page. I knew now they are real Africa herbalists who run cures for Herpes. There's every opportunity to be cure with natural herbs, because all medical prescriptions are derived from herbs and roots. Its really hard time living with Herpes on drugs which can't get you cure. I tried this and I can boost of myself now as a woman. I need to be loved not to lost, get your instant cure to all sicknesses from Dr, Odey Abang.
    He cures HSV,HPV,Cancer,low spam count and much more from the evidence I saw 💯 % sure no site effects with active immune booster

    Email him for you cure

  4. Nothing is not possible in this word.
    Herpes I cried out for 8moths had a cure and was making use of the Medication that never wanted a life living on drugs, I applied Antibiotics, he prescribed for me the acyclovir(Zovirax), famciclovir (Famvir), andvalacyclovir (Valtrex).
    They never get me cured.
    My God keep blessing you and your Family. Dr
    ODEY ABANG, your a powerful Herbalist fir your work in my life
    I wish you know how I feel inside me when I was making use of does tablets that never could there get me cured. I had to search about some of my favourite blogs when I thought about Dr Odey abang from the testimonies of patients and I remember a friend who told me I should try Dr. Odey Abang herbal medicine. He told me the man can cure me,but was shy and feel its dirty taking in herbs made with African herbalists.
    You need to know I would have been cured before now since I knew him then, but still interested in letting you that was my punishment.
    Thanks reading my article, feel good and not make my mistake, I love testimonies and explanations of the new beginning is all I hope for
    Think about your live and use herbs to get you cured of your challenge on
    His email is for you so you speak to him
    WhatsApp number +2349015049094