Class StatefulHandler
java.lang.Object
io.fluxcapacitor.javaclient.tracking.handling.StatefulHandler
- All Implemented Interfaces:
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 theDocumentStore
). - 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
andHandlerInvoker
abstractions. - Support is provided for multiple matches and combined invocation across entries.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static class
protected class
Nested classes/interfaces inherited from interface io.fluxcapacitor.common.handling.Handler
Handler.DelegatingHandler<M>
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
associations
(DeserializingMessage message) protected Boolean
canTrackerHandle
(DeserializingMessage message, String routingKey) getInvoker
(DeserializingMessage message) Returns aHandlerInvoker
capable of processing the given message, if available.protected boolean
includedPayload
(Object payload, StatefulHandler.AssociationValue association) toString()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface io.fluxcapacitor.common.handling.Handler
getTargetClass, or
-
Constructor Details
-
StatefulHandler
public StatefulHandler()
-
-
Method Details
-
getInvoker
Description copied from interface:Handler
Returns aHandlerInvoker
capable of processing the given message, if available.- Specified by:
getInvoker
in interfaceHandler<DeserializingMessage>
- Parameters:
message
- the message to be handled- Returns:
- an optional
HandlerInvoker
if this handler can handle the message; otherwiseOptional.empty()
-
alreadyFiltered
-
canTrackerHandle
-
associations
-
includedPayload
-
toString
-