Class CaptchaEventDispatcher

java.lang.Object
cloud.opencode.base.captcha.CaptchaEventDispatcher
All Implemented Interfaces:
CaptchaEventListener
public final class CaptchaEventDispatcher extends Object implements CaptchaEventListener
Captcha Event Dispatcher - Manages and dispatches CAPTCHA lifecycle events 验证码事件分发器 - 管理和分发验证码生命周期事件

This class implements CaptchaEventListener and acts as a composite dispatcher, forwarding events to all registered listeners. Each listener invocation is exception-isolated: a failure in one listener does not prevent others from being notified.

此类实现 CaptchaEventListener 并充当复合分发器，将事件转发给所有注册的监听器。 每个监听器调用都是异常隔离的：一个监听器的失败不会阻止其他监听器被通知。

Features | 主要功能:

  • Thread-safe listener registration and removal - 线程安全的监听器注册和移除
  • Exception isolation per listener - 每个监听器异常隔离
  • CopyOnWriteArrayList for safe concurrent iteration - 使用 CopyOnWriteArrayList 安全并发迭代
  • Implements CaptchaEventListener for easy composition - 实现 CaptchaEventListener 便于组合

Usage Examples | 使用示例:

CaptchaEventDispatcher dispatcher = new CaptchaEventDispatcher();
dispatcher.addListener(new LoggingListener());
dispatcher.addListener(new MetricsListener());
dispatcher.onGenerated(captcha);  // both listeners notified

Performance | 性能特性:

  • Event dispatch: O(n) where n is listener count - 事件分发: O(n)，n 为监听器数量
  • Add/remove: O(n) copy overhead (CopyOnWriteArrayList) - 添加/移除: O(n) 复制开销

Security | 安全性:

  • Thread-safe: Yes (CopyOnWriteArrayList) - 线程安全: 是
  • Null-safe: No (listener must not be null) - 空值安全: 否（监听器不能为空）
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • CaptchaEventDispatcher

      public CaptchaEventDispatcher()

  • Method Details

    • addListener

      public void addListener(CaptchaEventListener listener)
      Registers an event listener. 注册事件监听器。
      Parameters:
      listener - the listener to add | 要添加的监听器
      Throws:
      NullPointerException - if listener is null | 如果监听器为 null

    • removeListener

      public boolean removeListener(CaptchaEventListener listener)
      Removes an event listener. 移除事件监听器。
      Parameters:
      listener - the listener to remove | 要移除的监听器
      Returns:
      true if the listener was found and removed | 如果找到并移除了监听器返回 true

    • listenerCount

      public int listenerCount()
      Returns the number of registered listeners. 返回已注册的监听器数量。
      Returns:
      the listener count | 监听器数量

    • onGenerated

      public void onGenerated(Captcha captcha)
      Dispatches a generation event to all registered listeners. 向所有注册的监听器分发生成事件。

      Each listener is invoked in registration order. Exceptions thrown by individual listeners are caught and suppressed to ensure all listeners are notified.

      按注册顺序调用每个监听器。单个监听器抛出的异常会被捕获并抑制， 以确保所有监听器都被通知。

      Specified by:
      onGenerated in interface CaptchaEventListener
      Parameters:
      captcha - the generated CAPTCHA | 生成的验证码

    • onValidationSuccess

      public void onValidationSuccess(String captchaId)
      Dispatches a validation success event to all registered listeners. 向所有注册的监听器分发验证成功事件。
      Specified by:
      onValidationSuccess in interface CaptchaEventListener
      Parameters:
      captchaId - the CAPTCHA ID | 验证码 ID

    • onValidationFailure

      public void onValidationFailure(String captchaId, ValidationResult.ResultCode reason)
      Dispatches a validation failure event to all registered listeners. 向所有注册的监听器分发验证失败事件。
      Specified by:
      onValidationFailure in interface CaptchaEventListener
      Parameters:
      captchaId - the CAPTCHA ID | 验证码 ID
      reason - the failure reason code | 失败原因代码