Package software.amazon.lambda.durable.operation

Class BaseDurableOperation

java.lang.Object
software.amazon.lambda.durable.operation.BaseDurableOperation
Direct Known Subclasses:
SerializableDurableOperation, WaitOperation
public abstract class BaseDurableOperation extends Object
Base class for all durable operations (STEP, WAIT, etc.).

Key methods:

  • execute() starts the operation (returns immediately)
  • get() blocks until complete and returns the result

The separation allows:

  • Starting multiple async operations quickly
  • Blocking on results later when needed
  • Proper thread coordination via future

  • Field Details

  • Constructor Details

    • BaseDurableOperation

      protected BaseDurableOperation(OperationIdentifier operationIdentifier, DurableContextImpl durableContext, BaseDurableOperation parentOperation)

    • BaseDurableOperation

      protected BaseDurableOperation(OperationIdentifier operationIdentifier, DurableContextImpl durableContext, BaseDurableOperation parentOperation, boolean isVirtual)
      Constructs a new durable operation.
      Parameters:
      operationIdentifier - the unique identifier for this operation
      durableContext - the parent context this operation belongs to
      parentOperation - the parent operation if this is a branch/iteration of a ConcurrencyOperation
      isVirtual - whether this is a virtual operation that should not be persisted

  • Method Details

    • getCompletionFuture

      public CompletableFuture<BaseDurableOperation> getCompletionFuture()

    • getSubType

      public OperationSubType getSubType()
      Gets the operation sub-type (e.g. RUN_IN_CHILD_CONTEXT, WAIT_FOR_CALLBACK).

    • getOperationId

      public String getOperationId()
      Gets the unique identifier for this operation.

    • getName

      public String getName()
      Gets the operation name (may be null).

    • getContext

      protected DurableContextImpl getContext()
      Gets the parent context.

    • getType

      public software.amazon.awssdk.services.lambda.model.OperationType getType()
      Gets the operation type.

    • execute

      public void execute()
      Starts the operation by checking for an existing checkpoint. If a checkpoint exists, validates and replays it; otherwise starts fresh execution.

    • start

      protected abstract void start()
      Starts the operation on first execution (no existing checkpoint).

    • replay

      protected abstract void replay(software.amazon.awssdk.services.lambda.model.Operation existing)
      Replays the operation from an existing checkpoint.
      Parameters:
      existing - the checkpointed operation state

    • getOperation

      protected software.amazon.awssdk.services.lambda.model.Operation getOperation()
      Gets the Operation from ExecutionManager and update the replay state from REPLAY to EXECUTE if operation is not found. Operation IDs are globally unique (prefixed for child contexts), so no parentId is needed for lookups.
      Returns:
      the operation if found, otherwise null

    • getChildOperations

      protected List<software.amazon.awssdk.services.lambda.model.Operation> getChildOperations()
      Gets the direct child Operations of this context operation
      Returns:
      list of the child Operations

    • isOperationCompleted

      protected boolean isOperationCompleted()
      Returns true if this operation has completed (successfully or exceptionally).

    • waitForOperationCompletion

      protected software.amazon.awssdk.services.lambda.model.Operation waitForOperationCompletion()
      Waits for the operation to complete. Deregisters the current thread to allow Lambda suspension if the operation is still in progress, then re-registers when the operation completes.
      Returns:
      the completed operation

    • runUserHandler

      protected void runUserHandler(Runnable runnable, ThreadType threadType)
      Runs an operation's handler on a user-executor thread, managing thread registration and suspension.

      This method is responsible only for thread/executor/suspension scaffolding. Plugin user-function hooks are fired by runUserFunction(Integer, java.util.function.Supplier), which operations wrap around the actual user function so a user failure is reported through the hook boundary.

      Parameters:
      runnable - the operation handler to run (typically wraps a runUserFunction(java.lang.Integer, java.util.function.Supplier<T>) call)
      threadType - the thread type (STEP or CONTEXT)

    • runUserFunction

      protected <T> T runUserFunction(Integer attempt, Supplier<T> userFunction)
      Runs a user-provided function inside the plugin user-function hook boundary.

      Fires onUserFunctionStart before invoking the function and onUserFunctionEnd after. The function's exception propagates through this boundary so the end hook reports the true outcome, mirroring the JS/Python SDKs. Retry and checkpoint handling stays in the caller's surrounding try/catch, outside this boundary.

      onUserFunctionEnd fires for failures and suspensions alike so plugins (e.g. OTel) can end/clean up the attempt rather than leak state; the original throwable is always re-thrown to the caller.

      Type Parameters:
      T - the user function's result type
      Parameters:
      attempt - the 1-based attempt number for steps/waitForCondition, or null for context operations
      userFunction - the user function to invoke
      Returns:
      the user function's result

    • onCheckpointComplete

      public void onCheckpointComplete(software.amazon.awssdk.services.lambda.model.Operation operation)
      Receives operation updates from ExecutionManager. Completes the internal future when the operation reaches a terminal status, unblocking any threads waiting on this operation.
      Parameters:
      operation - the updated operation state

    • markAlreadyCompleted

      protected void markAlreadyCompleted()
      Marks the operation as already completed (in replay).

    • terminateExecution

      protected RuntimeException terminateExecution(UnrecoverableDurableExecutionException exception)
      Terminates the execution with the given exception.
      Parameters:
      exception - the unrecoverable exception
      Returns:
      never returns normally; always throws

    • terminateExecutionWithIllegalDurableOperationException

      protected RuntimeException terminateExecutionWithIllegalDurableOperationException(String message)
      Terminates the execution with an IllegalDurableOperationException.
      Parameters:
      message - the error message
      Returns:
      never returns normally; always throws

    • registerActiveThread

      protected void registerActiveThread(String threadId)
      Registers a thread as active in the execution manager.
      Parameters:
      threadId - the thread identifier to register

    • deregisterActiveThread

      protected void deregisterActiveThread(String threadId)

    • getCurrentThreadContext

      protected ThreadContext getCurrentThreadContext()
      Returns the current thread's context from the execution manager.

    • pollForOperationUpdates

      protected CompletableFuture<software.amazon.awssdk.services.lambda.model.Operation> pollForOperationUpdates()
      Polls the backend for updates to this operation.

    • pollForOperationUpdates

      protected CompletableFuture<software.amazon.awssdk.services.lambda.model.Operation> pollForOperationUpdates(Instant at)
      Polls the backend for updates to this operation at a specific time.
      Parameters:
      at - the time to poll for updates
      Returns:
      a future that completes with the updated operation

    • sendOperationUpdate

      protected void sendOperationUpdate(software.amazon.awssdk.services.lambda.model.OperationUpdate.Builder builder)
      Sends an operation update synchronously (blocks until the update is acknowledged).

    • sendOperationUpdateAsync

      protected CompletableFuture<Void> sendOperationUpdateAsync(software.amazon.awssdk.services.lambda.model.OperationUpdate.Builder builder)
      Sends an operation update asynchronously.

    • validateReplay

      protected void validateReplay(software.amazon.awssdk.services.lambda.model.Operation checkpointed)
      Validates that current operation matches checkpointed operation during replay.

    • getRunningUserHandler

      public CompletableFuture<Void> getRunningUserHandler()

    • fireOnOperationEnd

      protected void fireOnOperationEnd(software.amazon.awssdk.services.lambda.model.Operation operation, Throwable error, boolean isReplay)
      Fires onOperationEnd plugin hook when an operation reaches terminal status.

    • extractErrorFromOperation

      public static Throwable extractErrorFromOperation(software.amazon.awssdk.services.lambda.model.Operation operation)
      Extracts the error from a terminal operation as a Throwable. Returns null if the operation succeeded or has no error details.

    • getErrorObject

      public static software.amazon.awssdk.services.lambda.model.ErrorObject getErrorObject(software.amazon.awssdk.services.lambda.model.Operation operation)
      Extracts the ErrorObject from an operation based on its type.