java.beans
public class EventHandler extends Object implements InvocationHandler
EventHandler forms a bridge between dynamically created listeners and arbitrary properties and methods.
You can use this class to easily create listener implementations for
some basic interactions between an event source and its target. Using
the three static methods named create you can create
these listener implementations.
See the documentation of each method for usage examples.
Since: 1.4
| Constructor Summary | |
|---|---|
| EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName)
Creates a new EventHandler instance.
| |
| Method Summary | |
|---|---|
| static <T> T | create(Class<T> listenerInterface, Object target, String action) Constructs an implementation of You can use such an implementation to simply call a public no-argument method of an arbitrary target object or to forward the first argument of the listener method to the target method. Call this method like:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, target, "dispose"));
to achieve the following behavior:
button.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent ae) {
target.dispose();
}
});
That means if you need a listener implementation that simply calls a a no-argument method on a given instance for each method of the listener interface. Note: The |
| static <T> T | create(Class<T> listenerInterface, Object target, String action, String eventPropertyName) Constructs an implementation of Use this method if you want to create an implementation that retrieves a property value from the first argument of the listener method and applies it to the target's property or method. |
| static <T> T | create(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName) Constructs an implementation of Besides the functionality described for {@link create(Class, Object, String)} and {@link create(Class, Object, String, String)} this method allows you to filter the listener method that should have an effect. |
| String | getAction()
Returns the action method name. |
| String | getEventPropertyName()
Returns the event property name. |
| String | getListenerMethodName()
Returns the listener's method name. |
| Object | getTarget()
Returns the target object. |
| Object | invoke(Object proxy, Method method, Object[] arguments)
Invokes the EventHandler.
|
EventHandler instance.
Typical creation is done with the create method, not by knewing an EventHandler.
This constructs an EventHandler that will connect the method listenerMethodName to target.action, extracting eventPropertyName from the first argument of listenerMethodName. and sending it to action.
Throws a NullPointerException if the target
argument is null.
Parameters: target Object that will perform the action. action A property or method of the target. eventPropertyName A readable property of the inbound event. listenerMethodName The listener method name triggering the action.
Constructs an implementation of listenerInterface
to dispatch events.
You can use such an implementation to simply call a public no-argument method of an arbitrary target object or to forward the first argument of the listener method to the target method.
Call this method like:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, target, "dispose"));
to achieve the following behavior:
button.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent ae) {
target.dispose();
}
});
That means if you need a listener implementation that simply calls a a no-argument method on a given instance for each method of the listener interface.
Note: The action is interpreted as a method name. If your target object
has no no-argument method of the given name the EventHandler tries to find
a method with the same name but which can accept the first argument of the
listener method. Usually this will be an event object but any other object
will be forwarded, too. Keep in mind that using a property name instead of a
real method here is wrong and will throw an ArrayIndexOutOfBoundsException
whenever one of the listener methods is called.
The EventHandler will automatically convert primitives
to their wrapper class and vice versa. Furthermore it will call
a target method if it accepts a superclass of the type of the
first argument of the listener method.
In case that the method of the target object throws an exception
it will be wrapped in a RuntimeException and thrown out
of the listener method.
In case that the method of the target object cannot be found an
ArrayIndexOutOfBoundsException will be thrown when the
listener method is invoked.
A call to this method is equivalent to:
create(listenerInterface, target, action, null, null)
Parameters: listenerInterface Listener interface to implement. target Object to invoke action on. action Target property or method to invoke.
Returns: A constructed proxy object.
Constructs an implementation of listenerInterface
to dispatch events.
Use this method if you want to create an implementation that retrieves a property value from the first argument of the listener method and applies it to the target's property or method. This first argument of the listener is usually an event object but any other object is valid, too.
You can set the value of eventPropertyName to "prop"
to denote the retrieval of a property named "prop" from the event
object. In case that no such property exists the EventHandler
will try to find a method with that name.
If you set eventPropertyName to a value like this "a.b.c"
EventHandler will recursively evaluate the properties "a", "b"
and "c". Again if no property can be found the EventHandler
tries a method name instead. This allows mixing the names, too: "a.toString"
will retrieve the property "a" from the event object and will then call
the method "toString" on it.
An exception thrown in any of these methods will provoke a
RuntimeException to be thrown which contains an
InvocationTargetException containing the triggering exception.
If you set eventPropertyName to a non-null value the
action parameter will be interpreted as a property name
or a method name of the target object.
Any object retrieved from the event object and applied to the target will converted from primitives to their wrapper class or vice versa or applied to a method that accepts a superclass of the object.
Examples:
The following code:
button.addActionListener(
new ActionListener() {
public void actionPerformed(ActionEvent ae) {
Object o = ae.getSource().getClass().getName();
textField.setText((String) o);
}
});
Can be expressed using the EventHandler like this:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, textField, "text", "source.class.name");
As said above you can specify the target as a method, too:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, textField, "setText", "source.class.name");
Furthermore you can use method names in the property:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, textField, "setText", "getSource.getClass.getName");
Finally you can mix names:
button.addActionListener((ActionListener)
EventHandler.create(ActionListener.class, textField, "setText", "source.getClass.name");
A call to this method is equivalent to:
create(listenerInterface, target, action, null, null)
Parameters: listenerInterface Listener interface to implement. target Object to invoke action on. action Target property or method to invoke. eventPropertyName Name of property to extract from event.
Returns: A constructed proxy object.
Constructs an implementation of listenerInterface
to dispatch events.
Besides the functionality described for {@link create(Class, Object, String)}
and {@link create(Class, Object, String, String)} this method allows you
to filter the listener method that should have an effect. Look at these
method's documentation for more information about the EventHandler's
usage.
If you want to call dispose on a JFrame instance
when the WindowListener.windowClosing() method was invoked use
the following code:
EventHandler.create(WindowListener.class, jframeInstance, "dispose", null, "windowClosing");
A NullPointerException is thrown if the listenerInterface
or target argument are null.
Parameters: listenerInterface Listener interface to implement. target Object to invoke action on. action Target method name to invoke. eventPropertyName Name of property to extract from event. listenerMethodName Listener method to implement.
Returns: A constructed proxy object.
EventHandler.
This method is normally called by the listener's proxy implementation.
Parameters: proxy The listener interface that is implemented using the proxy mechanism. method The method that was called on the proxy instance. arguments The arguments which where given to the method.
Throws: Throwable NoSuchMethodException is thrown when the EventHandler's
action method or property cannot be found.