Implement new module with EventBus API

[JavaSaBr]

Overview

This branch introduces a new rlib-eventbus module with a very typed low-overhead event bus API. It adds strongly typed subscription/publishing contracts, default implementation with sync/background dispatch, type-id consistency guards, comprehensive edge-case tests, API naming cleanup, and updated documentation (Javadocs, README usage examples, and event flow diagram).

Changes Summary

1. New module: typed low-overhead EventBus

• Added a new Gradle module :rlib-eventbus and wired it into settings.gradle
• Added rlib-eventbus/build.gradle with publishing/java configuration and API dependency on rlib-collections
• Introduced API surface in EventBus:
  • subscribe(...) / unsubscribe(...)
  • send(...) (synchronous)
  • sendInBackground(...) (background dispatch)
  • Nested contracts TypeIdSet, TypeIdFactory, TypeId, and Event

2. Core implementation and dispatch model

• Added DefaultEventBus with:
  • Copy-on-modify consumer lists indexed by numeric TypeId.id()
  • Lazy type registration and sparse index expansion
  • Event-type to type-id consistency guard (IllegalStateException on conflicting IDs)
  • Validation for invalid negative type IDs (IllegalArgumentException)
  • Background dispatch through ForkJoinPool.commonPool()
• Added DefaultTypeIdFactory with per-TypeIdSet typed factories and stable per-event type IDs

3. Event flow diagram

flowchart TD
    A["Create TypeIdFactory<br/>EventBusFactory.createTypeIdFactory"] --> B["Create EventBus<br/>EventBusFactory.createEventBus"]
    B --> C["Resolve TypeId<br/>typeIdFactory.typeIdOf event type"]
    C --> D["Subscribe consumer<br/>eventBus.subscribe typeId consumer"]
    D --> E{Publish mode}
    E -->|send| F["Dispatch in caller thread"]
    E -->|sendInBackground| G["Schedule on executor"]
    G --> H["Dispatch on background thread"]
    F --> I["Lookup consumers by typeId id"]
    H --> I
    I --> J["Invoke subscribed consumers"]

Loading

4. Usage samples

Synchronous publish:

interface AppEvents extends EventBus.TypeIdSet {}

record UserCreated(
    String userId,
    EventBus.TypeId<AppEvents, UserCreated> typeId
) implements EventBus.Event<AppEvents> {}

var typeIdFactory = EventBusFactory.createTypeIdFactory(AppEvents.class);
var eventBus = EventBusFactory.createEventBus(typeIdFactory);
var userCreatedTypeId = typeIdFactory.typeIdOf(UserCreated.class);

eventBus.subscribe(userCreatedTypeId, event ->
    System.out.println("Created: " + event.userId()));

eventBus.send(new UserCreated("user-42", userCreatedTypeId));

Background publish:

eventBus.sendInBackground(new UserCreated("user-43", userCreatedTypeId));

5. Test coverage for happy paths and edge cases

• Added DefaultEventBusTest with 10 tests covering:
  • Multi-consumer delivery across different event types
  • Negative TypeId handling for send/unsubscribe
  • Out-of-range/sparse TypeId behavior
  • Unsubscribe lifecycle (including duplicate unsubscribe)
  • Conflicting type-id detection for same event type
  • Background dispatch behavior with deterministic latch-based assertion

Testing & Validation

• ./gradlew --no-daemon :rlib-eventbus:test ✅
• ./gradlew --no-daemon :rlib-eventbus:compileJava ✅
• Full branch verification before merge: ./gradlew clean build (recommended)

[Copilot]

Pull request overview

This PR adds a new rlib-eventbus module that introduces a typed EventBus API and default implementation for synchronous and background event dispatch.

Changes:

• Wires :rlib-eventbus into the Gradle multi-project build and README usage docs.
• Adds EventBus API contracts, factory methods, package nullness metadata, and default implementations.
• Adds tests covering delivery, unsubscribe behavior, invalid IDs, sparse IDs, conflicts, and async dispatch.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
settings.gradle	Includes the new EventBus module in the build.
build.gradle	Bumps the root project version.
README.md	Documents the new module and adds a usage example.
rlib-eventbus/build.gradle	Defines the new module and its collections dependency.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/EventBus.java	Adds the public EventBus API and nested type-id contracts.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/EventBusFactory.java	Adds factory methods for type-id factories and event buses.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/impl/DefaultEventBus.java	Implements subscription, unsubscription, synchronous dispatch, and background dispatch.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/impl/DefaultTypeIdFactory.java	Implements stable per-namespace TypeId creation.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/package-info.java	Marks the public EventBus package as null-marked.
rlib-eventbus/src/main/java/javasabr/rlib/eventbus/impl/package-info.java	Marks the implementation package as null-marked.
rlib-eventbus/src/test/java/javasabr/rlib/eventbus/DefaultEventBusTest.java	Adds unit coverage for core EventBus behaviors and edge cases.

[github-actions]

Overall Project	56.75%	🍏

There is no coverage information present for the Files changed

[github-actions]

Overall Project	56.79%	🍏

There is no coverage information present for the Files changed

[github-actions]

Overall Project	57.05% -0.01%	🍏
Files changed	99.23%	🍏

File	Coverage
EventBusFactory.java	100%	🍏
DefaultEventBus.java	100%	🍏
DefaultTypeIdFactory.java	96.92% -3.08%	🍏

[github-actions]

Overall Project	57.06% -0.01%	🍏
Files changed	99.23%	🍏

File	Coverage
EventBusFactory.java	100%	🍏
DefaultEventBus.java	100%	🍏
DefaultTypeIdFactory.java	96.92% -3.08%	🍏