cloud.opencode.base.event.OpenEvent

All Implemented Interfaces:: AutoCloseable

public final class OpenEvent extends Object implements AutoCloseable

OpenEvent - Event Bus with dead event detection, interceptors, sticky events, and metrics 事件总线 - 支持死事件检测、拦截器、粘性事件和指标

The main entry point for event-driven architecture support. Provides publish/subscribe pattern with virtual thread async processing, event filtering, interceptor chains, sticky events, subscription handles, dead event detection, and operational metrics.

事件驱动架构支持的主入口点。提供基于虚拟线程异步处理的发布/订阅模式，支持事件过滤、拦截器链、粘性事件、订阅句柄、死事件检测和运行指标。

Features | 主要功能:

Publish/Subscribe pattern - 发布/订阅模式
Sync/Async event processing - 同步/异步事件处理
Event priority and cancellation - 事件优先级和取消
Dead event detection - 死事件检测
Subscription handles (AutoCloseable) - 订阅句柄（自动关闭）
Event filtering (Predicate) - 事件过滤（谓词）
Interceptor chain - 拦截器链
Sticky events - 粘性事件
Operational metrics - 运行指标
Virtual thread async processing - 虚拟线程异步处理

Usage Examples | 使用示例:

// Get default instance
OpenEvent eventBus = OpenEvent.getDefault();

// Subscribe with Subscription handle
Subscription sub = eventBus.subscribe(UserEvent.class, e -> handle(e));
sub.unsubscribe(); // precise unsubscribe

// Subscribe with filter
eventBus.subscribe(OrderEvent.class, e -> handle(e), e -> e.getAmount() > 100);

// Dead event monitoring
eventBus.subscribe(DeadEvent.class, dead ->
    log.warn("Unhandled: {}", dead.getOriginalEvent()));

// Sticky events
eventBus.publishSticky(new ConfigEvent(config));
eventBus.subscribe(ConfigEvent.class, e -> applyConfig(e)); // receives immediately

// Interceptors
OpenEvent custom = OpenEvent.builder()
    .interceptor(new LoggingInterceptor())
    .build();

Security | 安全性:

Thread-safe: Yes (concurrent data structures) - 线程安全: 是（并发数据结构）

Since:

JDK 25, opencode-base-event V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

OpenEvent.Builder

Builder for OpenEvent OpenEvent构建器
Method Summary

Modifier and Type

Method

Description

void

addInterceptor(EventInterceptor interceptor)

Add an event interceptor 添加事件拦截器

static OpenEvent.Builder

builder()

Create a builder for custom configuration 创建用于自定义配置的构建器

void

clearAllStickyEvents()

Remove all sticky events, releasing references for GC.

void

close()

Shuts down the async executor and dispatchers, releasing resources.

static OpenEvent

create()

Create a new OpenEvent instance 创建新的OpenEvent实例

static OpenEvent

getDefault()

Get the default singleton instance 获取默认单例实例

EventStore

getEventStore()

Get the event store 获取事件存储

EventBusMetrics

getMetrics()

Get current event bus metrics snapshot 获取当前事件总线指标快照

<E extends Event> E

getStickyEvent(Class<E> eventType)

Get the last sticky event of the given type 获取指定类型的最后一个粘性事件

<E extends Event> void

on(Class<E> eventType, EventListener<E> listener)

Register a lambda listener for an event type (legacy void return) 为事件类型注册Lambda监听器（兼容旧接口，无返回值）

<E extends Event> void

on(Class<E> eventType, EventListener<E> listener, boolean async)

Register a lambda listener with async option (legacy void return) 使用异步选项注册Lambda监听器（兼容旧接口，无返回值）

<E extends Event> void

on(Class<E> eventType, EventListener<E> listener, boolean async, int priority)

Register a lambda listener with async and priority options (legacy void return) 使用异步和优先级选项注册Lambda监听器（兼容旧接口，无返回值）

void

publish(Event event)

Publish an event synchronously 同步发布事件

<T> void

publish(T data)

Publish data as a DataEvent 将数据作为DataEvent发布

<T> void

publish(T data, String source)

Publish data as a DataEvent with source 将数据作为带来源的DataEvent发布

boolean

publishAndWait(Event event, Duration timeout)

Publish and wait for processing to complete 发布并等待处理完成

CompletableFuture<Void>

publishAsync(Event event)

Publish an event asynchronously 异步发布事件

void

publishSticky(Event event)

Publish a sticky event (stored and replayed to future subscribers) 发布粘性事件（存储并重放给未来的订阅者）

void

register(Object subscriber)

Register an object's @Subscribe methods as event listeners 将对象的@Subscribe方法注册为事件监听器

void

removeInterceptor(EventInterceptor interceptor)

Remove an event interceptor 移除事件拦截器

<E extends Event> E

removeStickyEvent(Class<E> eventType)

Remove and return the sticky event of the given type 移除并返回指定类型的粘性事件

void

resetMetrics()

Reset all metrics counters 重置所有指标计数器

void

setEventStore(EventStore store)

Set the event store 设置事件存储

void

setExceptionHandler(EventExceptionHandler handler)

Set the exception handler 设置异常处理器

<E extends Event> Subscription

subscribe(Class<E> eventType, EventListener<E> listener)

Subscribe a listener and return a Subscription handle 订阅监听器并返回订阅句柄

<E extends Event> Subscription

subscribe(Class<E> eventType, EventListener<E> listener, Predicate<E> filter)

Subscribe a listener with a filter predicate 使用过滤谓词订阅监听器

<E extends Event> Subscription

subscribe(Class<E> eventType, EventListener<E> listener, Predicate<E> filter, boolean async, int priority)

Subscribe a listener with full configuration 使用完整配置订阅监听器

void

unregister(Object subscriber)

Unregister all listeners from a subscriber 从订阅者注销所有监听器

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- getDefault
  
  public static OpenEvent getDefault()
  
  Get the default singleton instance 获取默认单例实例
  
  Returns:
  
  the default OpenEvent instance | 默认OpenEvent实例
- create
  
  public static OpenEvent create()
  
  Create a new OpenEvent instance 创建新的OpenEvent实例
  
  Returns:
  
  new OpenEvent instance | 新的OpenEvent实例
- builder
  
  public static OpenEvent.Builder builder()
  
  Create a builder for custom configuration 创建用于自定义配置的构建器
  
  Returns:
  
  new Builder | 新的Builder
- register
  
  public void register(Object subscriber)
  
  Register an object's @Subscribe methods as event listeners 将对象的@Subscribe方法注册为事件监听器
  
  Parameters:
  
  subscriber - the subscriber object | 订阅者对象
  
  Throws:
  
  EventException - if method signature is invalid | 如果方法签名无效
- on
  
  public <E extends Event> void on(Class<E> eventType, EventListener<E> listener)
  
  Register a lambda listener for an event type (legacy void return) 为事件类型注册Lambda监听器（兼容旧接口，无返回值）
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
- on
  
  public <E extends Event> void on(Class<E> eventType, EventListener<E> listener, boolean async)
  
  Register a lambda listener with async option (legacy void return) 使用异步选项注册Lambda监听器（兼容旧接口，无返回值）
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
  
  async - true for async execution | 异步执行为true
- on
  
  public <E extends Event> void on(Class<E> eventType, EventListener<E> listener, boolean async, int priority)
  
  Register a lambda listener with async and priority options (legacy void return) 使用异步和优先级选项注册Lambda监听器（兼容旧接口，无返回值）
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
  
  async - true for async execution | 异步执行为true
  
  priority - listener priority (higher = earlier) | 监听器优先级（越高越早）
- subscribe
  
  public <E extends Event> Subscription subscribe(Class<E> eventType, EventListener<E> listener)
  
  Subscribe a listener and return a Subscription handle 订阅监听器并返回订阅句柄
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
  
  Returns:
  
  subscription handle for lifecycle management | 用于生命周期管理的订阅句柄
- subscribe
  
  public <E extends Event> Subscription subscribe(Class<E> eventType, EventListener<E> listener, Predicate<E> filter)
  
  Subscribe a listener with a filter predicate 使用过滤谓词订阅监听器
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
  
  filter - predicate to filter events, null means accept all | 过滤事件的谓词，null 表示接受全部
  
  Returns:
  
  subscription handle | 订阅句柄
- subscribe
  
  public <E extends Event> Subscription subscribe(Class<E> eventType, EventListener<E> listener, Predicate<E> filter, boolean async, int priority)
  
  Subscribe a listener with full configuration 使用完整配置订阅监听器
  
  Type Parameters:
  
  E - the event type parameter | 事件类型参数
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  listener - the event listener | 事件监听器
  
  filter - predicate to filter events, null means accept all | 过滤事件的谓词，null 表示接受全部
  
  async - true for async execution | 异步执行为true
  
  priority - listener priority (higher = earlier) | 监听器优先级（越高越早）
  
  Returns:
  
  subscription handle | 订阅句柄
- unregister
  
  public void unregister(Object subscriber)
  
  Unregister all listeners from a subscriber 从订阅者注销所有监听器
  
  Parameters:
  
  subscriber - the subscriber to unregister | 要注销的订阅者
- publish
  
  public void publish(Event event)
  
  Publish an event synchronously 同步发布事件
  
  Parameters:
  
  event - the event to publish | 要发布的事件
- publishAsync
  
  public CompletableFuture<Void> publishAsync(Event event)
  
  Publish an event asynchronously 异步发布事件
  
  Parameters:
  
  event - the event to publish | 要发布的事件
  
  Returns:
  
  CompletableFuture that completes when processing is done | 处理完成时完成的CompletableFuture
- publish
  
  public <T> void publish(T data)
  
  Publish data as a DataEvent 将数据作为DataEvent发布
  
  Type Parameters:
  
  T - the data type | 数据类型
  
  Parameters:
  
  data - the data to publish | 要发布的数据
- publish
  
  public <T> void publish(T data, String source)
  
  Publish data as a DataEvent with source 将数据作为带来源的DataEvent发布
  
  Type Parameters:
  
  T - the data type | 数据类型
  
  Parameters:
  
  data - the data to publish | 要发布的数据
  
  source - the event source | 事件来源
- publishAndWait
  
  public boolean publishAndWait(Event event, Duration timeout)
  
  Publish and wait for processing to complete 发布并等待处理完成
  
  Parameters:
  
  event - the event to publish | 要发布的事件
  
  timeout - max time to wait | 最大等待时间
  
  Returns:
  
  true if completed within timeout | 如果在超时内完成返回true
- publishSticky
  
  public void publishSticky(Event event)
  
  Publish a sticky event (stored and replayed to future subscribers) 发布粘性事件（存储并重放给未来的订阅者）
  The event is stored per-type (last one wins) and also published to current listeners. Future subscribers for this event type will immediately receive the stored sticky event.
  
  事件按类型存储（最后一个生效），并同时发布给当前监听器。该事件类型的未来订阅者将立即收到存储的粘性事件。
  
  Parameters:
  
  event - the event to publish as sticky | 要作为粘性事件发布的事件
- getStickyEvent
  
  public <E extends Event> E getStickyEvent(Class<E> eventType)
  
  Get the last sticky event of the given type 获取指定类型的最后一个粘性事件
  
  Type Parameters:
  
  E - the event type | 事件类型
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  Returns:
  
  the sticky event or null if none | 粘性事件，如果没有则为 null
- removeStickyEvent
  
  public <E extends Event> E removeStickyEvent(Class<E> eventType)
  
  Remove and return the sticky event of the given type 移除并返回指定类型的粘性事件
  
  Type Parameters:
  
  E - the event type | 事件类型
  
  Parameters:
  
  eventType - the event type class | 事件类型类
  
  Returns:
  
  the removed sticky event or null | 移除的粘性事件，如果没有则为 null
- clearAllStickyEvents
  
  public void clearAllStickyEvents()
  
  Remove all sticky events, releasing references for GC. 移除所有粘性事件，释放引用以便 GC。
  Sticky events are retained indefinitely until explicitly removed. Call this method periodically or on shutdown to prevent memory leaks in long-running applications.
  
  粘性事件会一直保留直到被显式移除。在长时间运行的应用中定期调用或在关闭时调用此方法以防止内存泄漏。
  
  Since:
  
  JDK 25, opencode-base-event V1.0.3
- addInterceptor
  
  public void addInterceptor(EventInterceptor interceptor)
  
  Add an event interceptor 添加事件拦截器
  
  Parameters:
  
  interceptor - the interceptor to add | 要添加的拦截器
- removeInterceptor
  
  public void removeInterceptor(EventInterceptor interceptor)
  
  Remove an event interceptor 移除事件拦截器
  
  Parameters:
  
  interceptor - the interceptor to remove | 要移除的拦截器
- getMetrics
  
  public EventBusMetrics getMetrics()
  
  Get current event bus metrics snapshot 获取当前事件总线指标快照
  
  Returns:
  
  metrics snapshot | 指标快照
- resetMetrics
  
  public void resetMetrics()
  
  Reset all metrics counters 重置所有指标计数器
- setEventStore
  
  public void setEventStore(EventStore store)
  
  Set the event store 设置事件存储
  
  Parameters:
  
  store - the event store | 事件存储
- getEventStore
  
  public EventStore getEventStore()
  
  Get the event store 获取事件存储
  
  Returns:
  
  the event store or null | 事件存储或null
- setExceptionHandler
  
  public void setExceptionHandler(EventExceptionHandler handler)
  
  Set the exception handler 设置异常处理器
  
  Parameters:
  
  handler - the exception handler | 异常处理器
- close
  
  public void close()
  
  Shuts down the async executor and dispatchers, releasing resources. 关闭异步执行器和分发器，释放资源。
  
  Specified by:
  
  close in interface AutoCloseable

Class OpenEvent

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Details

getDefault

create

builder

register

on

on

on

subscribe

subscribe

subscribe

unregister

publish

publishAsync

publish

publish

publishAndWait

publishSticky

getStickyEvent

removeStickyEvent

clearAllStickyEvents

addInterceptor

removeInterceptor

getMetrics

resetMetrics

setEventStore

getEventStore

setExceptionHandler

close