From d5fd6ac27c710a3bd341e3a73b67f16f35016278 Mon Sep 17 00:00:00 2001 From: carm Date: Thu, 23 Jun 2022 00:11:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(java):=20=E8=A1=A5=E5=85=A8=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=A4=A7=E9=83=A8=E5=88=86=E6=96=B9=E6=B3=95=E7=9A=84?= =?UTF-8?q?Javadoc=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pom.xml | 2 +- .../carm/lib/easylisteners/EasyListener.java | 104 ++++++++++++++++-- 2 files changed, 95 insertions(+), 11 deletions(-) diff --git a/pom.xml b/pom.xml index 22a751c..8c2d997 100644 --- a/pom.xml +++ b/pom.xml @@ -13,7 +13,7 @@ cc.carm.lib easylistener - 1.0.0 + 1.0.1 jar EasyListener diff --git a/src/main/java/cc/carm/lib/easylisteners/EasyListener.java b/src/main/java/cc/carm/lib/easylisteners/EasyListener.java index db6d72b..bcc743e 100644 --- a/src/main/java/cc/carm/lib/easylisteners/EasyListener.java +++ b/src/main/java/cc/carm/lib/easylisteners/EasyListener.java @@ -26,6 +26,12 @@ import java.util.function.Consumer; import java.util.function.Function; import java.util.function.Predicate; +/** + * 轻松(做)监听，简单快捷的通用Bukkit插件监听器类库。 + * + * @author CarmJos + * @since 1.0.0 + */ public class EasyListener implements Listener { protected final Plugin plugin; @@ -34,7 +40,13 @@ public class EasyListener implements Listener { this.plugin = plugin; } - private HandlerList getEventListeners(Class eventClass) { + /** + * 通过 {@link SimplePluginManager} 获取到一个事件类的 {@link HandlerList} 。 + * + * @param eventClass 事件类 + * @return 事件类的 {@link HandlerList} + */ + private @NotNull HandlerList getEventListeners(@NotNull Class eventClass) { try { Method method = SimplePluginManager.class.getDeclaredMethod("getEventListeners", Class.class); method.setAccessible(true); @@ -44,6 +56,14 @@ public class EasyListener implements Listener { } } + /** + * 创建一个事件的执行器实例。 + * + * @param eventClass 事件类 + * @param eventConsumer 事件执行内容 + * @param 事件类型 + * @return 事件的执行器实例 + */ private EventExecutor createExecutor(@NotNull Class eventClass, @NotNull Consumer eventConsumer) { return (listener, event) -> { @@ -56,48 +76,112 @@ public class EasyListener implements Listener { }; } - protected void register(Class eventClass, RegisteredListener listener) { + protected void register(@NotNull Class eventClass, @NotNull RegisteredListener listener) { getEventListeners(eventClass).register(listener); } + protected void register(@NotNull Class 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 {@link Event} 事件的类型 + * @return 本实例 + */ public EasyListener handle(@NotNull Class eventClass, @NotNull Consumer eventConsumer) { return handle(eventClass, null, eventConsumer); } + /** + * 处理一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param ignoreCancelled 是否忽略掉已经被取消的事件 + * @param eventConsumer 处理方法 + * @param {@link Event} 事件的类型 + * @return 本实例 + */ public EasyListener handle(@NotNull Class eventClass, boolean ignoreCancelled, @NotNull Consumer eventConsumer) { return handle(eventClass, null, ignoreCancelled, eventConsumer); } + /** + * 处理一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param priority {@link EventPriority} 事件处理优先级 + * @param eventConsumer 处理方法 + * @param {@link Event} 事件的类型 + * @return 本实例 + */ public EasyListener handle(@NotNull Class eventClass, @Nullable EventPriority priority, @NotNull Consumer eventConsumer) { return handle(eventClass, priority, false, eventConsumer); } - + /** + * 处理一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param priority {@link EventPriority} 事件处理优先级 + * @param ignoreCancelled 是否忽略掉已经被取消的事件 + * @param eventConsumer 处理方法 + * @param {@link Event} 事件的类型 + * @return 本实例 + */ public EasyListener handle(@NotNull Class eventClass, @Nullable EventPriority priority, boolean ignoreCancelled, @NotNull Consumer eventConsumer) { final EventPriority eventPriority = Optional.ofNullable(priority).orElse(EventPriority.NORMAL); - - RegisteredListener registeredListener = new RegisteredListener( - this, createExecutor(eventClass, eventConsumer), - eventPriority, this.plugin, ignoreCancelled - ); - register(eventClass, registeredListener); + final EventExecutor executor = createExecutor(eventClass, eventConsumer); + register(eventClass, executor, eventPriority, ignoreCancelled); return this; } + /** + * 无判别地取消一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param {@link Event} 事件的类型，必须实现 {@link Cancellable} 。 + * @return 本实例 + * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常 + */ public EasyListener cancel(@NotNull Class eventClass) { return cancel(eventClass, null, null); } + /** + * 有条件地取消一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param eventPredicate 判断事件是否可以取消的条件 + * @param {@link Event} 事件的类型，必须实现 {@link Cancellable} 。 + * @return 本实例 + * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常 + */ public EasyListener cancel(@NotNull Class eventClass, @Nullable Predicate eventPredicate) { return cancel(eventClass, null, eventPredicate); } - public EasyListener cancel(@NotNull Class eventClass, @Nullable EventPriority priority, @Nullable Predicate eventPredicate) { + /** + * 有条件地取消一个事件。 + * + * @param eventClass {@link Event} 事件类 + * @param priority {@link EventPriority} 事件处理优先级 + * @param eventPredicate 判断事件是否可以取消的条件 + * @param {@link Event} 事件的类型，必须实现 {@link Cancellable} 。 + * @return 本实例 + * @throws IllegalArgumentException 如果事件没有实现 {@link Cancellable} 则抛出此异常 + */ + public EasyListener cancel(@NotNull Class eventClass, @Nullable EventPriority priority, + @Nullable Predicate eventPredicate) { if (!Cancellable.class.isAssignableFrom(eventClass)) { throw new IllegalArgumentException("Event class " + eventClass.getName() + " is not cancellable"); }