Class AbstractWorkflowObserver<T extends JobEvent>
java.lang.Object
ai.redouble.nucleo.harness.AbstractWorkflowObserver<T>
- Type Parameters:
T- the type of events this observer handles
- All Implemented Interfaces:
JobObserver<T>
- Direct Known Subclasses:
StreamingLogObserver
public abstract class AbstractWorkflowObserver<T extends JobEvent>
extends Object
implements JobObserver<T>
Base class for observing events from a specific workflow.
This abstract class simplifies workflow-specific event observation by:
- Automatically filtering events to match a specific workflow ID
- Managing observer lifecycle with optional inactivity timeouts
- Providing automatic cleanup on workflow termination events
- Tracking last event time for staleness detection
Key Features:
- Workflow Filtering: Only events from the specified workflow ID are delivered
- Automatic Cleanup: Unsubscribes when receiving
WorkflowTerminationEvent - Inactivity Timeout: Optional timeout after which the observer is marked stale
- Thread-Safe: All public methods are thread-safe
Observer Equality and Deduplication:
By default, each observer instance is considered unique (uses Object identity).
Subclasses SHOULD override equals() and hashCode() if they want
deduplication behavior. When implementing equality, consider:
- workflowId: Always include - observers for different workflows are different
- Instance-specific state: Include fields that make this observer unique (e.g., WebSocket session ID, user ID, configuration flags)
- Shared state: Don't include mutable or shared fields like lastEventTime
Example - Session-based equality:
class WebSocketObserver extends AbstractWorkflowObserver<JobEvent> {
private final String sessionId;
@Override
public boolean equals(Object obj) {
if (this == obj) return true;
if (!(obj instanceof WebSocketObserver)) return false;
WebSocketObserver that = (WebSocketObserver) obj;
return Objects.equals(workflowId, that.workflowId) &&
Objects.equals(sessionId, that.sessionId);
}
@Override
public int hashCode() {
return Objects.hash(workflowId, sessionId);
}
}
Usage Example:
// Create a progress observer for a specific workflow
class ProgressObserver extends AbstractWorkflowObserver<JobProgressEvent<?>> {
ProgressObserver(String workflowId) {
super(workflowId, Duration.ofMinutes(5)); // 5-minute timeout
}
@Override
protected void handleEvent(JobProgressEvent<?> event) {
System.out.println("Progress: " + event.getProgressPercent() + "%");
}
}
// Register with JobDispatcher
JobDispatcher dispatcher = JobDispatcher.getInstance();
ProgressObserver observer = new ProgressObserver(workflowId);
dispatcher.observeWorkflow(observer, JobProgressEvent.class);
- Since:
- 0.1 (2025-10-11)
- Author:
- Andrey Santrosyan
-
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedAbstractWorkflowObserver(String workflowId) Creates a workflow observer without inactivity timeout.protectedAbstractWorkflowObserver(String workflowId, Duration inactivityTimeout) Creates a workflow observer with specified inactivity timeout. -
Method Summary
Modifier and TypeMethodDescriptionGets the time of the last received event.Returns a predicate for filtering events at the MessageBus level.Gets the workflow ID being observed.protected abstract voidhandleEvent(T event) Handles a workflow event.booleanChecks if this observer has an inactivity timeout configured.booleanisStale()Checks if this observer should be considered stale and eligible for cleanup.final voidProcess a job event.protected voidCalled when the observer is being cleaned up (either due to staleness or self-cleanup).protected booleanshouldSelfCleanup(T event) Determines if the observer should self-cleanup based on the event.
-
Field Details
-
workflowId
-
-
Constructor Details
-
AbstractWorkflowObserver
-
AbstractWorkflowObserver
Creates a workflow observer without inactivity timeout.- Parameters:
workflowId- the workflow ID to observe
-
-
Method Details
-
getPredicate
Description copied from interface:JobObserverReturns a predicate for filtering events at the MessageBus level. Called once during subscription.- Specified by:
getPredicatein interfaceJobObserver<T extends JobEvent>- Returns:
- predicate to filter events, or null to accept all events of type T
-
observe
Description copied from interface:JobObserverProcess a job event. Runs in a separate virtual thread. Must handle its own resources and exceptions.- Specified by:
observein interfaceJobObserver<T extends JobEvent>- Parameters:
event- the job event to process
-
handleEvent
Handles a workflow event. Subclasses must implement this to process events.- Parameters:
event- the workflow event to handle
-
shouldSelfCleanup
Determines if the observer should self-cleanup based on the event. By default, returns true if the event implements WorkflowTerminationEvent, indicating the workflow has definitively ended. Subclasses can override to customize cleanup behavior.- Parameters:
event- the event that might trigger cleanup- Returns:
- true if the observer should cleanup and unsubscribe
-
onCleanup
protected void onCleanup()Called when the observer is being cleaned up (either due to staleness or self-cleanup). Subclasses can override this to perform cleanup actions. -
isStale
public boolean isStale()Description copied from interface:JobObserverChecks if this observer should be considered stale and eligible for cleanup. Called periodically by the MessageBus cleanup mechanism.Observers can implement this to indicate when they should be automatically unsubscribed (e.g., after a period of inactivity or reaching a max event count).
- Specified by:
isStalein interfaceJobObserver<T extends JobEvent>- Returns:
- true if this observer is stale and should be cleaned up, false otherwise
-
getWorkflowId
-
getLastEventTime
Gets the time of the last received event.- Returns:
- instant of last event
-
hasInactivityTimeout
public boolean hasInactivityTimeout()Checks if this observer has an inactivity timeout configured.- Returns:
- true if timeout is configured
-