java.beans
Class EventHandler

java.lang.Object
  |
  +--java.beans.EventHandler
All Implemented Interfaces:
java.lang.reflect.InvocationHandler

public class EventHandler
extends java.lang.Object
implements java.lang.reflect.InvocationHandler

The EventHandler class provides support for dynamically generating event listeners whose methods execute a simple statement involving the incoming event object and a target object. This is a specialization of what the Proxy class does, in fact the EventHandler is implemented using the Proxy class.

The EventHandler class is intended to be used by interactive tools, like 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 checkbox and passing it directly to the method so that the method is isolated from the user interface layer.

Inner classes are a more general way to handle events from user interfaces, and the EventHandler class handles only a subset of what is possible using inner classes. One might nevertheless choose to use EventHandlers in a large application in which the same interface is implemented many times to reduce the disk and memory footprint of the application.

The reason that EventHandlers have such a small footprint is that the Proxy class, on which the EventHandler is based, shares implementations of similar interfaces. It is, therefore, possible to implement, for example, all ActionListeners in an application with a single class. In general, listeners based on the Proxy class, require one listener class to be created per listener type, where the inner class approach requires one class to be created per listener.

Additionally, both the EventHandler class and the Proxy class on which it depends have public factory methods to create instances of them and have no "hidden state". EventHandlers may therefore archived like other JavaBeans and appear in a textual form in the output of the new output streams.

The simplest use of EventHandler 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 calls the method named "toFront" on an instance of javax.swing.JFrame.

 
 myButton.addActionListener(
     (ActionListener)EventHandler.create(ActionListener.class, frame, "toFront"));
 
 
When 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:
 
 myButton.addActionListener(new ActionListener {
     public void actionPerformed(ActionEvent e) {
         frame.toFront();
     }
 });
 
 
The next simplest use of 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 object to the value of the "source" property of the event.
 
 EventHandler.create(ActionListener.class, target, "nextFocusableComponent", "source")
 
 
This would correspond to the following inner class implementation:
 
 new ActionListener {
     public void actionPerformed(ActionEvent e) {
         button.setNextFocusableComponent((Component)e.getSource()); 
     }
 }
 
 
Probably the most common use of EventHandler in the handling of the listener interfaces used in AWT and Swing 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.
 
 EventHandler.create(ActionListener.class, button, "label", "source.text")
 
 
This would correspond to the following inner class implementation:
 
 new ActionListener {
     public void actionPerformed(ActionEvent e) {
         button.setLabel(((JTextField)e.getSource()).getText()); 
     }
 }
 
 
The event property may be 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.

For example, the following EventHandler:

 
 EventHandler.create(ActionListener.class, target, "a", "b.c.d")
 
 
could be written as the following inner class (assuming all the properties had canonical "getter" methods and returned the appropriate types):
 
 new ActionListener {
     public void actionPerformed(ActionEvent e) {
         target.setA(e.getB().getC().getD()); 
     }
 }
 
 

Since:
1.4
See Also:
Proxy, EventObject

Constructor Summary
EventHandler(java.lang.Object target, java.lang.String action, java.lang.String eventPropertyName, java.lang.String listenerMethodName)
           
 
Method Summary
static java.lang.Object create(java.lang.Class listenerInterface, java.lang.Object target, java.lang.String action)
          Create an implementation of listenerInterface in which all of the methods in the listener interface apply the handler's action to the target.
static java.lang.Object create(java.lang.Class listenerInterface, java.lang.Object target, java.lang.String action, java.lang.String eventPropertyName)
          Create an implementation of listenerInterface 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 the target.
static java.lang.Object create(java.lang.Class listenerInterface, java.lang.Object target, java.lang.String action, java.lang.String eventPropertyName, java.lang.String listenerMethodName)
          Create an implementation of listenerInterface in which the listener method named listenerMethodName passes the value of the event expression, eventPropertyName, to the final method in the statement, action, which is applied to the target.
 java.lang.String getAction()
          Return the action of this handler.
 java.lang.String getEventPropertyName()
          Return the property of the event which should be used in the action applied to the target.
 java.lang.String getListenerMethodName()
          Return the name of the method which will trigger the action.
 java.lang.Object getTarget()
          Return the target of this handler.
 java.lang.Object invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] arguments)
          Extract the appropriate property value from the event and pass it to the action associated with this EventHandler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EventHandler

public EventHandler(java.lang.Object target,
                    java.lang.String action,
                    java.lang.String eventPropertyName,
                    java.lang.String listenerMethodName)
Parameters:
target - the object that will perform the action.
action - the (possibly qualified) name of a writable property or method on the target.
eventPropertyName - the (possibly qualified) name of a readable property of the incoming event.
listenerMethodName - the name of the method in the listener interface that should trigger the action.
See Also:
EventHandler
Method Detail

getTarget

public java.lang.Object getTarget()
Return the target of this handler.
Returns:
The target of this handler.

getAction

public java.lang.String getAction()
Return the action of this handler.
Returns:
The action of this handler.
See Also:
EventHandler

getEventPropertyName

public java.lang.String getEventPropertyName()
Return the property of the event which should be used in the action applied to the target.
Returns:
Return the property of the event.
See Also:
EventHandler

getListenerMethodName

public java.lang.String getListenerMethodName()
Return the name of the method which will trigger the action. A return value of null signifies that all methods in this interface trigger the action.
Returns:
The name of the method which will trigger the action.

invoke

public java.lang.Object invoke(java.lang.Object proxy,
                               java.lang.reflect.Method method,
                               java.lang.Object[] arguments)
Extract the appropriate property value from the event and pass it to the action associated with this EventHandler.
Specified by:
invoke in interface java.lang.reflect.InvocationHandler
Parameters:
proxy - the proxy object.
method - the method in the listener interface.
Returns:
the result of applying the action to the target.
See Also:
EventHandler

create

public static java.lang.Object create(java.lang.Class listenerInterface,
                                      java.lang.Object target,
                                      java.lang.String action)
Create an implementation of listenerInterface in which all of the methods in the listener interface apply the handler's action to the target. This method is implemented by calling the, more general, implementation of the create method with both the eventPropertyName and the listenerMethodName taking the value null.

To create an ActionListener that showed a JDialog with dialog.show(), one could write:

 
 EventHandler.create(ActionListener.class, dialog, "show");
 
 

Parameters:
listenerInterface - The listener interface to create a proxy for.
target - the object that will perform the action.
action - the name of a writable property or method on the target.
Returns:
an object that implements listenerInterface.
See Also:
create(Class, Object, String, String)

create

public static java.lang.Object create(java.lang.Class listenerInterface,
                                      java.lang.Object target,
                                      java.lang.String action,
                                      java.lang.String eventPropertyName)
Create an implementation of listenerInterface 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 the target. This method is implemented by calling the, more general, implementation of the create method with the listenerMethodName taking the value null.

To create an ActionListener that sets the the text of a JLabel to the text value of the JTextField source of the incoming event as in:

 
 label.setText((JTextField(event.getSource())).getText()) 
 
 
one could write:
 
 EventHandler.create(ActionListener.class, label, "text", "source.text");
 
 
Parameters:
listenerInterface - the listener interface to create a proxy for.
target - the object that will perform the action.
action - the name of a writable property or method on the target.
eventPropertyName - the (possibly qualified) name of a readable property of the incoming event.
Returns:
an object that implements listenerInterface
See Also:
create(Class, Object, String, String, String)

create

public static java.lang.Object create(java.lang.Class listenerInterface,
                                      java.lang.Object target,
                                      java.lang.String action,
                                      java.lang.String eventPropertyName,
                                      java.lang.String listenerMethodName)
Create an implementation of listenerInterface in which the listener method named listenerMethodName passes the value of the event expression, eventPropertyName, to the final method in the statement, action, which is applied to the target. All of the other listener methods do nothing.

If the eventPropertyName is null the implementation will call a method with the name specified in action which takes an EventObject or a nullary method with the same name if a method accepting an EventObject is not defined.

If the listenerMethodName is null all methods in the interface trigger the action to be executed on the target.

For example, to create a MouseListener that sets the target object's origin property to the incoming MouseEvent's location (that's the value of mouseEvent.getPoint()) each time a mouse button is pressed, one would write:

 
 EventHandler.create(MouseListener.class, "mousePressed", target, "origin", "point");
 
 
This is comparable to writing a MouseListener in which all of the methods except mousePressed are no-ops:
 
 new MouseAdapter() {
     public void mousePressed(MouseEvent e) {
         target.setOrigin(e.getPoint());
     }
 }
 
 
Parameters:
listenerInterface - the listener interface to create a proxy for.
target - the object that will perform the action.
action - the name of a writable property or method on the target.
eventPropertyName - the (possibly qualified) name of a readable property of the incoming event.
listenerMethodName - the name of the method in the listener interface that should trigger the action.
Returns:
an object that implements listenerInterface.
See Also:
EventHandler