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 Details

    • workflowId

      protected final String workflowId
  • Constructor Details

    • AbstractWorkflowObserver

      protected AbstractWorkflowObserver(String workflowId, Duration inactivityTimeout)
      Creates a workflow observer with specified inactivity timeout.
      Parameters:
      workflowId - the workflow ID to observe
      inactivityTimeout - duration after which the observer is considered stale (null for no timeout)
    • AbstractWorkflowObserver

      protected AbstractWorkflowObserver(String workflowId)
      Creates a workflow observer without inactivity timeout.
      Parameters:
      workflowId - the workflow ID to observe
  • Method Details

    • getPredicate

      public final Predicate<T> getPredicate()
      Description copied from interface: JobObserver
      Returns a predicate for filtering events at the MessageBus level. Called once during subscription.
      Specified by:
      getPredicate in interface JobObserver<T extends JobEvent>
      Returns:
      predicate to filter events, or null to accept all events of type T
    • observe

      public final void observe(T event)
      Description copied from interface: JobObserver
      Process a job event. Runs in a separate virtual thread. Must handle its own resources and exceptions.
      Specified by:
      observe in interface JobObserver<T extends JobEvent>
      Parameters:
      event - the job event to process
    • handleEvent

      protected abstract void handleEvent(T event)
      Handles a workflow event. Subclasses must implement this to process events.
      Parameters:
      event - the workflow event to handle
    • shouldSelfCleanup

      protected boolean shouldSelfCleanup(T event)
      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: JobObserver
      Checks 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:
      isStale in interface JobObserver<T extends JobEvent>
      Returns:
      true if this observer is stale and should be cleaned up, false otherwise
    • getWorkflowId

      public String getWorkflowId()
      Gets the workflow ID being observed.
      Returns:
      the workflow ID
    • getLastEventTime

      public Instant 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