< prev index next >
src/java.desktop/share/classes/java/beans/EventHandler.java
Print this page
@@ -34,86 +34,86 @@
import sun.reflect.misc.MethodUtil;
import sun.reflect.misc.ReflectUtil;
/**
- * The <code>EventHandler</code> class provides
+ * The {@code EventHandler} class provides
* support for dynamically generating event listeners whose methods
* execute a simple statement involving an incoming event object
* and a target object.
* <p>
- * The <code>EventHandler</code> class is intended to be used by interactive tools, such as
+ * The {@code 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 <em>source</em>)
* to an application logic bean (the <em>target</em>). The most effective
* connections of this kind isolate the application logic from the user
- * interface. For example, the <code>EventHandler</code> for a
- * connection from a <code>JCheckBox</code> to a method
+ * interface. For example, the {@code EventHandler} for a
+ * connection from a {@code 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.
* <p>
* Inner classes are another, more general way to handle events from
- * user interfaces. The <code>EventHandler</code> class
+ * user interfaces. The {@code EventHandler} class
* handles only a subset of what is possible using inner
- * classes. However, <code>EventHandler</code> works better
+ * classes. However, {@code EventHandler} works better
* with the long-term persistence scheme than inner classes.
- * Also, using <code>EventHandler</code> in large applications in
+ * Also, using {@code EventHandler} in large applications in
* which the same interface is implemented many times can
* reduce the disk and memory footprint of the application.
* <p>
- * The reason that listeners created with <code>EventHandler</code>
+ * The reason that listeners created with {@code EventHandler}
* have such a small
- * footprint is that the <code>Proxy</code> class, on which
- * the <code>EventHandler</code> relies, shares implementations
+ * footprint is that the {@code Proxy} class, on which
+ * the {@code EventHandler} relies, shares implementations
* of identical
* interfaces. For example, if you use
- * the <code>EventHandler</code> <code>create</code> methods to make
- * all the <code>ActionListener</code>s in an application,
+ * the {@code EventHandler create} methods to make
+ * all the {@code ActionListener}s in an application,
* all the action listeners will be instances of a single class
- * (one created by the <code>Proxy</code> class).
+ * (one created by the {@code Proxy} class).
* In general, listeners based on
- * the <code>Proxy</code> class require one listener class
+ * the {@code Proxy} class require one listener class
* to be created per <em>listener type</em> (interface),
* whereas the inner class
* approach requires one class to be created per <em>listener</em>
* (object that implements the interface).
*
* <p>
- * You don't generally deal directly with <code>EventHandler</code>
+ * You don't generally deal directly with {@code EventHandler}
* instances.
- * Instead, you use one of the <code>EventHandler</code>
- * <code>create</code> methods to create
+ * Instead, you use one of the {@code EventHandler}
+ * {@code create} methods to create
* an object that implements a given listener interface.
- * This listener object uses an <code>EventHandler</code> object
+ * This listener object uses an {@code 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 <code>create</code> methods.
+ * objects using the {@code create} methods.
*
* <h2>Examples of Using EventHandler</h2>
*
- * The simplest use of <code>EventHandler</code> is to install
+ * The simplest use of {@code EventHandler} is to install
* a listener that calls a method on the target object with no arguments.
- * In the following example we create an <code>ActionListener</code>
- * that invokes the <code>toFront</code> method on an instance
- * of <code>javax.swing.JFrame</code>.
+ * In the following example we create an {@code ActionListener}
+ * that invokes the {@code toFront} method on an instance
+ * of {@code javax.swing.JFrame}.
*
* <blockquote>
*<pre>
*myButton.addActionListener(
* (ActionListener)EventHandler.create(ActionListener.class, frame, "toFront"));
*</pre>
* </blockquote>
*
- * When <code>myButton</code> is pressed, the statement
- * <code>frame.toFront()</code> will be executed. One could get
+ * When {@code myButton} is pressed, the statement
+ * {@code 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 <code>ActionListener</code>
+ * by defining a new implementation of the {@code ActionListener}
* interface and adding an instance of it to the button:
*
* <blockquote>
*<pre>
//Equivalent code using an inner class instead of EventHandler.
@@ -123,16 +123,16 @@
* }
*});
*</pre>
* </blockquote>
*
- * The next simplest use of <code>EventHandler</code> is
+ * The next simplest use of {@code 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 <code>ActionListener</code> that
- * sets the <code>nextFocusableComponent</code> property of the target
+ * In the following example we create an {@code ActionListener} that
+ * sets the {@code nextFocusableComponent} property of the target
* (myButton) object to the value of the "source" property of the event.
*
* <blockquote>
*<pre>
*EventHandler.create(ActionListener.class, myButton, "nextFocusableComponent", "source")
@@ -150,13 +150,13 @@
* }
*}
*</pre>
* </blockquote>
*
- * It's also possible to create an <code>EventHandler</code> that
+ * It's also possible to create an {@code EventHandler} that
* just passes the incoming event object to the target's action.
- * If the fourth <code>EventHandler.create</code> argument is
+ * If the fourth {@code EventHandler.create} argument is
* an empty string, then the event is just passed along:
*
* <blockquote>
*<pre>
*EventHandler.create(ActionListener.class, target, "doActionEvent", "")
@@ -174,15 +174,15 @@
* }
*}
*</pre>
* </blockquote>
*
- * Probably the most common use of <code>EventHandler</code>
+ * Probably the most common use of {@code EventHandler}
* is to extract a property value from the
* <em>source</em> 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 <code>ActionListener</code> that
+ * In the following example we create an {@code 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.
*
* <blockquote>
@@ -248,21 +248,21 @@
* target.getA().setB(e.getC().isD());
* }
*}
*</pre>
* <p>
- * As <code>EventHandler</code> ultimately relies on reflection to invoke
+ * As {@code 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 <code>MyTarget</code> which is
+ * if the target is an instance of the class {@code MyTarget} which is
* defined as:
* <pre>
* public class MyTarget {
* public void doIt(String);
* public void doIt(Object);
* }
* </pre>
- * Then the method <code>doIt</code> is overloaded. EventHandler will invoke
+ * Then the method {@code 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.
*
@@ -282,26 +282,26 @@
private final String eventPropertyName;
private final String listenerMethodName;
private final AccessControlContext acc = AccessController.getContext();
/**
- * Creates a new <code>EventHandler</code> object;
- * you generally use one of the <code>create</code> methods
+ * Creates a new {@code EventHandler} object;
+ * you generally use one of the {@code create} methods
* instead of invoking this constructor directly. Refer to
* {@link java.beans.EventHandler#create(Class, Object, String, String)
* the general version of create} for a complete description of
- * the <code>eventPropertyName</code> and <code>listenerMethodName</code>
+ * the {@code eventPropertyName} and {@code listenerMethodName}
* parameter.
*
* @param target the object that will perform the action
* @param action the name of a (possibly qualified) property or method on
* the target
* @param eventPropertyName the (possibly qualified) name of a readable property of the incoming event
* @param listenerMethodName the name of the method in the listener interface that should trigger the action
*
- * @throws NullPointerException if <code>target</code> is null
- * @throws NullPointerException if <code>action</code> is null
+ * @throws NullPointerException if {@code target} is null
+ * @throws NullPointerException if {@code action} is null
*
* @see EventHandler
* @see #create(Class, Object, String, String, String)
* @see #getTarget
* @see #getAction
@@ -357,11 +357,11 @@
return eventPropertyName;
}
/**
* Returns the name of the method that will trigger the action.
- * A return value of <code>null</code> signifies that all methods in the
+ * A return value of {@code null} signifies that all methods in the
* listener interface trigger the action.
*
* @return the name of the method that will trigger the action
*
* @see #EventHandler(Object, String, String, String)
@@ -410,11 +410,11 @@
}
/**
* Extract the appropriate property value from the event and
* pass it to the action associated with
- * this <code>EventHandler</code>.
+ * this {@code EventHandler}.
*
* @param proxy the proxy object
* @param method the method in the listener interface
* @return the result of applying the action to the target
*
@@ -493,23 +493,23 @@
}
return null;
}
/**
- * Creates an implementation of <code>listenerInterface</code> in which
+ * Creates an implementation of {@code listenerInterface} in which
* <em>all</em> of the methods in the listener interface apply
- * the handler's <code>action</code> to the <code>target</code>. This
+ * the handler's {@code action} to the {@code target}. This
* method is implemented by calling the other, more general,
- * implementation of the <code>create</code> method with both
- * the <code>eventPropertyName</code> and the <code>listenerMethodName</code>
- * taking the value <code>null</code>. Refer to
+ * implementation of the {@code create} method with both
+ * the {@code eventPropertyName} and the {@code listenerMethodName}
+ * taking the value {@code null}. Refer to
* {@link java.beans.EventHandler#create(Class, Object, String, String)
* the general version of create} for a complete description of
- * the <code>action</code> parameter.
+ * the {@code action} parameter.
* <p>
- * To create an <code>ActionListener</code> that shows a
- * <code>JDialog</code> with <code>dialog.show()</code>,
+ * To create an {@code ActionListener} that shows a
+ * {@code JDialog} with {@code dialog.show()},
* one can write:
*
*<blockquote>
*<pre>
*EventHandler.create(ActionListener.class, dialog, "show")
@@ -519,15 +519,15 @@
* @param <T> the type to create
* @param listenerInterface the listener interface to create a proxy for
* @param target the object that will perform the action
* @param action the name of a (possibly qualified) property or method on
* the target
- * @return an object that implements <code>listenerInterface</code>
+ * @return an object that implements {@code listenerInterface}
*
- * @throws NullPointerException if <code>listenerInterface</code> is null
- * @throws NullPointerException if <code>target</code> is null
- * @throws NullPointerException if <code>action</code> is null
+ * @throws NullPointerException if {@code listenerInterface} is null
+ * @throws NullPointerException if {@code target} is null
+ * @throws NullPointerException if {@code action} is null
*
* @see #create(Class, Object, String, String)
*/
public static <T> T create(Class<T> listenerInterface,
Object target, String action)
@@ -535,25 +535,25 @@
return create(listenerInterface, target, action, null, null);
}
/**
/**
- * Creates an implementation of <code>listenerInterface</code> in which
+ * Creates an implementation of {@code listenerInterface} in which
* <em>all</em> of the methods pass the value of the event
- * expression, <code>eventPropertyName</code>, to the final method in the
- * statement, <code>action</code>, which is applied to the <code>target</code>.
+ * expression, {@code eventPropertyName}, to the final method in the
+ * statement, {@code action}, which is applied to the {@code target}.
* This method is implemented by calling the
- * more general, implementation of the <code>create</code> method with
- * the <code>listenerMethodName</code> taking the value <code>null</code>.
+ * more general, implementation of the {@code create} method with
+ * the {@code listenerMethodName} taking the value {@code null}.
* Refer to
* {@link java.beans.EventHandler#create(Class, Object, String, String)
* the general version of create} for a complete description of
- * the <code>action</code> and <code>eventPropertyName</code> parameters.
+ * the {@code action} and {@code eventPropertyName} parameters.
* <p>
- * To create an <code>ActionListener</code> that sets the
- * the text of a <code>JLabel</code> to the text value of
- * the <code>JTextField</code> source of the incoming event,
+ * To create an {@code ActionListener} that sets the
+ * the text of a {@code JLabel} to the text value of
+ * the {@code JTextField} source of the incoming event,
* you can use the following code:
*
*<blockquote>
*<pre>
*EventHandler.create(ActionListener.class, label, "text", "source.text");
@@ -577,15 +577,15 @@
* @param target the object that will perform the action
* @param action the name of a (possibly qualified) property or method on
* the target
* @param eventPropertyName the (possibly qualified) name of a readable property of the incoming event
*
- * @return an object that implements <code>listenerInterface</code>
+ * @return an object that implements {@code listenerInterface}
*
- * @throws NullPointerException if <code>listenerInterface</code> is null
- * @throws NullPointerException if <code>target</code> is null
- * @throws NullPointerException if <code>action</code> is null
+ * @throws NullPointerException if {@code listenerInterface} is null
+ * @throws NullPointerException if {@code target} is null
+ * @throws NullPointerException if {@code action} is null
*
* @see #create(Class, Object, String, String, String)
*/
public static <T> T create(Class<T> listenerInterface,
Object target, String action,
@@ -593,65 +593,65 @@
{
return create(listenerInterface, target, action, eventPropertyName, null);
}
/**
- * Creates an implementation of <code>listenerInterface</code> in which
- * the method named <code>listenerMethodName</code>
- * passes the value of the event expression, <code>eventPropertyName</code>,
- * to the final method in the statement, <code>action</code>, which
- * is applied to the <code>target</code>. All of the other listener
+ * Creates an implementation of {@code listenerInterface} in which
+ * the method named {@code listenerMethodName}
+ * passes the value of the event expression, {@code eventPropertyName},
+ * to the final method in the statement, {@code action}, which
+ * is applied to the {@code target}. All of the other listener
* methods do nothing.
* <p>
- * The <code>eventPropertyName</code> string is used to extract a value
+ * The {@code 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 the
- * <code>eventPropertyName</code>. Alternatively if you want
+ * {@code eventPropertyName}. Alternatively if you want
* the incoming event object passed directly to the target method use
* the empty string.
- * The format of the <code>eventPropertyName</code> string is a sequence of
+ * The format of the {@code eventPropertyName} 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: <code>propertyName{.propertyName}*</code>
- * where <code>propertyName</code> matches a method or
- * property. For example, to extract the <code>point</code>
- * property from a <code>MouseEvent</code>, you could use either
- * <code>"point"</code> or <code>"getPoint"</code> as the
- * <code>eventPropertyName</code>. To extract the "text" property from
- * a <code>MouseEvent</code> with a <code>JLabel</code> source use any
- * of the following as <code>eventPropertyName</code>:
- * <code>"source.text"</code>,
- * <code>"getSource.text"</code> <code>"getSource.getText"</code> or
- * <code>"source.getText"</code>. If a method can not be found, or an
+ * The syntax is: {@code propertyName{.propertyName}*}
+ * where {@code propertyName} matches a method or
+ * property. For example, to extract the {@code point}
+ * property from a {@code MouseEvent}, you could use either
+ * {@code "point"} or {@code "getPoint"} as the
+ * {@code eventPropertyName}. To extract the "text" property from
+ * a {@code MouseEvent} with a {@code JLabel} source use any
+ * of the following as {@code eventPropertyName}:
+ * {@code "source.text"},
+ * {@code "getSource.text" "getSource.getText"} or
+ * {@code "source.getText"}. If a method can not be found, or an
* exception is generated as part of invoking a method a
- * <code>RuntimeException</code> will be thrown at dispatch time. For
+ * {@code RuntimeException} will be thrown at dispatch time. For
* example, if the incoming event object is null, and
- * <code>eventPropertyName</code> is non-null and not empty, a
- * <code>RuntimeException</code> will be thrown.
+ * {@code eventPropertyName} is non-null and not empty, a
+ * {@code RuntimeException} will be thrown.
* <p>
- * The <code>action</code> argument is of the same format as the
- * <code>eventPropertyName</code> argument where the last property name
+ * The {@code action} argument is of the same format as the
+ * {@code eventPropertyName} argument where the last property name
* identifies either a method name or writable property.
* <p>
- * If the <code>listenerMethodName</code> is <code>null</code>
- * <em>all</em> methods in the interface trigger the <code>action</code> to be
- * executed on the <code>target</code>.
- * <p>
- * For example, to create a <code>MouseListener</code> that sets the target
- * object's <code>origin</code> property to the incoming <code>MouseEvent</code>'s
- * location (that's the value of <code>mouseEvent.getPoint()</code>) each
+ * If the {@code listenerMethodName} is {@code null}
+ * <em>all</em> methods in the interface trigger the {@code action} to be
+ * executed on the {@code target}.
+ * <p>
+ * For example, to create a {@code MouseListener} that sets the target
+ * object's {@code origin} property to the incoming {@code MouseEvent}'s
+ * location (that's the value of {@code mouseEvent.getPoint()}) each
* time a mouse button is pressed, one would write:
*<blockquote>
*<pre>
*EventHandler.create(MouseListener.class, target, "origin", "point", "mousePressed");
*</pre>
*</blockquote>
*
- * This is comparable to writing a <code>MouseListener</code> in which all
- * of the methods except <code>mousePressed</code> are no-ops:
+ * This is comparable to writing a {@code MouseListener} in which all
+ * of the methods except {@code mousePressed} are no-ops:
*
*<blockquote>
*<pre>
//Equivalent code using an inner class instead of EventHandler.
*new MouseAdapter() {
@@ -668,15 +668,15 @@
* @param action the name of a (possibly qualified) property or method on
* the target
* @param eventPropertyName the (possibly qualified) name of a readable property of the incoming event
* @param listenerMethodName the name of the method in the listener interface that should trigger the action
*
- * @return an object that implements <code>listenerInterface</code>
+ * @return an object that implements {@code listenerInterface}
*
- * @throws NullPointerException if <code>listenerInterface</code> is null
- * @throws NullPointerException if <code>target</code> is null
- * @throws NullPointerException if <code>action</code> is null
+ * @throws NullPointerException if {@code listenerInterface} is null
+ * @throws NullPointerException if {@code target} is null
+ * @throws NullPointerException if {@code action} is null
*
* @see EventHandler
*/
public static <T> T create(Class<T> listenerInterface,
Object target, String action,
< prev index next >