Class EventHandler
- All Implemented Interfaces:
InvocationHandler
EventHandler
class provides
support for dynamically generating event listeners whose methods
execute a simple statement involving an incoming event object
and a target object.
The EventHandler
class is intended to be used by interactive tools, such as
application builders, that allow developers to make connections between
beans. Typically connections are made from a user interface bean
(the event source)
to an application logic bean (the target). The most effective
connections of this kind isolate the application logic from the user
interface. For example, the EventHandler
for a
connection from a JCheckBox
to a method
that accepts a boolean value can deal with extracting the state
of the check box and passing it directly to the method so that
the method is isolated from the user interface layer.
Inner classes are another, more general way to handle events from
user interfaces. The EventHandler
class
handles only a subset of what is possible using inner
classes. However, EventHandler
works better
with the long-term persistence scheme than inner classes.
Also, using EventHandler
in large applications in
which the same interface is implemented many times can
reduce the disk and memory footprint of the application.
The reason that listeners created with EventHandler
have such a small
footprint is that the Proxy
class, on which
the EventHandler
relies, shares implementations
of identical
interfaces. For example, if you use
the EventHandler create
methods to make
all the ActionListener
s in an application,
all the action listeners will be instances of a single class
(one created by the Proxy
class).
In general, listeners based on
the Proxy
class require one listener class
to be created per listener type (interface),
whereas the inner class
approach requires one class to be created per listener
(object that implements the interface).
You don't generally deal directly with EventHandler
instances.
Instead, you use one of the EventHandler
create
methods to create
an object that implements a given listener interface.
This listener object uses an EventHandler
object
behind the scenes to encapsulate information about the
event, the object to be sent a message when the event occurs,
the message (method) to be sent, and any argument
to the method.
The following section gives examples of how to create listener
objects using the create
methods.
Examples of Using EventHandler
The simplest use ofEventHandler
is to install
a listener that calls a method on the target object with no arguments.
In the following example we create an ActionListener
that invokes the toFront
method on an instance
of javax.swing.JFrame
.
WhenmyButton.addActionListener( (ActionListener)EventHandler.create(ActionListener.class, frame, "toFront"));
myButton
is pressed, the statement
frame.toFront()
will be executed. One could get
the same effect, with some additional compile-time type safety,
by defining a new implementation of the ActionListener
interface and adding an instance of it to the button:
The next simplest use of//Equivalent code using an inner class instead of EventHandler. myButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { frame.toFront(); } });
EventHandler
is
to extract a property value from the first argument
of the method in the listener interface (typically an event object)
and use it to set the value of a property in the target object.
In the following example we create an ActionListener
that
sets the nextFocusableComponent
property of the target
(myButton) object to the value of the "source" property of the event.
This would correspond to the following inner class implementation:EventHandler.create(ActionListener.class, myButton, "nextFocusableComponent", "source")
It's also possible to create an//Equivalent code using an inner class instead of EventHandler. new ActionListener() { public void actionPerformed(ActionEvent e) { myButton.setNextFocusableComponent((Component)e.getSource()); } }
EventHandler
that
just passes the incoming event object to the target's action.
If the fourth EventHandler.create
argument is
an empty string, then the event is just passed along:
This would correspond to the following inner class implementation:EventHandler.create(ActionListener.class, target, "doActionEvent", "")
Probably the most common use of//Equivalent code using an inner class instead of EventHandler. new ActionListener() { public void actionPerformed(ActionEvent e) { target.doActionEvent(e); } }
EventHandler
is to extract a property value from the
source of the event object and set this value as
the value of a property of the target object.
In the following example we create an ActionListener
that
sets the "label" property of the target
object to the value of the "text" property of the
source (the value of the "source" property) of the event.
This would correspond to the following inner class implementation:EventHandler.create(ActionListener.class, myButton, "label", "source.text")
The event property may be "qualified" with an arbitrary number of property prefixes delimited with the "." character. The "qualifying" names that appear before the "." characters are taken as the names of properties that should be applied, left-most first, to the event object.//Equivalent code using an inner class instead of EventHandler. new ActionListener { public void actionPerformed(ActionEvent e) { myButton.setLabel(((JTextField)e.getSource()).getText()); } }
For example, the following action listener
might be written as the following inner class (assuming all the properties had canonical getter methods and returned the appropriate types):EventHandler.create(ActionListener.class, target, "a", "b.c.d")
The target property may also be "qualified" with an arbitrary number of property prefixs delimited with the "." character. For example, the following action listener://Equivalent code using an inner class instead of EventHandler. new ActionListener { public void actionPerformed(ActionEvent e) { target.setA(e.getB().getC().isD()); } }
EventHandler.create(ActionListener.class, target, "a.b", "c.d")might be written as the following inner class (assuming all the properties had canonical getter methods and returned the appropriate types):
//Equivalent code using an inner class instead of EventHandler. new ActionListener { public void actionPerformed(ActionEvent e) { target.getA().setB(e.getC().isD()); } }
As EventHandler
ultimately relies on reflection to invoke
a method we recommend against targeting an overloaded method. For example,
if the target is an instance of the class MyTarget
which is
defined as:
public class MyTarget { public void doIt(String); public void doIt(Object); }Then the method
doIt
is overloaded. EventHandler will invoke
the method that is appropriate based on the source. If the source is
null, then either method is appropriate and the one that is invoked is
undefined. For that reason we recommend against targeting overloaded
methods.- Since:
- 1.4
- See Also:
-
Constructor Summary
ConstructorDescriptionEventHandler
(Object target, String action, String eventPropertyName, String listenerMethodName) Creates a newEventHandler
object; you generally use one of thecreate
methods instead of invoking this constructor directly. -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> T
Creates an implementation oflistenerInterface
in which all of the methods in the listener interface apply the handler'saction
to thetarget
.static <T> T
/** Creates an implementation oflistenerInterface
in which all of the methods pass the value of the event expression,eventPropertyName
, to the final method in the statement,action
, which is applied to thetarget
.static <T> T
create
(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName) Creates an implementation oflistenerInterface
in which the method namedlistenerMethodName
passes the value of the event expression,eventPropertyName
, to the final method in the statement,action
, which is applied to thetarget
.Returns the name of the target's writable property that this event handler will set, or the name of the method that this event handler will invoke on the target.Returns the property of the event that should be used in the action applied to the target.Returns the name of the method that will trigger the action.Returns the object to which this event handler will send a message.Extract the appropriate property value from the event and pass it to the action associated with thisEventHandler
.
-
Constructor Details
-
EventHandler
@ConstructorProperties({"target","action","eventPropertyName","listenerMethodName"}) public EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName) Creates a newEventHandler
object; you generally use one of thecreate
methods instead of invoking this constructor directly. Refer tothe general version of create
for a complete description of theeventPropertyName
andlistenerMethodName
parameter.- Parameters:
target
- the object that will perform the actionaction
- the name of a (possibly qualified) property or method on the targeteventPropertyName
- the (possibly qualified) name of a readable property of the incoming eventlistenerMethodName
- the name of the method in the listener interface that should trigger the action- Throws:
NullPointerException
- iftarget
is nullNullPointerException
- ifaction
is null- See Also:
-
-
Method Details
-
getTarget
Returns the object to which this event handler will send a message.- Returns:
- the target of this event handler
- See Also:
-
getAction
Returns the name of the target's writable property that this event handler will set, or the name of the method that this event handler will invoke on the target.- Returns:
- the action of this event handler
- See Also:
-
getEventPropertyName
Returns the property of the event that should be used in the action applied to the target.- Returns:
- the property of the event
- See Also:
-
getListenerMethodName
Returns the name of the method that will trigger the action. A return value ofnull
signifies that all methods in the listener interface trigger the action.- Returns:
- the name of the method that will trigger the action
- See Also:
-
invoke
Extract the appropriate property value from the event and pass it to the action associated with thisEventHandler
.- Specified by:
invoke
in interfaceInvocationHandler
- Parameters:
proxy
- the proxy objectmethod
- the method in the listener interfacearguments
- an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, ornull
if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such asjava.lang.Integer
orjava.lang.Boolean
.- Returns:
- the result of applying the action to the target
- See Also:
-
create
Creates an implementation oflistenerInterface
in which all of the methods in the listener interface apply the handler'saction
to thetarget
. This method is implemented by calling the other, more general, implementation of thecreate
method with both theeventPropertyName
and thelistenerMethodName
taking the valuenull
. Refer tothe general version of create
for a complete description of theaction
parameter.To create an
ActionListener
that shows aJDialog
withdialog.show()
, one can write:EventHandler.create(ActionListener.class, dialog, "show")
- Type Parameters:
T
- the type to create- Parameters:
listenerInterface
- the listener interface to create a proxy fortarget
- the object that will perform the actionaction
- the name of a (possibly qualified) property or method on the target- Returns:
- an object that implements
listenerInterface
- Throws:
NullPointerException
- iflistenerInterface
is nullNullPointerException
- iftarget
is nullNullPointerException
- ifaction
is nullIllegalArgumentException
- if creating a Proxy forlistenerInterface
fails for any of the restrictions specified byProxy.newProxyInstance(java.lang.ClassLoader, java.lang.Class<?>[], java.lang.reflect.InvocationHandler)
- See Also:
-
create
public static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName) /** Creates an implementation oflistenerInterface
in which all of the methods pass the value of the event expression,eventPropertyName
, to the final method in the statement,action
, which is applied to thetarget
. This method is implemented by calling the more general, implementation of thecreate
method with thelistenerMethodName
taking the valuenull
. Refer tothe general version of create
for a complete description of theaction
andeventPropertyName
parameters.To create an
ActionListener
that sets the the text of aJLabel
to the text value of theJTextField
source of the incoming event, you can use the following code:EventHandler.create(ActionListener.class, label, "text", "source.text");
//Equivalent code using an inner class instead of EventHandler. new ActionListener() { public void actionPerformed(ActionEvent event) { label.setText(((JTextField)(event.getSource())).getText()); } };
- Type Parameters:
T
- the type to create- Parameters:
listenerInterface
- the listener interface to create a proxy fortarget
- the object that will perform the actionaction
- the name of a (possibly qualified) property or method on the targeteventPropertyName
- the (possibly qualified) name of a readable property of the incoming event- Returns:
- an object that implements
listenerInterface
- Throws:
NullPointerException
- iflistenerInterface
is nullNullPointerException
- iftarget
is nullNullPointerException
- ifaction
is nullIllegalArgumentException
- if creating a Proxy forlistenerInterface
fails for any of the restrictions specified byProxy.newProxyInstance(java.lang.ClassLoader, java.lang.Class<?>[], java.lang.reflect.InvocationHandler)
- See Also:
-
create
public static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName) Creates an implementation oflistenerInterface
in which the method namedlistenerMethodName
passes the value of the event expression,eventPropertyName
, to the final method in the statement,action
, which is applied to thetarget
. All of the other listener methods do nothing.The
eventPropertyName
string is used to extract a value from the incoming event object that is passed to the target method. The common case is the target method takes no arguments, in which case a value of null should be used for theeventPropertyName
. Alternatively if you want the incoming event object passed directly to the target method use the empty string. The format of theeventPropertyName
string is a sequence of methods or properties where each method or property is applied to the value returned by the preceding method starting from the incoming event object. The syntax is:propertyName{.propertyName}*
wherepropertyName
matches a method or property. For example, to extract thepoint
property from aMouseEvent
, you could use either"point"
or"getPoint"
as theeventPropertyName
. To extract the "text" property from aMouseEvent
with aJLabel
source use any of the following aseventPropertyName
:"source.text"
,"getSource.text" "getSource.getText"
or"source.getText"
. If a method can not be found, or an exception is generated as part of invoking a method aRuntimeException
will be thrown at dispatch time. For example, if the incoming event object is null, andeventPropertyName
is non-null and not empty, aRuntimeException
will be thrown.The
action
argument is of the same format as theeventPropertyName
argument where the last property name identifies either a method name or writable property.If the
listenerMethodName
isnull
all methods in the interface trigger theaction
to be executed on thetarget
.For example, to create a
MouseListener
that sets the target object'sorigin
property to the incomingMouseEvent
's location (that's the value ofmouseEvent.getPoint()
) each time a mouse button is pressed, one would write:EventHandler.create(MouseListener.class, target, "origin", "point", "mousePressed");
MouseListener
in which all of the methods exceptmousePressed
are no-ops://Equivalent code using an inner class instead of EventHandler. new MouseAdapter() { public void mousePressed(MouseEvent e) { target.setOrigin(e.getPoint()); } };
- Type Parameters:
T
- the type to create- Parameters:
listenerInterface
- the listener interface to create a proxy fortarget
- the object that will perform the actionaction
- the name of a (possibly qualified) property or method on the targeteventPropertyName
- the (possibly qualified) name of a readable property of the incoming eventlistenerMethodName
- the name of the method in the listener interface that should trigger the action- Returns:
- an object that implements
listenerInterface
- Throws:
NullPointerException
- iflistenerInterface
is nullNullPointerException
- iftarget
is nullNullPointerException
- ifaction
is nullIllegalArgumentException
- if creating a Proxy forlistenerInterface
fails for any of the restrictions specified byProxy.newProxyInstance(java.lang.ClassLoader, java.lang.Class<?>[], java.lang.reflect.InvocationHandler)
- See Also:
-