Module it.rebirthproject.ufoeb
Package it.rebirthproject.ufoeb.architecture.eventbus

Interface EventBus

All Known Implementing Classes:
UfoEventBus
public interface EventBus
UFO EventBus is a publish/subscribe event system. Events are posted to the bus (post(Object)), which delivers them to subscribers (listeners) that have a matching handler method for the event type. To receive events, listeners must register themselves to the bus using register(Object). Once registered, listeners receive events until unregister(Object) is called. Event handling methods of listeners must be annotated by Listen, must be public, return nothing (void), and have exactly one parameter (the event).

Example: 

 Class MagazineReader wants to receive MagazineNews events, so this could be a stub of the class:

 public class MagazineReader {
      @Listen
      public void listenOnMagazineNews(MagazineNewsEvent event) {
          System.out.println("A news arrived: " + event.getNews());
      }
 }

 Class MagazineNewsEvent can be a simple POJO used to carry event's metadata, like this one:

 public class MagazineNewsEvent {

      private final String newsMessage;

      public MagazineNewsEvent(String newsMessage) {
          this.newsMessage = newsMessage;
      }

      public String getNews() {
          return newsMessage;
      }
 }

 The MagazineReader instance must be registered to EventBus to receive news in his listenOnMagazineNews method.

 public static void main(String ... args) {
     MagazineReader magazineReader = new MagazineReader();
     eventBus.register(magazineReader);
     ...
     eventBus.post(new MagazineNewsEvent("Hello Readers!!! Something new just happened..."));
     ...
 }

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Future<Boolean>
    isRegistered(Object possibleRegisteredListener)
    Checks if the passed object is already registered in the eventbus for listening to events.
    void
    post(Object event)
    Posts the given event to the eventbus.
    void
    postSticky(Object event)
    Posts the given event to the eventbus that saves it (because it's sticky).
    void
    printBusState()
    Tells the bus to log its memory state for debug pourpose.
    void
    register(Object listenerToRegister)
    Registers a listener to the eventbus to receive specific events.
    void
    removeAllSticky()
    Removes all the sticky events from eventbus.
    void
    removeSticky(Class<?> eventClass)
    Removes a sticky event from the eventbus given the event type.
    void
    removeSticky(Object event)
    Removes a sticky event from the eventbus.
    void
    shutdownBus()
    Shutdown the eventbus infrastructure.
    void
    unregister(Object listenerToUnregister)
    Unregisters the given listener from the eventbus.

  • Method Details

    • register

      void register(Object listenerToRegister) throws EventBusException
      Registers a listener to the eventbus to receive specific events. Listeners must call unregister(Object) once they are no longer interested in receiving events. Listeners event handling methods must be annotated with the Listen annotation.
      Parameters:
      listenerToRegister - The listener to register
      Throws:
      EventBusException - If the listener is null or something fails while registering

    • unregister

      void unregister(Object listenerToUnregister) throws EventBusException
      Unregisters the given listener from the eventbus.
      Parameters:
      listenerToUnregister - The listener to unregister
      Throws:
      EventBusException - If the given listener is null or something fails while unregistering
      See Also:

    • post

      void post(Object event) throws EventBusException
      Posts the given event to the eventbus. This event will always be notified to and listened by registered listeners. Depending on which inheritance policy is chosen during bus initialization and on which event class/interface is listened by the listeners, listeners could get other events too. For example if an event extends a superclass or implements an interface. For a detailed explanation about inheritance policies refers to EventBusBuilder documentation
      Parameters:
      event - The event to post
      Throws:
      EventBusException - If the event is null or some internal error occurs while posting the event

    • postSticky

      void postSticky(Object event) throws EventBusException
      Posts the given event to the eventbus that saves it (because it's sticky). Once new listeners register to the same sticky event they will be notified about the sticky event on registration. In this way it's possible to not lose events which are being already sent before the listener is being registered.
      Parameters:
      event - The 'sticky' event to post
      Throws:
      EventBusException - If the sticky event is null or some internal error occurs while posting the sticky event

    • removeSticky

      void removeSticky(Object event) throws EventBusException
      Removes a sticky event from the eventbus.
      Parameters:
      event - The sticky event to remove
      Throws:
      EventBusException - If the sticky event is null or some internal error occurs while posting the sticky event
      See Also:

    • removeSticky

      void removeSticky(Class<?> eventClass) throws EventBusException
      Removes a sticky event from the eventbus given the event type.
      Parameters:
      eventClass - The class of a sticky event to remove
      Throws:
      EventBusException - If the class of the sticky event to remove is null or some internal error occurs while posting the sticky event
      See Also:

    • removeAllSticky

      void removeAllSticky() throws EventBusException
      Removes all the sticky events from eventbus.
      Throws:
      EventBusException - If some error occurs while removing all the sticky events

    • printBusState

      void printBusState() throws EventBusException
      Tells the bus to log its memory state for debug pourpose.
      Throws:
      EventBusException

    • shutdownBus

      void shutdownBus()
      Shutdown the eventbus infrastructure. This is needed to free memory and to stop background workers behind the scenes. Note: Make sure to call this method when there is no more need for an eventbus in your application, so this can be usually done before the application shutdown.

    • isRegistered

      Future<Boolean> isRegistered(Object possibleRegisteredListener) throws EventBusException
      Checks if the passed object is already registered in the eventbus for listening to events.
      Parameters:
      possibleRegisteredListener - An object which represents a possible registered listener
      Returns:
      A future wrapping a boolean value which will be true if the object passed to the method is a listener for some events or false otherwise
      Throws:
      EventBusException - If the possibleRegisteredListener is null or some error occurs during isRegistered method execution
      See Also: