JVx Reference, Events
Let's talk about events and event handling in JVx.
What are events...
Events are an important mechanism no matter to what programming language or framework you turn to. It allows us to react on certain actions and "defer" actions until something triggered them. Such triggers can be anything, like a certain condition is hit in another thread, the user clicked a button or another action has finally finished. Long story short, you get notified that something happened, and that you can now do something.
...and why do I need to handle them?
Well, you can't skip events, they are a cornerstone of JVx. Theoretically, you could use JVx without using any of its events, but you would not only miss out on a lot of functionality but also be unable to do anything useful. But don't worry, understanding the event system is easy, using it even easier.
Terminology
For JVx the following terminology applies: An event is a property of an object, you can register listeners on that event which will get invoked if the event is dispatched (fired). Every event consists of the EventHandler class which allows to register, remove and manage the listeners and also dispatches the events, meaning invoking the listeners and notifying them that the event occurred. There is no single underlying listener interface.
Within the JVx framework, every event-property of an object does start with the prefix "event" to make it easily searchable and identifiable. But enough dry talk, let's get started.
Attaching listeners as class
The easiest way to get notified of events is to attach a class (which is implementing the listener interface) to an event as listener, like this:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener(new ActionListener());
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
}
private static final class ActionListener implements IActionListener
{
public void action(UIActionEvent pActionEvent) throws Throwable
{
System.out.println("Button clicked!");
}
}
Attaching listeners as inlined class
Of course we can inline this listener class:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener(new IActionListener()
{
public void action(UIActionEvent pActionEvent) throws Throwable
{
System.out.println("Button clicked!");
}
});
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
}
Attaching listeners JVx style
So far, so normal. But in JVx we have support to attach listeners based on reflection, like this:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener(this, "doButtonClick");
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
public void doButtonClick(UIActionEvent pActionEvent) throws Throwable
{
System.out.println("Button clicked");
}
}
What is happening here is that, internally, a listener is created which references the given object and the named method. This allows to easily add and remove listeners from events and keeping the classes clean by allowing to have all related event listeners in one place and without additional class definitions.
Attaching listeners as lambdas
Yet there is more, we can of course attach lambdas to the events as listeners, too:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener((pActionEvent) -> System.out.println("Button clicked"));
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
}
Attaching listeners as method references
And last but not least, thanks to the new capabilities of Java 1.8, we can also use method references:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener(this::doButtonClick);
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
private void doButtonClick(UIActionEvent pActionEvent) throws Throwable
{
System.out.println("Button clicked");
}
}
Parameters or no parameters? To throw or not to throw?
By default we actually support two different classes of listeners, the specified event/listener interface itself, and (javax.rad.util.)IRunnable. Which means that you can also attach methods which do not have any parameters, like this:
{
public MainFrame()
{
super();
UIButton button = new UIButton("Click me!");
button.eventAction().addListener(this::doButtonClickNoParameters);
button.eventAction().addListener(this::doButtonClickWithParameters);
setLayout(new UIBorderLayout());
add(button, UIBorderLayout.CENTER);
}
private void doButtonClickNoParameters() throws Throwable
{
System.out.println("Button clicked");
}
private void doButtonClickWithParameters(UIActionEvent pActionEvent) throws Throwable
{
System.out.println("Button clicked");
}
}
Additionally, all listeners and IRunnable itself do support to throw Throwable, which is then handled inside the EventHandler. So you are very flexible when it comes to what methods you can attach and use as listeners.
Creating your own events
You can, of course, create your own EventHandlers and listeners to create your own events. All you need are two classes, an extension of EventHandler and a listener interface.
{
public CustomEvent()
{
super(ICustomListener.class);
}
}
public interface ICustomListener
{
public void somethingHappened(String pName);
}
And that's it, from here on you can use it:
event.addListener((pName) -> System.out.println(pName + " 1"));
event.addListener((pName) -> System.out.println(pName + " 2"));
event.addListener((pName) -> System.out.println(pName + " 3"));
event.dispatchEvent("Adam");
More methods!
You can also use an interface for listeners which has multiple methods, specifying in the constructor which method to invoke:
{
public CustomEvent()
{
super(ICustomListener.class, "somethingOtherHappened");
}
}
public interface ICustomListener
{
public void somethingHappened(String pName);
public void somethingOtherHappened(String pName, BigDecimal pValue);
public void nothingHappened();
}
Now every time the event is dispatched, the somethingOtherHappened method will be invoked. Anyway, don't use this. The upside of having a "simple" listener interface with just one method (SAM-type) is that it allows to use lambdas with it. A listener interface with multiple methods won't allow this.
In JVx we reduced our listener interfaces to just one method (in a backward compatible way) to make sure all events can be used with lambdas.
Fire away!
That's it for this short reference sheet, that is how our event system can and should be used. Of course, there is much more to it under the hood, for example listeners being wrapped in proxy classes, reflection used for invoking methods and some more stuff. If you feel adventurous, be my guest and have a good look at the internals of EventHandler, it is quite an interesting read.
API, Development, Information | rzenz | 03/11/2016 | 
Comments (0)
RSS-Feed