Gwt-Platform event best practices

A newer version of this blog post is available here.

As we worked through enhancing the way events were handled in Gwt-Platform, we came across one constatation, no common pattern was used or encouraged. This post addresses this issue and offers a little tutorial about how to create custom events in Gwt-Platform.

First of all, an event contains two major parts: the Event class itself and an Handler. Those two parts can either sit in different files or be included in the same file, with the Handler nested inside the Event. The second approach is our favorite since Handler is an interface related to an event. Also, it can be done in a few lines and reduce the total number of files.

Give that, here’s how we write our events:

public class ShowMessageEvent extends
    GwtEvent<ShowMessageEvent.ShowMessageHandler> {
  public interface ShowMessageHandler extends EventHandler {
    void onShowMessage(ShowMessageEvent event);
  }

  private static Type<ShowMessageHandler> TYPE = new Type<ShowMessageHandler>();

  public static void fire(HasEventBus source, String message) {
    if (TYPE != null) {
      source.fireEvent(new ShowMessageEvent(message));
    }
  }

  public static Type<ShowMessageHandler> getType() {
    return TYPE;
  }

  private final String message;

  public ShowMessageEvent(final String message) {
    this.message = message;
  }

  @Override
  public Type<ShowMessageHandler> getAssociatedType() {
    return TYPE;
  }

  public String getMessage() {
    return message;
  }

  @Override
  protected void dispatch(ShowMessageHandler handler) {
    handler.onShowMessage(this);
  }
}

Note here the static fire method. This is a convenient static factory method that let’s you fire an event without having to manually instantiate a ShowMessageEvent class. Using these methods is recommended rather than calling directly fireEvent. Also, the first parameter of this method is not the event bus itself, but rather the source. Passing in your presenter as the first parameter will make sure that the event is attached to the real source that triggered it. Using HasEventBus rather than GWT’s HasHandlers increases the type safety of GWTP, ensuring you never fire into a widget an event that was supposed to go on the bus.

Now that we have all the scaffolding for the event, it’s time to figure out how to use it. In Gwt-Platform every presenter implements HasEventBus so they all have the ability to fire events. The best practice approach is to simply use the static fire method of your event. In the above example this would be ShowMessageEvent.fire(this, “Hello world!”);. Some situations will require you to fire events from an object that doesn’t have access to fireEvent(). In this case, the best practice is to inject the EventBus, implement HasEventBus, and relay the call to fireEvent:

public abstract class MyCustomCallback<T> implements AsyncCallback<T>, HasEventBus {
  @Inject
  private static EventBus eventBus;

  @Override
  public void onFailure(Throwable caught) {
    ShowMessageEvent.fire(this, "Oops! Something went wrong!");
  }

  @Override
  public void fireEvent(GwtEvent<?> event) {
      eventBus.fireEvent(this, event);
  }
}

In this case we have used static injection to provide the EventBus (don’t forget to requestStaticInjection in your Gin module!). This is because AsyncCallback classes do not typically participate in dependency injection. If your class does participate in dependency injection then you should use constructor injection. The goal of this pattern is to ensure that event sources are correctly tracked. Since the callback implements HasEventBus it will set itself as the source of the event. More importantly, every class that extends this abstract class will be able to fire any event and set itself as the source.

Now, how do we listen to events travelling on the bus? If you’re listening from a presenter, the prefered way is to use addRegisteredHandler(eventType, eventHandler);. This method not only registers a handler on the event bus, it also makes sure that every registered handler is correctly unregistered when the presenter is unbound. If you are not within a presenter, inject the EventBus and call eventBus.addHandler(eventType, eventHandler);. It is customary to use an anonymous inner class as an eventHandler, for example:

public abstract class MyPresenter extends PresenterImpl<MyPresenter.MyView, MyPresenter.MyProxy> {
  ...
  @Override
  public void onBind() {
    super.onBind();
    addRegisteredHandler( ShowMessageEvent.getType(), new ShowMessageHandler() {
          @Override
          void onShowMessage(ShowMessageEvent event) {
            getView().displayMessage( event.getMessage() );
          }
        } );
  }
}

But you can also use the following pattern:

public abstract class MyPresenter extends PresenterImpl<MyPresenter.MyView, MyPresenter.MyProxy>
    implements ShowMessageHandler {
  ...
  @Override
  public void onBind() {
    super.onBind();
    addRegisteredHandler( ShowMessageEvent.getType(), this );
  }

  @Override
  void onShowMessage(ShowMessageEvent event) {
    getView().displayMessage( event.getMessage() );
  }
}

I hope this post will help you design your own events, but in any case feel free to leave comments or ask questions! In a future article we will discuss how you can automatically generate most of the boilerplate using GWTP’s annotation processing classes contributed by Brendan Doherty. We will also discuss the use of the @ProxyEvent annotation and how it differs from the events described above.