java.beans

Class EventHandler

Implemented Interfaces:
InvocationHandler

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 create(Class 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.

static
T create(Class 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.

static
T create(Class 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.

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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

EventHandler

public EventHandler(Object target,
                    String action,
                    String eventPropertyName,
                    String listenerMethodName)
Creates a new 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.

Method Details

T create

public static  T create(Class 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)

Parameters:
listenerInterface - Listener interface to implement.
target - Object to invoke action on.
action - Target property or method to invoke.
Returns:
A constructed proxy object.

T create

public static  T create(Class 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)

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.

T create

public static  T create(Class 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.

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.

getAction

public String getAction()
Returns the action method name.

getEventPropertyName

public String getEventPropertyName()
Returns the event property name.

getListenerMethodName

public String getListenerMethodName()
Returns the listener's method name.

getTarget

public Object getTarget()
Returns the target object.

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] arguments)
Invokes the EventHandler.

This method is normally called by the listener's proxy implementation.

Specified by:
invoke in interface InvocationHandler
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.

java.beans.EventHandler Copyright (C) 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.