监听器 - Listener

学习目标

• 理解监听器的意义
• 了解监听器的注册
• @EventHandler注解的作用

理解监听器的意义

监听器可以使开发者简化相关检测的操作，例如玩家移动，玩家说话，服务器关闭....等操作，当服务器里做了部分操作时，会触发 -BukkitAPI 里部分的 org.bukkit.event 包的内容
例如:
org.bukkit.event.player#AsyncPlayerChatEvent (根据javadoc可以得知该类是用来作为 处理玩家异步说话时的事件)

了解监听器的注册

要注册一个事件我们需要先来看看JavaDoc的注释是怎么写的

打开 org.bukkit.event 下我们可以看到一个注解 EventHandler，一个接口 Listener

• EventHandler
  一个用于声明方法成为一个事件监听器方法的注解
  原文:
  An annotation to mark methods as being event handler methods
• Listener
  一个触发所有事件监听器的接口
  原文:
  Simple interface for tagging all EventListeners

有点乱？喝杯茶再来看吧~
那么有了上面的注释，我们可以得到一些信息

1. 注解 EventHandler 可以让一个方法作为一个事件监听器方法
2. 接口 Listener 可以让一个类作为监听器类(难以解释，翻翻源码就知道了)

所以我们可以写出以下代码

import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class Tutorial1 extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        getLogger().info("onEnable has been invoked!");
    }
    
    @EventHandler
    public void onChat(AsyncPlayerChatEvent event) {
      event.getPlayer().sendMessage("chat!");
    }

}

那么我们编译并打包好代码，丢进 plugins 文件夹，进入游戏，说话，然后你就会发现 onChat 方法并没有被执行
这是为什么呢？
我们来看看 PluginManager 这个 Bukkit 提供的插件管理类，我们可以看到一个方法

registerEvents(Listener listener, Plugin plugin)
将传入的监听器类的所有事件进行注册
原文:
Registers all the events in the given listener class

那么我们在 onEnable 里键入以下代码

  Bukkit.getPluginManager().registerEvents(this, this);

再编译测试，你就会发现 onChat 方法里的内容就触发了

完整代码:

import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class Tutorial1 extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        getLogger().info("onEnable has been invoked!");
        // 注册本类为所有事件, 如果你将你的监听器类放在别的类里, 
        // 这里假设该类是 ChatListener
        // 那传入的参数就改为 Bukkit.getPluginManager.registerEvents(new ChatListener(), this);
        Bukkit.getPluginManager().registerEvents(this, this);
    }
    
    @EventHandler
    public void onChat(AsyncPlayerChatEvent event) {
      event.getPlayer().sendMessage("chat!");
    }

}

@EventHandler注解的作用

那么我们已经学会了监听器的注册的操作了, 那我们来研究一下这个 EventHandler
我们先来看看 registerEvents() 方法的具体实现

public void registerEvents(Listener listener, Plugin plugin) {
  以上省略......
  for (Map.Entry<Class<? extends Event>, Set<RegisteredListener>> entry : plugin.getPluginLoader().createRegisteredListeners(listener, plugin).entrySet()) {
 getEventListeners(getRegistrationClass((Class)entry.getKey())).registerAll((Collection)entry.getValue());
  }
}

我们看到一个方法 getRegistrationClass(), 我们又来看看这个方法都做了些什么吧

public Map<Class<? extends Event>, Set<RegisteredListener>> createRegisteredListeners(Listener listener, Plugin plugin) {
    Validate.notNull(plugin, "Plugin can not be null");
    Validate.notNull(listener, "Listener can not be null");
    
    this.server.getPluginManager().useTimings();
    Map<Class<? extends Event>, Set<RegisteredListener>> ret = new HashMap();
    Method[] privateMethods;
    try {
      Method[] publicMethods = listener.getClass().getMethods();
      privateMethods = listener.getClass().getDeclaredMethods();
      Set<Method> methods = new HashSet(publicMethods.length + privateMethods.length, 1.0F);
      for (Method method : publicMethods) {
        methods.add(method);
      }
      for (Method method : privateMethods) {
        methods.add(method);
      }
    }
    catch (NoClassDefFoundError e) {
      plugin.getLogger().severe("Plugin " + plugin.getDescription().getFullName() + " has failed to register events for " + listener.getClass() + " because " + e.getMessage() + " does not exist.");
      return ret;
    }
    Set<Method> methods;
    for (final Method method : methods) {
      EventHandler eh = (EventHandler)method.getAnnotation(EventHandler.class);
      以下省略......
    }

那么我们可以从上边的代码发现, BukkitAPI 先对传入的 Listener 实现类进行检查, 之后反射遍历传入的 Listener 实现类的所有方法, 之后再做些必要的事情后就注册好了一个事件了

根据上方的代码我们可以得到以下结论

• EventHandler用于标记某个特定的方法为监听器