It all starts with the EventBus

#EventBus The EventBus is the core and key component of our framework. An Event is an object that informs the corresponding event handler (also called Listeners in Swing etc.) that something has changed. Events can be fired along an EventBus. That means, that the fired Event will be dispatched / delivered to any registered event handler. The EventBus takes care for you to dispatch the Event correctly. So you don't need to code your own solution (Event-dispatching, handler-managing, etc.) by hand for every component that is traditionally observed by an observer (also called Listener or in our context “event handler”). See wikipedia's explanation of the traditional observer pattern.

#Event Now you should have an idea why an EventBus is a good idea. Now lets take a look how to define a Event. This is simply done by defining your own event-class that derived from com.mvplite.event.Event. So take a look at this:

public class UnreadCountChangedEvent extends Event {

	private final int newUnradCount;
	
	public UnreadCountChangedEvent(int newUnreadCount){
		this.newUnradCount = newUnreadCount;
	}
	
	public int getUnreadCount(){
		return newUnradCount;
	}

}

Like the name says the UnreadCountChangedEvent is fired to inform that the count of unread mails in the users inbox has been changed, because e.g. the user has marked an mail as read or unread.

#EventHandler The last question we have to answer is how do we define an event handler. We found a simple and elegant solution to do this with the help of java annotations. Let's assume we have a class MyClass that wants to get informed about changes on the unread mail count. In other words: MyClass wants to receive UnreadCountChangedEvents. So MyClass must be an EventHandler. This is realized in our framework without writing to much boilerplate code. Simply define a method in MyClass that has exactly one parameter with the type of your Event your want receive and mark it with the @EventHandler Annotation. Register MyClass on the EventBus as an event handler and you are done.

public class MyClass {

	public MyClass(EventBus eventBus){
		// Register this instance as EventHandler on the EventBus
		eventBus.addHandler(this);
	}

	@EventHandler
	public void onUnreadCountChanged(UnreadCountChangedEvent e){
		// Do something useful with e.getUnreadCount();
	}
	
}

Yes that's all :) Let's explain it step by step: You register this instance of MyClass on the EventBus by calling EventBus.addHandler(Object handler). By calling addHandler() the EventBus will scan MyClass for methods that are tagged with @EventHandler. If a method with @EventHandler has been found the method must have exactly one parameter that defines for which Event this method is the EventHandler for. By the way: the name of the method doesn't matter. Check this:

public class MyClass {

	public MyClass(EventBus eventBus){
		// Register this instance as EventHandler on the EventBus
		eventBus.addHandler(this);
	}

	@EventHandler // A valid handler for UnreadCountChangedEvents
	public void onUnreadCountChanged(UnreadCountChangedEvent e){ }
	
	@EventHandler // A valid handler for UnreadCountChangedEvents
	public void onFoo( UnreadCountChangedEvent e){ }

	@EventHandler // Invalid, because no parameter
	public void  onUnreadCountChanged(){ }

	@EventHandler // Invalid, because exactly 1 parameter is required
	public void  onUnreadCountChanged( UnreadCountChangedEvent e, int a){ }

	@EventHandler // A valid Handler for AnotherEvent
	public void onAnother(AnotherEvent e) { }
	
}

---

Read next: Model-View-Presenter: The Basics