|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.beans.EventHandler
public class EventHandler
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.
Constructor Summary | |
---|---|
EventHandler(Object target,
String action,
String eventPropertyName,
String listenerMethodName)
Creates a new EventHandler instance. |
Method Summary | ||
---|---|---|
static
|
create(Class<T> listenerInterface,
Object target,
String action)
Constructs an implementation of listenerInterface
to dispatch events. |
|
static
|
create(Class<T> listenerInterface,
Object target,
String action,
String eventPropertyName)
Constructs an implementation of listenerInterface
to dispatch events. |
|
static
|
create(Class<T> listenerInterface,
Object target,
String action,
String eventPropertyName,
String listenerMethodName)
Constructs an implementation of listenerInterface
to dispatch events. |
|
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 . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName)
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
.
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.Method Detail |
---|
public String getEventPropertyName()
public String getListenerMethodName()
public Object getTarget()
public String getAction()
public Object invoke(Object proxy, Method method, Object[] arguments)
EventHandler
.
This method is normally called by the listener's proxy implementation.
invoke
in interface InvocationHandler
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.
void
, the proxy
instance will ignore it. If the wrapped method returns
a primitive, this must be the correct wrapper type whose value
is exactly assignable to the appropriate type (no widening
will be performed); a null object in this case causes a
NullPointerException
. In all remaining cases, if
the returned object is not assignment compatible to the
declared type of the original method, the proxy instance
will generate a ClassCastException
.
Throwable
- NoSuchMethodException
is thrown when the EventHandler's
action method or property cannot be found.Proxy
,
UndeclaredThrowableException
public static <T> T create(Class<T> listenerInterface, Object target, String 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)
listenerInterface
- Listener interface to implement.target
- Object to invoke action on.action
- Target property or method to invoke.
public static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName)
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)
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.
public static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName)
Constructs an implementation of listenerInterface
to dispatch events.
Besides the functionality described for create(Class, Object, String)
and 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
.
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |