Package software.amazon.lambda.durable

Interface DurableContext

All Superinterfaces:
BaseContext
All Known Implementing Classes:
DurableContextImpl
public interface DurableContext extends BaseContext

  • Method Details

    • getCurrentContext

      static DurableContext getCurrentContext()
      Description copied from interface: BaseContext
      Gets the current context (DurableContext or StepContext) for this thread.
      Returns:
      the current context or null if not set

    • isReplaying

      boolean isReplaying()
      Returns whether this context is currently replaying checkpointed durable operations.

    • step

      default <T> T step(String name, Class<T> resultType, Function<StepContext,T> func)
      Executes a durable step with the given name and blocks until it completes.

      On first execution, runs func and checkpoints the result. On replay, returns the cached result without re-executing.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a StepContext
      Returns:
      the step result

    • step

      default <T> T step(String name, Class<T> resultType, Function<StepContext,T> func, StepConfig config)
      Executes a durable step with the given name and configuration, blocking until it completes.
      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a StepContext
      config - the step configuration (retry strategy, semantics, custom SerDes)
      Returns:
      the step result

    • step

      default <T> T step(String name, TypeToken<T> resultType, Function<StepContext,T> func)
      Executes a durable step using a TypeToken for generic result types, blocking until it completes.
      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic types
      func - the function to execute, receiving a StepContext
      Returns:
      the step result

    • step

      default <T> T step(String name, TypeToken<T> resultType, Function<StepContext,T> func, StepConfig config)
      Executes a durable step using a TypeToken and configuration, blocking until it completes.
      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic types
      func - the function to execute, receiving a StepContext
      config - the step configuration (retry strategy, semantics, custom SerDes)
      Returns:
      the step result

    • stepAsync

      default <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext,T> func)
      Asynchronously executes a durable step, returning a DurableFuture that can be composed or blocked on.
      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a StepContext
      Returns:
      a future representing the step result

    • stepAsync

      default <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext,T> func, StepConfig config)
      Asynchronously executes a durable step using custom configuration.

      This is the core stepAsync implementation. All other step/stepAsync overloads delegate here.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      func - the function to execute, receiving a StepContext
      config - the step configuration (retry strategy, semantics, custom SerDes)
      Returns:
      a future representing the step result

    • stepAsync

      default <T> DurableFuture<T> stepAsync(String name, TypeToken<T> resultType, Function<StepContext,T> func)
      Asynchronously executes a durable step using a TypeToken for generic result types.

      This is the core stepAsync implementation. All other step/stepAsync overloads delegate here.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic types
      func - the function to execute, receiving a StepContext
      Returns:
      a future representing the step result

    • stepAsync

      <T> DurableFuture<T> stepAsync(String name, TypeToken<T> resultType, Function<StepContext,T> func, StepConfig config)
      Asynchronously executes a durable step using a TypeToken and custom configuration.

      This is the core stepAsync implementation. All other step/stepAsync overloads delegate here.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic types
      func - the function to execute, receiving a StepContext
      config - the step configuration (retry strategy, semantics, custom SerDes)
      Returns:
      a future representing the step result

    • step

      @Deprecated default <T> T step(String name, Class<T> resultType, Supplier<T> func)
      Deprecated.
      use the variants accepting StepContext instead

    • step

      @Deprecated default <T> T step(String name, Class<T> resultType, Supplier<T> func, StepConfig config)
      Deprecated.
      use the variants accepting StepContext instead

    • step

      @Deprecated default <T> T step(String name, TypeToken<T> resultType, Supplier<T> func)
      Deprecated.
      use the variants accepting StepContext instead

    • step

      @Deprecated default <T> T step(String name, TypeToken<T> resultType, Supplier<T> func, StepConfig config)
      Deprecated.
      use the variants accepting StepContext instead

    • stepAsync

      @Deprecated default <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Supplier<T> func)
      Deprecated.
      use the variants accepting StepContext instead

    • stepAsync

      @Deprecated default <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Supplier<T> func, StepConfig config)
      Deprecated.
      use the variants accepting StepContext instead

    • stepAsync

      @Deprecated default <T> DurableFuture<T> stepAsync(String name, TypeToken<T> resultType, Supplier<T> func)
      Deprecated.
      use the variants accepting StepContext instead

    • stepAsync

      @Deprecated default <T> DurableFuture<T> stepAsync(String name, TypeToken<T> resultType, Supplier<T> func, StepConfig config)
      Deprecated.
      use the variants accepting StepContext instead

    • wait

      default Void wait(String name, Duration duration)
      Suspends execution for the specified duration without consuming compute resources.

      On first execution, checkpoints a wait operation and suspends the Lambda. On replay after the duration has elapsed, returns immediately.

      Parameters:
      name - the unique operation name within this context
      duration - the duration to wait
      Returns:
      always null

    • waitAsync

      DurableFuture<Void> waitAsync(String name, Duration duration)
      Asynchronously suspends execution for the specified duration.
      Parameters:
      name - the unique operation name within this context
      duration - the duration to wait
      Returns:
      a future that completes when the wait duration has elapsed

    • invoke

      default <T, U> T invoke(String name, String functionName, U payload, Class<T> resultType)
      Invokes another Lambda function by name and blocks until the result is available.

      On first execution, checkpoints a chained invoke operation that triggers the target function. On replay, returns the cached result without re-invoking.

      Type Parameters:
      T - the result type
      U - the payload type
      Parameters:
      name - the unique operation name within this context
      functionName - the ARN or name of the Lambda function to invoke
      payload - the input payload to send to the target function
      resultType - the result class for deserialization
      Returns:
      the invocation result

    • invoke

      default <T, U> T invoke(String name, String functionName, U payload, Class<T> resultType, InvokeConfig config)
      Invokes another Lambda function with custom configuration, blocking until the result is available.

    • invoke

      default <T, U> T invoke(String name, String functionName, U payload, TypeToken<T> resultType)
      Invokes another Lambda function using a TypeToken for generic result types, blocking until complete.

    • invoke

      default <T, U> T invoke(String name, String functionName, U payload, TypeToken<T> resultType, InvokeConfig config)
      Invokes another Lambda function using a TypeToken and custom configuration, blocking until complete.

    • invokeAsync

      default <T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, Class<T> resultType, InvokeConfig config)
      Invokes another Lambda function using a TypeToken and custom configuration, blocking until complete.

    • invokeAsync

      default <T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, Class<T> resultType)
      Asynchronously invokes another Lambda function, returning a DurableFuture.

    • invokeAsync

      default <T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, TypeToken<T> resultType)
      Asynchronously invokes another Lambda function using a TypeToken for generic result types.

    • invokeAsync

      <T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, TypeToken<T> resultType, InvokeConfig config)
      Asynchronously invokes another Lambda function using a TypeToken and custom configuration.

      This is the core invokeAsync implementation. All other invoke/invokeAsync overloads delegate here.

      Type Parameters:
      T - the result type
      U - the payload type
      Parameters:
      name - the unique operation name within this context
      functionName - the ARN or name of the Lambda function to invoke
      payload - the input payload to send to the target function
      resultType - the type token for deserialization of generic result types
      config - the invoke configuration (custom SerDes for result and payload)
      Returns:
      a future representing the invocation result

    • createCallback

      default <T> DurableCallbackFuture<T> createCallback(String name, Class<T> resultType, CallbackConfig config)
      Creates a callback with custom configuration.

    • createCallback

      default <T> DurableCallbackFuture<T> createCallback(String name, TypeToken<T> resultType)
      Creates a callback using a TypeToken for generic result types.

    • createCallback

      default <T> DurableCallbackFuture<T> createCallback(String name, Class<T> resultType)
      Creates a callback with default configuration.

    • createCallback

      <T> DurableCallbackFuture<T> createCallback(String name, TypeToken<T> resultType, CallbackConfig config)
      Creates a callback operation that suspends execution until an external system completes it.

      This is the core createCallback implementation. Returns a DurableCallbackFuture containing a callback ID that external systems use to report completion via the Lambda Durable API.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic result types
      config - the callback configuration (custom SerDes)
      Returns:
      a future containing the callback ID and eventual result

    • runInChildContext

      default <T> T runInChildContext(String name, Class<T> resultType, Function<DurableContext,T> func)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      Returns:
      the child context result

    • runInChildContext

      default <T> T runInChildContext(String name, TypeToken<T> resultType, Function<DurableContext,T> func)
      Runs a function in a child context using a TypeToken for generic result types, blocking until complete.

    • runInChildContextAsync

      default <T> DurableFuture<T> runInChildContextAsync(String name, Class<T> resultType, Function<DurableContext,T> func)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Parameters:
      name - the operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      Returns:
      the DurableFuture of the child context result

    • runInChildContextAsync

      default <T> DurableFuture<T> runInChildContextAsync(String name, TypeToken<T> resultType, Function<DurableContext,T> func)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Parameters:
      name - the operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      Returns:
      the DurableFuture of the child context result

    • runInChildContext

      default <T> T runInChildContext(String name, Class<T> resultType, Function<DurableContext,T> func, RunInChildContextConfig config)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      Returns:
      the child context result

    • runInChildContext

      default <T> T runInChildContext(String name, TypeToken<T> resultType, Function<DurableContext,T> func, RunInChildContextConfig config)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Parameters:
      name - the operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      config - the configuration for the child context
      Returns:
      the child context result

    • runInChildContextAsync

      default <T> DurableFuture<T> runInChildContextAsync(String name, Class<T> resultType, Function<DurableContext,T> func, RunInChildContextConfig config)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Parameters:
      name - the operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      config - the configuration for the child context
      Returns:
      the DurableFuture wrapping the child context result

    • runInChildContextAsync

      <T> DurableFuture<T> runInChildContextAsync(String name, TypeToken<T> resultType, Function<DurableContext,T> func, RunInChildContextConfig config)
      Runs a function in a child context, blocking until it completes.

      Child contexts provide isolated operation ID namespaces, allowing nested workflows to be composed without ID collisions. On replay, the child context's operations are replayed independently.

      Parameters:
      name - the operation name within this context
      resultType - the result class for deserialization
      func - the function to execute, receiving a child DurableContext
      config - the configuration for the child context
      Returns:
      the DurableFuture wrapping the child context result

    • map

      default <I, O> MapResult<O> map(String name, Collection<I> items, Class<O> resultType, DurableContext.MapFunction<I,O> function)

    • map

      default <I, O> MapResult<O> map(String name, Collection<I> items, Class<O> resultType, DurableContext.MapFunction<I,O> function, MapConfig config)

    • map

      default <I, O> MapResult<O> map(String name, Collection<I> items, TypeToken<O> resultType, DurableContext.MapFunction<I,O> function)

    • map

      default <I, O> MapResult<O> map(String name, Collection<I> items, TypeToken<O> resultType, DurableContext.MapFunction<I,O> function, MapConfig config)

    • mapAsync

      default <I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items, Class<O> resultType, DurableContext.MapFunction<I,O> function)

    • mapAsync

      default <I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items, Class<O> resultType, DurableContext.MapFunction<I,O> function, MapConfig config)

    • mapAsync

      default <I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items, TypeToken<O> resultType, DurableContext.MapFunction<I,O> function)

    • mapAsync

      <I, O> DurableFuture<MapResult<O>> mapAsync(String name, Collection<I> items, TypeToken<O> resultType, DurableContext.MapFunction<I,O> function, MapConfig config)

    • parallel

      default ParallelDurableFuture parallel(String name)
      Creates a ParallelDurableFuture for executing multiple branches concurrently with default config
      Returns:
      a new ParallelDurableFuture for registering and executing branches

    • parallel

      ParallelDurableFuture parallel(String name, ParallelConfig config)
      Creates a ParallelDurableFuture for executing multiple branches concurrently.
      Parameters:
      config - the parallel execution configuration
      Returns:
      a new ParallelDurableFuture for registering and executing branches

    • waitForCallback

      default <T> T waitForCallback(String name, Class<T> resultType, BiConsumer<String,StepContext> func)
      Executes a submitter function and waits for an external callback, blocking until the callback completes.

      Combines a step (to run the submitter) and a callback (to receive the external result) in a child context. The submitter receives a callback ID that external systems use to report completion.

      If a failed child is replayed without its nested operation details and its original exception cannot be reconstructed, ChildContextFailedException carries the stored context failure. The SDK does not guess whether the missing callback or submitter caused it, and does not rerun the completed child.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      func - the submitter function, receiving the callback ID and a StepContext
      Returns:
      the callback result

    • waitForCallback

      default <T> T waitForCallback(String name, TypeToken<T> resultType, BiConsumer<String,StepContext> func)
      Executes a submitter and waits for an external callback using a TypeToken, blocking until complete.

    • waitForCallback

      default <T> T waitForCallback(String name, Class<T> resultType, BiConsumer<String,StepContext> func, WaitForCallbackConfig waitForCallbackConfig)
      Executes a submitter and waits for an external callback with custom configuration, blocking until complete.

    • waitForCallback

      default <T> T waitForCallback(String name, TypeToken<T> resultType, BiConsumer<String,StepContext> func, WaitForCallbackConfig waitForCallbackConfig)
      Executes a submitter and waits for an external callback using a TypeToken and custom configuration.

    • waitForCallbackAsync

      default <T> DurableFuture<T> waitForCallbackAsync(String name, Class<T> resultType, BiConsumer<String,StepContext> func)
      Asynchronously executes a submitter and waits for an external callback.

    • waitForCallbackAsync

      default <T> DurableFuture<T> waitForCallbackAsync(String name, TypeToken<T> resultType, BiConsumer<String,StepContext> func)
      Asynchronously executes a submitter and waits for an external callback using a TypeToken.

    • waitForCallbackAsync

      default <T> DurableFuture<T> waitForCallbackAsync(String name, Class<T> resultType, BiConsumer<String,StepContext> func, WaitForCallbackConfig waitForCallbackConfig)
      Asynchronously executes a submitter and waits for an external callback with custom configuration.

    • waitForCallbackAsync

      <T> DurableFuture<T> waitForCallbackAsync(String name, TypeToken<T> resultType, BiConsumer<String,StepContext> func, WaitForCallbackConfig waitForCallbackConfig)
      Asynchronously executes a submitter and waits for an external callback using a TypeToken and custom configuration.

      This is the core waitForCallbackAsync implementation. All other waitForCallback/waitForCallbackAsync overloads delegate here. Internally creates a child context containing a callback operation and a step that runs the submitter function.

      Retrieving a failed replay's result can report ChildContextFailedException when nested operation details are no longer available and the original exception cannot be reconstructed.

      Type Parameters:
      T - the result type
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic result types
      func - the submitter function, receiving the callback ID and a StepContext
      waitForCallbackConfig - the configuration for both the callback and submitter step
      Returns:
      a future representing the callback result

    • waitForCondition

      default <T> T waitForCondition(String name, Class<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc)
      Polls a condition function until it signals done, blocking until complete.
      Type Parameters:
      T - the type of state being polled
      Parameters:
      name - the unique operation name within this context
      resultType - the result class for deserialization
      checkFunc - the function that evaluates the condition and returns a WaitForConditionResult
      Returns:
      the final state value when the condition is met

    • waitForCondition

      default <T> T waitForCondition(String name, Class<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc, WaitForConditionConfig<T> config)
      Polls a condition function until it signals done, using a custom configuration, blocking until complete.

    • waitForCondition

      default <T> T waitForCondition(String name, TypeToken<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc)
      Polls a condition function until it signals done, using a TypeToken, blocking until complete.

    • waitForCondition

      default <T> T waitForCondition(String name, TypeToken<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc, WaitForConditionConfig<T> config)
      Polls a condition function until it signals done, using a TypeToken and custom configuration, blocking until complete.

    • waitForConditionAsync

      default <T> DurableFuture<T> waitForConditionAsync(String name, Class<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc)
      Asynchronously polls a condition function until it signals done.

    • waitForConditionAsync

      default <T> DurableFuture<T> waitForConditionAsync(String name, Class<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc, WaitForConditionConfig<T> config)
      Asynchronously polls a condition function until it signals done, using custom configuration.

    • waitForConditionAsync

      default <T> DurableFuture<T> waitForConditionAsync(String name, TypeToken<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc)
      Asynchronously polls a condition function until it signals done, using a TypeToken.

    • waitForConditionAsync

      <T> DurableFuture<T> waitForConditionAsync(String name, TypeToken<T> resultType, BiFunction<T,StepContext,WaitForConditionResult<T>> checkFunc, WaitForConditionConfig<T> config)
      Asynchronously polls a condition function until it signals done, using a TypeToken and custom configuration.

      This is the core waitForConditionAsync implementation. All other waitForCondition/waitForConditionAsync overloads delegate here.

      Type Parameters:
      T - the type of state being polled
      Parameters:
      name - the unique operation name within this context
      resultType - the type token for deserialization of generic types
      checkFunc - the function that evaluates the condition and returns a WaitForConditionResult
      config - the waitForCondition configuration (wait strategy, custom SerDes)
      Returns:
      a future representing the final state value

    • withRetry

      default <T> T withRetry(String name, BiFunction<Integer,DurableContext,T> operation)
      Replay-safe retry loop for any durable operation (sync) with default configuration.

      Uses WithRetryConfig defaults: RetryStrategies.Presets.DEFAULT retry strategy and no child context wrapping.

      Type Parameters:
      T - the result type
      Parameters:
      name - operation name (used for backoff wait names, and as the child context name when wrapping); pass null for an anonymous retry whose backoff waits use default names
      operation - the retryable operation — receives the 1-based attempt number and the durable context
      Returns:
      the operation result
      See Also:

    • withRetry

      default <T> T withRetry(String name, BiFunction<Integer,DurableContext,T> operation, WithRetryConfig config)
      Replay-safe retry loop for any durable operation (sync).

      Provides the same retry-with-backoff pattern that step() has built in, but for operations that cannot live inside a step (waitForCallback, invoke, waitForCondition, etc.).

      Every side-effect in the loop is a durable operation, so the loop is replay-safe by construction. On replay, completed operations return cached results instantly and the loop fast-forwards to the current attempt.

      The retry loop always runs in a child context to provide an isolated operation ID namespace. If WithRetryConfig.wrapInChildContext() is enabled, the child context is checkpointed (persisted) so all attempts are grouped under a single named operation in execution history. Otherwise, a virtual child context is used — no checkpointing overhead, but the child re-executes on replay.

      Type Parameters:
      T - the result type
      Parameters:
      name - operation name (used for backoff wait names, and as the child context name when wrapping); pass null for an anonymous retry whose backoff waits use default names
      operation - the retryable operation — receives the 1-based attempt number and the durable context
      config - retry configuration including the retry strategy and child context wrapping
      Returns:
      the operation result

    • withRetryAsync

      default <T> DurableFuture<T> withRetryAsync(String name, BiFunction<Integer,DurableContext,T> operation)
      Replay-safe retry loop for any durable operation (async) with default configuration.

      Uses WithRetryConfig defaults: RetryStrategies.Presets.DEFAULT retry strategy and no child context wrapping.

      Type Parameters:
      T - the result type
      Parameters:
      name - operation name (used for child context and backoff wait names); pass null for an anonymous retry whose backoff waits use default names
      operation - the retryable operation — receives the 1-based attempt number and the durable context
      Returns:
      a future representing the operation result
      See Also:

    • withRetryAsync

      <T> DurableFuture<T> withRetryAsync(String name, BiFunction<Integer,DurableContext,T> operation, WithRetryConfig config)
      Replay-safe retry loop for any durable operation (async).

      The retry loop always runs in a child context to provide an isolated operation ID namespace. If WithRetryConfig.wrapInChildContext() is enabled, the child context is checkpointed (persisted) so all attempts are grouped under a single named operation in execution history. Otherwise, a virtual child context is used — no checkpointing overhead, but the child re-executes on replay.

      Type Parameters:
      T - the result type
      Parameters:
      name - operation name (used for child context and backoff wait names); pass null for an anonymous retry whose backoff waits use default names
      operation - the retryable operation — receives the 1-based attempt number and the durable context
      config - retry configuration including the retry strategy
      Returns:
      a future representing the operation result