feat(api): 修改接口的实现方式。

将关键方法置顶，并采用接口与实现类的方式分离关键代码，便于学习使用。

README.md

@@ -18,7 +18,7 @@
 
 public class DemoPlugin extends JavaPlugin {
 
-    protected final EasyListener listeners = new EasyListener(this);
+    protected final EasyListener listeners = EasyListener.create(this);
 
     @Override
     public void onEnable() {
@@ -37,7 +37,7 @@ public class DemoPlugin extends JavaPlugin {
                         EntityDamageEvent.class, EventPriority.HIGHEST,
                         (event) -> event.getCause() != EntityDamageEvent.DamageCause.ENTITY_ATTACK
                 ); // 有条件的取消一个事件
-        
+
         listeners  // 额外提供的快捷方法
                 .cancelDeath(null) // 所有玩家取消死亡
                 .cancelBreak(player -> !player.isOp()) // 禁止非OP玩家破坏方块/接水或岩浆

pom.xml

@@ -13,7 +13,7 @@
     </properties>
     <groupId>cc.carm.lib</groupId>
     <artifactId>easylistener</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
     <packaging>jar</packaging>
 
     <name>EasyListener</name>

src/main/java/cc/carm/lib/easylistener/EasyListener.java

@@ -1,6 +1,5 @@
 package cc.carm.lib.easylistener;
 
-import org.bukkit.Bukkit;
 import org.bukkit.Location;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
@@ -15,11 +14,10 @@ import org.bukkit.event.player.PlayerBucketFillEvent;
 import org.bukkit.event.player.PlayerJoinEvent;
 import org.bukkit.event.player.PlayerQuitEvent;
 import org.bukkit.event.weather.WeatherChangeEvent;
-import org.bukkit.plugin.*;
+import org.bukkit.plugin.Plugin;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import java.lang.reflect.Method;
 import java.util.Optional;
 import java.util.function.BiPredicate;
 import java.util.function.Consumer;
@@ -30,110 +28,27 @@ import java.util.function.Predicate;
  * 轻松(做)监听，简单快捷的通用Bukkit插件监听器类库。
  *
  * @author CarmJos
- * @since 1.0.0
  */
-public class EasyListener implements Listener {
+public interface EasyListener extends Listener {
 
-    protected final Plugin plugin;
+    /**
-
+     * 创建一个新的 {@link EasyListener} 实例
-    public EasyListener(Plugin plugin) {
+     *
-        this.plugin = plugin;
+     * @param plugin {@link Plugin}插件实例
+     * @return {@link EasyListener} 实例
+     */
+    static @NotNull ListenerManager create(@NotNull Plugin plugin) {
+        return new ListenerManager(plugin);
     }
 
     /**
      * 注销本监听器内的全部监听器。
      * <br> 也可以通过 {@link HandlerList#unregister(Listener)} 方法注销本监听器。
      */
-    public void unregisterAll() {
+    default void unregisterAll() {
         HandlerList.unregisterAll(this);
     }
 
-    /**
-     * 通过 {@link SimplePluginManager} 获取到一个事件类的 {@link HandlerList} 。
-     *
-     * @param eventClass 事件类
-     * @return 事件类的 {@link HandlerList}
-     */
-    private @NotNull HandlerList getEventListeners(@NotNull Class<? extends Event> eventClass) {
-        try {
-            Method method = SimplePluginManager.class.getDeclaredMethod("getEventListeners", Class.class);
-            method.setAccessible(true);
-            return (HandlerList) method.invoke(Bukkit.getPluginManager(), eventClass);
-        } catch (Exception e) {
-            throw new IllegalPluginAccessException(e.toString());
-        }
-    }
-
-    /**
-     * 创建一个事件的执行器实例。
-     *
-     * @param eventClass    事件类
-     * @param eventConsumer 事件执行内容
-     * @param <T>           事件类型
-     * @return 事件的执行器实例
-     */
-    private <T extends Event> EventExecutor createExecutor(@NotNull Class<T> eventClass,
-                                                           @NotNull Consumer<T> eventConsumer) {
-        return (listener, event) -> {
-            try {
-                if (!eventClass.isAssignableFrom(event.getClass())) return;
-                eventConsumer.accept(eventClass.cast(event));
-            } catch (Throwable t) {
-                throw new EventException(t);
-            }
-        };
-    }
-
-    protected void register(@NotNull Class<? extends Event> eventClass, @NotNull RegisteredListener listener) {
-        getEventListeners(eventClass).register(listener);
-    }
-
-    protected void register(@NotNull Class<? extends Event> eventClass, @NotNull EventExecutor executor,
-                            @NotNull EventPriority priority, boolean ignoreCancelled) {
-        register(eventClass, new RegisteredListener(this, executor, priority, this.plugin, ignoreCancelled));
-    }
-
-    /**
-     * 处理一个事件。
-     *
-     * @param eventClass    {@link Event} 事件类
-     * @param eventConsumer 处理方法
-     * @param <T>           {@link Event} 事件的类型
-     * @return 本实例
-     */
-    public <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
-                                                 @NotNull Consumer<T> eventConsumer) {
-        return handle(eventClass, null, eventConsumer);
-    }
-
-    /**
-     * 处理一个事件。
-     *
-     * @param eventClass      {@link Event} 事件类
-     * @param ignoreCancelled 是否忽略掉已经被取消的事件
-     * @param eventConsumer   处理方法
-     * @param <T>             {@link Event} 事件的类型
-     * @return 本实例
-     */
-    public <T extends Event> EasyListener handle(@NotNull Class<T> eventClass, boolean ignoreCancelled,
-                                                 @NotNull Consumer<T> eventConsumer) {
-        return handle(eventClass, null, ignoreCancelled, eventConsumer);
-    }
-
-    /**
-     * 处理一个事件。
-     *
-     * @param eventClass    {@link Event} 事件类
-     * @param priority      {@link EventPriority} 事件处理优先级
-     * @param eventConsumer 处理方法
-     * @param <T>           {@link Event} 事件的类型
-     * @return 本实例
-     */
-    public <T extends Event> EasyListener handle(@NotNull Class<T> eventClass, @Nullable EventPriority priority,
-                                                 @NotNull Consumer<T> eventConsumer) {
-        return handle(eventClass, priority, false, eventConsumer);
-    }
-
     /**
      * 处理一个事件。
      *
@@ -144,13 +59,67 @@ public class EasyListener implements Listener {
      * @param <T>             {@link Event} 事件的类型
      * @return 本实例
      */
-    public <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
+    <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
-                                                 @Nullable EventPriority priority, boolean ignoreCancelled,
+                                          @Nullable EventPriority priority, boolean ignoreCancelled,
-                                                 @NotNull Consumer<T> eventConsumer) {
+                                          @NotNull Consumer<T> eventConsumer);
-        final EventPriority eventPriority = Optional.ofNullable(priority).orElse(EventPriority.NORMAL);
+
-        final EventExecutor executor = createExecutor(eventClass, eventConsumer);
+    /**
-        register(eventClass, executor, eventPriority, ignoreCancelled);
+     * 有条件地取消一个事件。
-        return this;
+     * <br> 本方法在条件满足时对事件进行取消，不会改变事件取消的状态。
+     * <br> 因此，已经被取消的事件将不再进行判断和取消。。
+     *
+     * @param eventClass     {@link Event} 事件类
+     * @param priority       {@link EventPriority} 事件处理优先级
+     * @param eventPredicate 判断事件是否可以取消的条件
+     * @param <T>            {@link Event} 事件的类型，必须实现 {@link Cancellable} 。
+     * @return 本实例
+     * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常
+     */
+    <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass,
+                                          @Nullable EventPriority priority,
+                                          @Nullable Predicate<T> eventPredicate);
+
+    /**
+     * 处理一个事件。
+     *
+     * @param eventClass    {@link Event} 事件类
+     * @param eventConsumer 处理方法
+     * @param <T>           {@link Event} 事件的类型
+     * @return 本实例
+     */
+    default <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
+                                                  @NotNull Consumer<T> eventConsumer) {
+        return handle(eventClass, null, eventConsumer);
+    }
+
+    /**
+     * 处理一个事件。
+     *
+     * @param eventClass      {@link Event} 事件类
+     * @param ignoreCancelled 是否忽略掉已经被取消的事件
+     * @param eventConsumer   处理方法
+     * @param <T>             {@link Event} 事件的类型
+     * @return 本实例
+     */
+    default <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
+                                                  boolean ignoreCancelled,
+                                                  @NotNull Consumer<T> eventConsumer) {
+        return handle(eventClass, null, ignoreCancelled, eventConsumer);
+    }
+
+    /**
+     * 处理一个事件。
+     *
+     * @param eventClass    {@link Event} 事件类
+     * @param priority      {@link EventPriority} 事件处理优先级
+     * @param eventConsumer 处理方法
+     * @param <T>           {@link Event} 事件的类型
+     * @return 本实例
+     */
+    default <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
+                                                  @Nullable EventPriority priority,
+                                                  @NotNull Consumer<T> eventConsumer) {
+        return handle(eventClass, priority, false, eventConsumer);
     }
 
     /**
@@ -161,7 +130,7 @@ public class EasyListener implements Listener {
      * @return 本实例
      * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常
      */
-    public <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass) {
+    default <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass) {
         return cancel(eventClass, null, null);
     }
 
@@ -174,59 +143,41 @@ public class EasyListener implements Listener {
      * @return 本实例
      * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常
      */
-    public <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass, @Nullable Predicate<T> eventPredicate) {
+    default <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass,
+                                                  @Nullable Predicate<T> eventPredicate) {
         return cancel(eventClass, null, eventPredicate);
     }
 
-    /**
+    // >---------------------------
-     * 有条件地取消一个事件。
+    // 预设快捷操作方法
-     *
-     * @param eventClass     {@link Event} 事件类
-     * @param priority       {@link EventPriority} 事件处理优先级
-     * @param eventPredicate 判断事件是否可以取消的条件
-     * @param <T>            {@link Event} 事件的类型，必须实现 {@link Cancellable} 。
-     * @return 本实例
-     * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常
-     */
-    public <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass, @Nullable EventPriority priority,
-                                                 @Nullable Predicate<T> eventPredicate) {
-        if (!Cancellable.class.isAssignableFrom(eventClass)) {
-            throw new IllegalArgumentException("Event class " + eventClass.getName() + " is not cancellable");
-        }
 
-        Predicate<T> predicate = Optional.ofNullable(eventPredicate).orElse(t -> true);
+    default EasyListener cancelJoinMessage() {
-        return handle(eventClass, priority, (event) -> {
-            if (predicate.test(event)) ((Cancellable) event).setCancelled(true);
-        });
-    }
-
-    public EasyListener cancelJoinMessage() {
         return handleJoinMessage(null);
     }
 
-    public EasyListener handleJoinMessage(@Nullable Function<Player, String> joinMessage) {
+    default EasyListener handleJoinMessage(@Nullable Function<Player, String> joinMessage) {
         final Function<Player, String> message = Optional.ofNullable(joinMessage).orElse(t -> "");
         return handle(PlayerJoinEvent.class, (event) -> event.setJoinMessage(message.apply(event.getPlayer())));
     }
 
-    public EasyListener cancelQuitMessage() {
+    default EasyListener cancelQuitMessage() {
         return handleQuitMessage(null);
     }
 
-    public EasyListener handleQuitMessage(@Nullable Function<Player, String> quitMessage) {
+    default EasyListener handleQuitMessage(@Nullable Function<Player, String> quitMessage) {
         final Function<Player, String> message = Optional.ofNullable(quitMessage).orElse(t -> "");
         return handle(PlayerQuitEvent.class, (event) -> event.setQuitMessage(message.apply(event.getPlayer())));
     }
 
-    public EasyListener cancelWeatherChange() {
+    default EasyListener cancelWeatherChange() {
         return cancelWeatherChange(null);
     }
 
-    public EasyListener cancelWeatherChange(@Nullable Predicate<WeatherChangeEvent> weatherPredicate) {
+    default EasyListener cancelWeatherChange(@Nullable Predicate<WeatherChangeEvent> weatherPredicate) {
         return cancel(WeatherChangeEvent.class, weatherPredicate);
     }
 
-    public EasyListener cancelBreak(@Nullable Predicate<Player> player) {
+    default EasyListener cancelBreak(@Nullable Predicate<Player> player) {
         final Predicate<Player> predicate = Optional.ofNullable(player).orElse(t -> true);
         return cancelBreak(
                 (event) -> predicate.test(event.getPlayer()),
@@ -234,13 +185,13 @@ public class EasyListener implements Listener {
         );
     }
 
-    public EasyListener cancelBreak(@Nullable Predicate<BlockBreakEvent> blockBreakPredicate,
+    default EasyListener cancelBreak(@Nullable Predicate<BlockBreakEvent> blockBreakPredicate,
-                                    @Nullable Predicate<PlayerBucketFillEvent> bucketFillPredicate) {
+                                     @Nullable Predicate<PlayerBucketFillEvent> bucketFillPredicate) {
         return cancel(BlockBreakEvent.class, blockBreakPredicate)
                 .cancel(PlayerBucketFillEvent.class, bucketFillPredicate);
     }
 
-    public EasyListener cancelPlace(@Nullable Predicate<Player> player) {
+    default EasyListener cancelPlace(@Nullable Predicate<Player> player) {
         final Predicate<Player> predicate = Optional.ofNullable(player).orElse(t -> true);
         return cancelPlace(
                 (event) -> predicate.test(event.getPlayer()),
@@ -248,8 +199,8 @@ public class EasyListener implements Listener {
         );
     }
 
-    public EasyListener cancelPlace(@Nullable Predicate<BlockPlaceEvent> blockBreakPredicate,
+    default EasyListener cancelPlace(@Nullable Predicate<BlockPlaceEvent> blockBreakPredicate,
-                                    @Nullable Predicate<PlayerBucketEmptyEvent> bucketEmptyPredicate) {
+                                     @Nullable Predicate<PlayerBucketEmptyEvent> bucketEmptyPredicate) {
         return cancel(BlockPlaceEvent.class, blockBreakPredicate)
                 .cancel(PlayerBucketEmptyEvent.class, bucketEmptyPredicate);
     }
@@ -260,7 +211,7 @@ public class EasyListener implements Listener {
      * @param predicate 判断器，返回true则取消事件。两参数分别为 attacker 与 victim 。
      * @return 当前实例
      */
-    public EasyListener cancelPVP(@Nullable BiPredicate<Player, Player> predicate) {
+    default EasyListener cancelPVP(@Nullable BiPredicate<Player, Player> predicate) {
         final BiPredicate<Player, Player> p = Optional.ofNullable(predicate).orElse((attacker, victim) -> true);
         return cancelAttack((attacker, damager) -> {
             if (!(attacker instanceof Player) || !(damager instanceof Player)) return false;
@@ -274,12 +225,12 @@ public class EasyListener implements Listener {
      * @param predicate 判断器，返回true则取消事件。两参数分别为 attacker 与 victim 。
      * @return 当前实例
      */
-    public EasyListener cancelAttack(@Nullable BiPredicate<Entity/*attacker*/, Entity/*victim*/> predicate) {
+    default EasyListener cancelAttack(@Nullable BiPredicate<Entity/*attacker*/, Entity/*victim*/> predicate) {
         final BiPredicate<Entity, Entity> p = Optional.ofNullable(predicate).orElse((attacker, victim) -> true);
         return cancel(EntityDamageByEntityEvent.class, (event) -> p.test(event.getDamager(), event.getEntity()));
     }
 
-    public EasyListener cancelDeath(@Nullable Predicate<Player> predicate) {
+    default EasyListener cancelDeath(@Nullable Predicate<Player> predicate) {
         return cancelDeath(predicate, (event) -> {
             event.setDeathMessage(null);
             event.setKeepInventory(true);
@@ -288,8 +239,8 @@ public class EasyListener implements Listener {
     }
 
     @SuppressWarnings("deprecation")
-    public EasyListener cancelDeath(@Nullable Predicate<Player> predicate,
+    default EasyListener cancelDeath(@Nullable Predicate<Player> predicate,
-                                    @Nullable Consumer<PlayerDeathEvent> handler) {
+                                     @Nullable Consumer<PlayerDeathEvent> handler) {
         final Predicate<Player> p = Optional.ofNullable(predicate).orElse((player) -> true);
         return handle(PlayerDeathEvent.class, (event) -> {
             if (!p.test(event.getEntity())) return;
@@ -298,7 +249,7 @@ public class EasyListener implements Listener {
         });
     }
 
-    public EasyListener cancelSpawn(@Nullable BiPredicate<Entity, Location> predicate) {
+    default EasyListener cancelSpawn(@Nullable BiPredicate<Entity, Location> predicate) {
         final BiPredicate<Entity, Location> p = Optional.ofNullable(predicate).orElse((entity, location) -> !(entity instanceof Player));
         return cancel(EntitySpawnEvent.class, (event) -> p.test(event.getEntity(), event.getLocation()));
     }

src/main/java/cc/carm/lib/easylistener/ListenerManager.java

@@ -0,0 +1,103 @@
+package cc.carm.lib.easylistener;
+
+import org.bukkit.Bukkit;
+import org.bukkit.event.*;
+import org.bukkit.plugin.*;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.lang.reflect.Method;
+import java.util.Optional;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+
+@SuppressWarnings("SameParameterValue")
+public class ListenerManager implements EasyListener {
+
+    protected final Plugin plugin;
+
+    public ListenerManager(Plugin plugin) {
+        this.plugin = plugin;
+    }
+
+    public Plugin getPlugin() {
+        return plugin;
+    }
+
+    /**
+     * 通过 {@link SimplePluginManager} 获取到一个事件类的 {@link HandlerList} 。
+     *
+     * @param eventClass 事件类
+     * @return 事件类的 {@link HandlerList}
+     */
+    private @NotNull HandlerList getEventListeners(@NotNull Class<? extends Event> eventClass) {
+        try {
+            Method method = SimplePluginManager.class.getDeclaredMethod("getEventListeners", Class.class);
+            method.setAccessible(true);
+            return (HandlerList) method.invoke(Bukkit.getPluginManager(), eventClass);
+        } catch (Exception e) {
+            throw new IllegalPluginAccessException(e.toString());
+        }
+    }
+
+    /**
+     * 创建一个事件的执行器实例。
+     *
+     * @param eventClass    事件类
+     * @param eventConsumer 事件执行内容
+     * @param <T>           事件类型
+     * @return 事件的执行器实例
+     */
+    protected <T extends Event> EventExecutor createExecutor(@NotNull Class<T> eventClass,
+                                                             @NotNull Consumer<T> eventConsumer) {
+        return (listener, event) -> {
+            try {
+                if (!eventClass.isAssignableFrom(event.getClass())) return;
+                eventConsumer.accept(eventClass.cast(event));
+            } catch (Throwable t) {
+                throw new EventException(t);
+            }
+        };
+    }
+
+    protected void requireType(@NotNull Class<?> target, @NotNull Class<?> value,
+                               @Nullable String message) throws IllegalArgumentException {
+        if (target.isAssignableFrom(value)) return;
+        if (message == null) throw new IllegalArgumentException();
+        else throw new IllegalArgumentException(message);
+    }
+
+    protected void register(@NotNull Class<? extends Event> eventClass, @NotNull RegisteredListener listener) {
+        getEventListeners(eventClass).register(listener);
+    }
+
+    protected void register(@NotNull Class<? extends Event> eventClass, @NotNull EventExecutor executor,
+                            @NotNull EventPriority priority, boolean ignoreCancelled) {
+        register(eventClass, new RegisteredListener(this, executor, priority, getPlugin(), ignoreCancelled));
+    }
+
+    protected <T extends Event> void register(@NotNull Class<T> eventClass, @NotNull Consumer<T> eventConsumer,
+                                              @NotNull EventPriority priority, boolean ignoreCancelled) {
+        register(eventClass, createExecutor(eventClass, eventConsumer), priority, ignoreCancelled);
+    }
+
+    @Override
+    public <T extends Event> EasyListener handle(@NotNull Class<T> eventClass,
+                                                 @Nullable EventPriority priority, boolean ignoreCancelled,
+                                                 @NotNull Consumer<T> eventConsumer) {
+        register(eventClass, eventConsumer, Optional.ofNullable(priority).orElse(EventPriority.NORMAL), ignoreCancelled);
+        return this;
+    }
+
+    @Override
+    public <T extends Event> EasyListener cancel(@NotNull Class<T> eventClass, @Nullable EventPriority priority,
+                                                 @Nullable Predicate<T> eventPredicate) {
+        requireType(Cancellable.class, eventClass, "Event class " + eventClass.getName() + " is not cancellable");
+
+        final Predicate<T> predicate = Optional.ofNullable(eventPredicate).orElse(t -> true);
+        return handle(eventClass, priority, true, (event) -> {
+            if (predicate.test(event)) ((Cancellable) event).setCancelled(true);
+        });
+    }
+
+}

src/test/java/DemoPlugin.java

@@ -9,7 +9,7 @@ import org.bukkit.plugin.java.JavaPlugin;
 
 public class DemoPlugin extends JavaPlugin {
 
-    protected final EasyListener listeners = new EasyListener(this);
+    protected final EasyListener listeners = EasyListener.create(this);
 
     @Override
     public void onEnable() {