Class StatefulHandler

java.lang.Object
io.fluxzero.sdk.tracking.handling.StatefulHandler
All Implemented Interfaces:
Handler<DeserializingMessage>
public class StatefulHandler extends Object implements Handler<DeserializingMessage>
A Handler implementation for classes annotated with Stateful, responsible for resolving and invoking stateful handler instances based on Association metadata.

This handler enables long-lived, stateful components to participate in message processing. It ensures that:

  • Messages are routed to the correct instance(s) based on matching association keys
  • Instances are automatically created, updated, or deleted depending on the result of handler methods
  • Static methods may initialize new handler instances (e.g., factory methods on creation events)
  • Association routing is supported via property-based or method-level annotations

Routing Logic

The handler uses the following mechanisms to determine message dispatch:
  • Association annotations on fields and methods define the routing keys used to match incoming messages to stateful instances.
  • EntityId defines the identity of the handler, used when persisting or retrieving state.
  • If no matching instances are found, static methods marked with @Handle... and @Association(always = true) may be invoked to initialize new instances.
  • Fallback routing via RoutingKey annotations or message metadata is also supported.

Persistence and Lifecycle

  • The resolved handler instances are loaded and stored via a HandlerRepository (typically backed by the DocumentStore).
  • If a handler method returns a new instance, it replaces the current state.
  • If a handler method returns null, the instance is removed from storage.

Batch-Aware Behavior

  • Routing decisions may respect the current Tracker context, segment ownership, and routing constraints.
  • Within a batch, state changes may be staged locally before committing (when commitInBatch = true).

Internal Mechanics

  • Associations are lazily resolved and memoized for performance.
  • Handler invocation is delegated via HandlerMatcher and HandlerInvoker abstractions.
  • Support is provided for multiple matches and combined invocation across entries.
See Also: