EventHandler (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

java.beans
类 EventHandler

java.lang.Object
  java.beans.EventHandler

所有已实现的接口：: InvocationHandler

public class EventHandler
extends Object
implements InvocationHandler
extends Object
implements InvocationHandler

EventHandler 类为动态生成事件侦听器提供支持，这些侦听器的方法执行一条涉及传入事件对象和目标对象的简单语句。

EventHandler 类由交互工具（比如应用程序生成器）使用，这些工具允许开发人员在 bean 之间建立连接。通常是建立从用户界面 bean（事件 source）到应用程序逻辑 bean（target）的连接。大多数这类有效连接隔离了应用程序逻辑与用户界面。例如，用于从 JCheckBox 到接受 boolean 值的方法之间连接的 EventHandler 可以处理复选框状态的提取，以及处理将其直接传递给该方法，从而使该方法与用户界面层隔离。

内部类是处理来自用户界面的事件的另一种更常见方法。EventHandler 类只处理可能使用内部类的事件的子集。不过，EventHandler 使用长期持久方案要比使用内部类更有效。同样，在同一接口被实现很多次的大型应用程序中，使用 EventHandler 可以减少应用程序的磁盘和内存占用。

使用 EventHandler 创建侦听器占用内存如此之少的原因是，EventHandler 所依赖的 Proxy 类共享了同一接口的实现。例如，如果使用 EventHandler 的 create 方法生成某个应用程序中的所有 ActionListener，则所有动作侦听器都将是单个类（由 Proxy 类创建）的实例。通常，基于 Proxy 类的侦听器要求为每个侦听器类型（接口）创建一个侦听器类，而使用内部类方法时要求为每个侦听器（实现接口的对象）创建一个类。

通常不需要直接处理 EventHandler 实例。相反，可使用 EventHandler 的 create 方法之一创建实现给定侦听器接口的对象。此侦听器对象在后台使用一个 EventHandler 对象来封装关于事件的信息、发生事件时发送消息的对象、要发送的消息（方法）和方法的任意参数。以下部分给出了如何使用 create 方法创建侦听器对象的示例。

使用 EventHandler 的示例

EventHandler 最简单的使用方法是安装一个侦听器，不带参数地在目标对象上调用某个方法。在以下示例中，将创建一个在 javax.swing.JFrame 实例上调用 toFront 方法的 ActionListener。

myButton.addActionListener(
    (ActionListener)EventHandler.create(ActionListener.class, frame, "toFront"));

当按下 myButton 时，将执行 frame.toFront() 语句。通过定义 ActionListener 接口的新实现并将其实例添加到按钮中，用户可以获得同样的效果，且具有额外的编译时类型安全：

//Equivalent code using an inner class instead of EventHandler.
myButton.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        frame.toFront();
    }
});

EventHandler 的另一种最简单用法是从侦听器接口（通常是一个事件对象）中的方法的第一个参数中提取属性值，并用其设置目标对象中的属性值。在以下示例中，将创建一个 ActionListener，它将目标 (myButton) 对象的 nextFocusableComponent 属性设置为事件的 "source" 属性的值。

EventHandler.create(ActionListener.class, myButton, "nextFocusableComponent", "source")

这将对应于以下内部类实现：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        myButton.setNextFocusableComponent((Component)e.getSource()); 
    }
}

也可以创建一个只是将传入事件对象传递给目标动作的 EventHandler。如果 EventHandler.create 中的第四个参数为空字符串，则事件的传递方式如下：

EventHandler.create(ActionListener.class, target, "doActionEvent", "")

这将对应于以下内部类实现：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        target.doActionEvent(e);
    }
}

EventHandler 最常见的用法可能是从事件对象的 source 中提取属性值，并将此值设置为目标对象的属性值。在以下示例中，将创建一个 ActionListener，它将目标对象的 "label" 属性设置为事件源的 "text" 属性的值（"source" 属性的值）。

EventHandler.create(ActionListener.class, myButton, "label", "source.text")

这将对应于以下内部类实现：

//Equivalent code using an inner class instead of EventHandler.
new ActionListener {
    public void actionPerformed(ActionEvent e) {
        myButton.setLabel(((JTextField)e.getSource()).getText()); 
    }
}

可以使用以 "." 字符分隔的任意数量的属性前缀来“限定”事件属性。采用出现在 "." 字符前面的“限定”名称作为将应用于事件对象的属性名称，最左边的最先应用。

例如，以下动作侦听器

EventHandler.create(ActionListener.class, target, "a", "b.c.d")

可以写成以下内部类（假定所有属性都有规范的获取方法并返回适当的类型）：

//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")

可以写成以下内部类（假定所有属性都有规范的获取方法并返回适当的类型）：

   //Equivalent code using an inner class instead of EventHandler.
   new ActionListener {
     public void actionPerformed(ActionEvent e) {
         target.getA().setB(e.getC().isD()); 
    }
}

由于 EventHandler 最终依赖反射来调用方法，所以建议不要以重载方法为目标。例如，如果目标是类 MyTarget 的一个实例，而 MyTarget 定义如下：

   public class MyTarget {
     public void doIt(String);
     public void doIt(Object);
   }

那么方法 doIt 被重载。EventHandler 将基于源调用恰当的方法。如果源为 null，那么两个方法都可以，具体调用哪个方法是不确定的。因此，建议不要以重载方法为目标。

从以下版本开始：: 1.4
另请参见：: Proxy, EventObject

构造方法摘要

EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName)
          创建一个新的 EventHandler 对象；通常使用 create 方法之一，而不是直接调用此构造方法。

方法摘要

static <T> T create(Class<T> listenerInterface, Object target, String action)
          创建 listenerInterface 的实现，在该实现中，侦听器接口中的所有方法都会将处理程序的 action 应用到 target。

static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName)
          创建 listenerInterface 的实现，在该实现中，所有方法都会将事件表达式的值 eventPropertyName 传递给语句中的最终方法 action，后者被应用于 target。

static <T> T create(Class<T> listenerInterface, Object target, String action, String eventPropertyName, String listenerMethodName)
          创建 listenerInterface 的实现，在该实现中，名为 listenerMethodName 的方法将事件表达式的值 eventPropertyName 传递给语句中的最终方法 action，后者被应用于 target。

String getAction()
          返回此事件处理程序将设置的目标的可写属性名称，或者此事件处理程序将在目标上调用的方法名称。

String getEventPropertyName()
          返回应该在应用于目标的动作中使用的事件属性。

String getListenerMethodName()
          返回将触发动作的属性名称。

Object getTarget()
          返回此事件处理程序将为其发送消息的对象。

Object invoke(Object proxy, Method method, Object[] arguments)
          从事件中提取适当属性值，并将其传递到与此 EventHandler 相关联的动作。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法摘要
`EventHandler(Object target, String action, String eventPropertyName, String listenerMethodName)` 创建一个新的 `EventHandler` 对象；通常使用 `create` 方法之一，而不是直接调用此构造方法。

从类 java.lang.Object 继承的方法
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

构造方法详细信息

EventHandler

public EventHandler(Object target,
                    String action,
                    String eventPropertyName,
                    String listenerMethodName)

创建一个新的 EventHandler 对象；通常使用 create 方法之一，而不是直接调用此构造方法。有关 eventPropertyName 和 listenerMethodName 参数的完整描述，请参考 create 的一般形式。

参数：: target - 将执行动作的对象; action - 目标上属性或方法的（可能受限定的）名称; eventPropertyName - 传入事件的可读属性的（可能受限定的）名称; listenerMethodName - 应该触发该动作的侦听器接口中的方法名称
另请参见：: EventHandler, create(Class, Object, String, String, String), getTarget(), getAction(), getEventPropertyName(), getListenerMethodName()

方法详细信息

getTarget

public Object getTarget()

返回此事件处理程序将为其发送消息的对象。

返回：: 此事件处理程序的目标
另请参见：: EventHandler(Object, String, String, String)

getAction

public String getAction()

返回此事件处理程序将设置的目标的可写属性名称，或者此事件处理程序将在目标上调用的方法名称。

返回：: 此事件处理程序的动作
另请参见：: EventHandler(Object, String, String, String)

getEventPropertyName

public String getEventPropertyName()

返回应该在应用于目标的动作中使用的事件属性。

返回：: 事件属性
另请参见：: EventHandler(Object, String, String, String)

getListenerMethodName

public String getListenerMethodName()

返回将触发动作的属性名称。返回值为 null 表示侦听器接口中的所有方法都将触发该动作。

返回：: 将触发该动作的方法名称
另请参见：: EventHandler(Object, String, String, String)

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] arguments)

从事件中提取适当属性值，并将其传递到与此 EventHandler 相关联的动作。

指定者：: 接口 InvocationHandler 中的 invoke

参数：: proxy - 代理对象; method - 侦听器接口中的方法; arguments - 包含传入代理实例上方法调用的参数值的对象数组，如果接口方法不使用参数，则为 null。基本类型的参数被包装在适当基本包装器类（如 java.lang.Integer 或 java.lang.Boolean）的实例中。
返回：: 对目标应用该操作的结果
另请参见：: EventHandler

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action)

创建 listenerInterface 的实现，在该实现中，侦听器接口中的所有方法都会将处理程序的 action 应用到 target。此方法是通过调用其他更常见的 create 方法实现来实现的，其中 eventPropertyName 和 listenerMethodName 都采用 null 值。有关 action 参数的完整描述，请参考 create 的一般形式。

要创建一个使用 dialog.show() 显示 JDialog 的 ActionListener，用户可以编写以下代码：

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

参数：: listenerInterface - 要为其创建代理的侦听器接口; target - 将执行动作的对象; action - 目标上的某个方法或（可能受限定的）属性的名称
返回：: 实现 listenerInterface 的对象
抛出：: NullPointerException - 如果 listenerInterface 为 null; NullPointerException - 如果 target 为 null; NullPointerException - 如果 action 为 null
另请参见：: create(Class, Object, String, String)

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action,
                           String eventPropertyName)

创建 listenerInterface 的实现，在该实现中，所有方法都会将事件表达式的值 eventPropertyName 传递给语句中的最终方法 action，后者被应用于 target。此方法是通过调用更常见的 create 方法实现来实现的，其中 listenerMethodName 采用 null 值。有关 action 和 eventPropertyName 参数的完整描述，请参考 create 的一般形式。

要创建一个将 JLabel 的文本设置为传入事件 JTextField 源的文本值的 ActionListener，可以使用以下代码：

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());
     }
};

参数：: listenerInterface - 要为其创建代理的侦听器接口; target - 将执行动作的对象; action - 目标上的某个（可能受限定的）属性或方法的名称; eventPropertyName - 传入事件的某个可读属性的（可能受限定的）名称
返回：: 实现 listenerInterface 的对象
抛出：: NullPointerException - 如果 listenerInterface 为 null; NullPointerException - 如果 target 为 null; NullPointerException - 如果 action 为 null
另请参见：: create(Class, Object, String, String, String)

create

public static <T> T create(Class<T> listenerInterface,
                           Object target,
                           String action,
                           String eventPropertyName,
                           String listenerMethodName)

创建 listenerInterface 的实现，在该实现中，名为 listenerMethodName 的方法将事件表达式的值 eventPropertyName 传递给语句中的最终方法 action，后者被应用于 target。其他所有侦听器方法不执行任何操作。

eventPropertyName 字符串用来从传递给目标方法的传入事件对象中提取值。一般情况下目标方法不带任何参数，在这种情况下 eventPropertyName 应该使用 null 值。此外，如果希望传入事件对象直接传递给目标方法，则应该使用空字符串。eventPropertyName 字符串的格式是一个方法或属性序列，其中从传入事件对象开始，每一个方法或属性都应用于前一个方法所返回的值。语法如下：propertyName{.propertyName}* 其中 propertyName 与方法或属性匹配。例如，要从 MouseEvent 中提取 point 属性，可以使用 "point" 或 "getPoint" 作为 eventPropertyName。要从具有 JLabel 源的 MouseEvent 中提取 "text" 属性，可以使用以下值之一作为 eventPropertyName："source.text"、"getSource.text"、"getSource.getText" 或者 "source.getText"。如果无法找到某个方法，或者作为调用方法的过程中生成某个异常，则在指派时将抛出 RuntimeException。例如，如果传入事件对象为 null，且 eventPropertyName 为非 null 或非空，则将抛出 RuntimeException。

action 参数的格式与 eventPropertyName 参数相同，其中最后一个属性名标识一个方法名或可写属性。

如果 listenerMethodName 为 null，则接口中的所有方法都会触发将在 target 上执行的 action。

例如，要创建一个 MouseListener，使其在每次按下鼠标按键时，都将目标对象的 origin 属性设置为传入 MouseEvent 的位置（即 mouseEvent.getPoint() 的值），则应编写以下代码：

EventHandler.create(MouseListener.class, "mousePressed", target, "origin", "point");

这相当于编写一个 MouseListener，其中除 mousePressed 以外的所有方法都是无操作：

//Equivalent code using an inner class instead of EventHandler.
new MouseAdapter() {
    public void mousePressed(MouseEvent e) {
        target.setOrigin(e.getPoint());
    }
}

参数：: listenerInterface - 要为其创建代理的侦听器接口; target - 将执行动作的对象; action - 目标上的某个（可能受限制的）属性或方法的名称; eventPropertyName - 传入事件的某个可读属性的（可能受限定的）名称; listenerMethodName - 应触发该动作的侦听器接口中的方法名称
返回：: 实现 listenerInterface 的对象
抛出：: NullPointerException - 如果 listenerInterface 为 null; NullPointerException - 如果 target 为 null; NullPointerException - 如果 action 为 null
另请参见：: EventHandler