Package io.dapr.workflows

# Interface WorkflowContext

All Known Implementing Classes:
  `DefaultWorkflowContext`

public interface WorkflowContext
Context object used by workflow implementations to perform actions such as scheduling activities, durable timers, waiting for external events, and for getting basic information about the current workflow instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<V> Task<List<V>>`
  `allOf(List<Task<V>> tasks)`
  Returns a new `Task` that is completed when all the given `Task`s complete.
  `default Task<Task<?>>`
  `anyOf(Task<?>... tasks)`
  Returns a new `Task` that is completed when any of the given `Task`s complete.
  `Task<Task<?>>`
  `anyOf(List<Task<?>> tasks)`
  Returns a new `Task` that is completed when any of the tasks in `tasks` completes.
  `default Task<Void>`
  `callActivity(String name)`
  Asynchronously invokes an activity by name and returns a new `Task` that completes when the activity completes.
  `default <V> Task<V>`
  `callActivity(String name, Class<V> returnType)`
  Asynchronously invokes an activity by name and returns a new `Task` that completes when the activity completes.
  `default Task<Void>`
  `callActivity(String name, Object input)`
  Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes.
  `default Task<Void>`
  `callActivity(String name, Object input, WorkflowTaskOptions options)`
  Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes.
  `<V> Task<V>`
  `callActivity(String name, Object input, WorkflowTaskOptions options, Class<V> returnType)`
  Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes.
  `default <V> Task<V>`
  `callActivity(String name, Object input, Class<V> returnType)`
  Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes.If the activity completes successfully, the returned `Task`'s value will be the activity's output.
  `default Task<Void>`
  `callChildWorkflow(String name)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `default Task<Void>`
  `callChildWorkflow(String name, Object input)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `default <V> Task<V>`
  `callChildWorkflow(String name, Object input, Class<V> returnType)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `default Task<Void>`
  `callChildWorkflow(String name, Object input, String instanceID, WorkflowTaskOptions options)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `<V> Task<V>`
  `callChildWorkflow(String name, Object input, String instanceID, WorkflowTaskOptions options, Class<V> returnType)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `default <V> Task<V>`
  `callChildWorkflow(String name, Object input, String instanceID, Class<V> returnType)`
  Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.
  `void`
  `complete(Object output)`
  Completes the current workflow.
  `default void`
  `continueAsNew(Object input)`
  Restarts the orchestration with a new input and clears its history.
  `void`
  `continueAsNew(Object input, boolean preserveUnprocessedEvents)`
  Restarts the orchestration with a new input and clears its history.
  `Task<Void>`
  `createTimer(Duration duration)`
  Creates a durable timer that expires after the specified delay.
  `Task<Void>`
  `createTimer(ZonedDateTime zonedDateTime)`
  Creates a durable timer that expires after the specified timestamp with specific zone.
  `Instant`
  `getCurrentInstant()`
  Gets the current orchestration time in UTC.
  `<V> V`
  `getInput(Class<V> targetType)`
  Gets the deserialized input of the current task orchestration.
  `String`
  `getInstanceId()`
  Gets the instance ID of the current workflow.
  `org.slf4j.Logger`
  `getLogger()`
  Get a logger only when `isReplaying` is false.
  `String`
  `getName()`
  Gets the name of the current workflow.
  `Optional<PropagatedHistory>`
  `getPropagatedHistory()`
  Gets the propagated history from a parent workflow, if any was propagated.
  `boolean`
  `isPatched(String patchName)`
  Checks if the patch has been applied.
  `boolean`
  `isReplaying()`
  Gets a value indicating whether the workflow is currently replaying a previous execution.
  `default UUID`
  `newUuid()`
  Create a new UUID that is safe for replay within a workflow.
  `void`
  `setCustomStatus(Object status)`
  Set a custom status to a workflow execution.
  `<V> Task<Void>`
  `waitForExternalEvent(String name)`
  Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received.
  `default <V> Task<V>`
  `waitForExternalEvent(String name, Class<V> dataType)`
  Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received.
  `<V> Task<Void>`
  `waitForExternalEvent(String name, Duration timeout)`
  Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received or is canceled when `timeout` expires.
  `<V> Task<V>`
  `waitForExternalEvent(String name, Duration timeout, Class<V> dataType)`
  Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received or is canceled when `timeout` expires.

- ## Method Details

  - ### getLogger

    org.slf4j.Logger getLogger()
    Get a logger only when `isReplaying` is false. Otherwise, return a NOP (no operation) logger.
    Returns:
      Logger

  - ### getName

    String getName()
    Gets the name of the current workflow.
    Returns:
      the name of the current workflow

  - ### getInstanceId

    String getInstanceId()
    Gets the instance ID of the current workflow.
    Returns:
      the instance ID of the current workflow

  - ### getCurrentInstant

    Instant getCurrentInstant()
    Gets the current orchestration time in UTC.
    Returns:
      the current orchestration time in UTC

  - ### complete

    void complete(Object output)
    Completes the current workflow.
    Parameters:
      `output` - the serializable output of the completed Workflow.

  - ### waitForExternalEvent

    <V> Task<V> waitForExternalEvent(String name, Duration timeout, Class<V> dataType) throws TaskCanceledException
    Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received or is canceled when `timeout` expires.

    If the current orchestration is not yet waiting for an event named `name`, then the event will be saved in the orchestration instance state and dispatched immediately when this method is called. This event saving occurs even if the current orchestrator cancels the wait operation before the event is received.

    Orchestrators can wait for the same event name multiple times, so waiting for multiple events with the same name is allowed. Each external event received by an orchestrator will complete just one task returned by this method.

    Type Parameters:
      `V` - the expected type of the event data payload
    Parameters:
      `name` - the case-insensitive name of the event to wait for
      `timeout` - the amount of time to wait before canceling the returned `Task`
      `dataType` - the expected class type of the event data payload
    Returns:
      a new `Task` that completes when the external event is received or when `timeout` expires
    Throws:
      `TaskCanceledException` - if the specified `timeout` value expires before the event is received

  - ### waitForExternalEvent

    <V> Task<Void> waitForExternalEvent(String name, Duration timeout) throws TaskCanceledException
    Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received or is canceled when `timeout` expires.

    See `waitForExternalEvent(String, Duration, Class)` for a full description.

    Type Parameters:
      `V` - the expected type of the event data payload
    Parameters:
      `name` - the case-insensitive name of the event to wait for
      `timeout` - the amount of time to wait before canceling the returned `Task`
    Returns:
      a new `Task` that completes when the external event is received or when `timeout` expires
    Throws:
      `TaskCanceledException` - if the specified `timeout` value expires before the event is received

  - ### waitForExternalEvent

    <V> Task<Void> waitForExternalEvent(String name) throws TaskCanceledException
    Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received.

    See `waitForExternalEvent(String, Duration, Class)` for a full description.

    Type Parameters:
      `V` - the expected type of the event data payload
    Parameters:
      `name` - the case-insensitive name of the event to wait for
    Returns:
      a new `Task` that completes when the external event is received
    Throws:
      `TaskCanceledException`

  - ### waitForExternalEvent

    default <V> Task<V> waitForExternalEvent(String name, Class<V> dataType)
    Waits for an event to be raised named `name` and returns a `Task` that completes when the event is received.

    See `waitForExternalEvent(String, Duration, Class)` for a full description.

    Type Parameters:
      `V` - the expected type of the event data payload
    Parameters:
      `name` - the case-insensitive name of the event to wait for
      `dataType` - the expected class type of the event data payload
    Returns:
      a new `Task` that completes when the external event is received

  - ### callActivity

    <V> Task<V> callActivity(String name, Object input, WorkflowTaskOptions options, Class<V> returnType)
    Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes. If the activity completes successfully, the returned `Task`'s value will be the activity's output. If the activity fails, the returned `Task` will complete exceptionally with a `TaskFailedException`.
    Type Parameters:
      `V` - the expected type of the activity output
    Parameters:
      `name` - the name of the activity to call
      `input` - the serializable input to pass to the activity
      `options` - additional options that control the execution and processing of the activity
      `returnType` - the expected class type of the activity output
    Returns:
      a new `Task` that completes when the activity completes or fails

  - ### callActivity

    default Task<Void> callActivity(String name)
    Asynchronously invokes an activity by name and returns a new `Task` that completes when the activity completes. See `callActivity(String, Object, WorkflowTaskOptions, Class)` for a complete description.
    Parameters:
      `name` - the name of the activity to call
    Returns:
      a new `Task` that completes when the activity completes or fails
    See Also:
      - `callActivity(String, Object, WorkflowTaskOptions, Class)`

  - ### callActivity

    default Task<Void> callActivity(String name, Object input)
    Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes. See `callActivity(String, Object, WorkflowTaskOptions, Class)` for a complete description.
    Parameters:
      `name` - the name of the activity to call
      `input` - the serializable input to pass to the activity
    Returns:
      a new `Task` that completes when the activity completes or fails

  - ### callActivity

    default <V> Task<V> callActivity(String name, Class<V> returnType)
    Asynchronously invokes an activity by name and returns a new `Task` that completes when the activity completes. If the activity completes successfully, the returned `Task`'s value will be the activity's output. See `callActivity(String, Object, WorkflowTaskOptions, Class)` for a complete description.
    Type Parameters:
      `V` - the expected type of the activity output
    Parameters:
      `name` - the name of the activity to call
      `returnType` - the expected class type of the activity output
    Returns:
      a new `Task` that completes when the activity completes or fails

  - ### callActivity

    default <V> Task<V> callActivity(String name, Object input, Class<V> returnType)
    Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes.If the activity completes successfully, the returned `Task`'s value will be the activity's output. See `callActivity(String, Object, WorkflowTaskOptions, Class)` for a complete description.
    Type Parameters:
      `V` - the expected type of the activity output
    Parameters:
      `name` - the name of the activity to call
      `input` - the serializable input to pass to the activity
      `returnType` - the expected class type of the activity output
    Returns:
      a new `Task` that completes when the activity completes or fails

  - ### callActivity

    default Task<Void> callActivity(String name, Object input, WorkflowTaskOptions options)
    Asynchronously invokes an activity by name and with the specified input value and returns a new `Task` that completes when the activity completes. See `callActivity(String, Object, WorkflowTaskOptions, Class)` for a complete description.
    Parameters:
      `name` - the name of the activity to call
      `input` - the serializable input to pass to the activity
      `options` - additional options that control the execution and processing of the activity
    Returns:
      a new `Task` that completes when the activity completes or fails

  - ### isReplaying

    boolean isReplaying()
    Gets a value indicating whether the workflow is currently replaying a previous execution.

    Workflow functions are "replayed" after being unloaded from memory to reconstruct local variable state. During a replay, previously executed tasks will be completed automatically with previously seen values that are stored in the workflow history. Once the workflow reaches the point where it's no longer replaying existing history, this method will return `false`.

    You can use this method if you have logic that needs to run only when not replaying. For example, certain types of application logging may become too noisy when duplicated as part of replay. The application code could check to see whether the function is being replayed and then issue the log statements when this value is `false`.

    Returns:
      `true` if the workflow is replaying, otherwise `false`

  - ### allOf

    <V> Task<List<V>> allOf(List<Task<V>> tasks) throws CompositeTaskFailedException
    Returns a new `Task` that is completed when all the given `Task`s complete. If any of the given `Task`s complete with an exception, the returned `Task` will also complete with an `CompositeTaskFailedException` containing details of the first encountered failure. The value of the returned `Task` is an ordered list of the return values of the given tasks. If no tasks are provided, returns a `Task` completed with value `null`.

    This method is useful for awaiting the completion of a set of independent tasks before continuing to the next step in the orchestration, as in the following example:

         Task<String> t1 = ctx.callActivity("MyActivity", String.class);
         Task<String> t2 = ctx.callActivity("MyActivity", String.class);
         Task<String> t3 = ctx.callActivity("MyActivity", String.class);

         List<String> orderedResults = ctx.allOf(List.of(t1, t2, t3)).await();

    Exceptions in any of the given tasks results in an unchecked `CompositeTaskFailedException`. This exception can be inspected to obtain failure details of individual `Task`s.

         try {
             List<String> orderedResults = ctx.allOf(List.of(t1, t2, t3)).await();
         } catch (CompositeTaskFailedException e) {
             List<Exception> exceptions = e.getExceptions()
         }

    Type Parameters:
      `V` - the return type of the `Task` objects
    Parameters:
      `tasks` - the list of `Task` objects
    Returns:
      the values of the completed `Task` objects in the same order as the source list
    Throws:
      `CompositeTaskFailedException` - if the specified `timeout` value expires before the event is received

  - ### anyOf

    Task<Task<?>> anyOf(List<Task<?>> tasks)
    Returns a new `Task` that is completed when any of the tasks in `tasks` completes. See `anyOf(Task[])` for more detailed information.
    Parameters:
      `tasks` - the list of `Task` objects
    Returns:
      a new `Task` that is completed when any of the given `Task`s complete
    See Also:
      - `anyOf(Task[])`

  - ### anyOf

    default Task<Task<?>> anyOf(Task<?>... tasks)
    Returns a new `Task` that is completed when any of the given `Task`s complete. The value of the new `Task` is a reference to the completed `Task` object. If no tasks are provided, returns a `Task` that never completes.

    This method is useful for waiting on multiple concurrent tasks and performing a task-specific operation when the first task completes, as in the following example:

         Task<Void> event1 = ctx.waitForExternalEvent("Event1");
         Task<Void> event2 = ctx.waitForExternalEvent("Event2");
         Task<Void> event3 = ctx.waitForExternalEvent("Event3");

         Task<?> winner = ctx.anyOf(event1, event2, event3).await();
         if (winner == event1) {
             // ...
         } else if (winner == event2) {
             // ...
         } else if (winner == event3) {
             // ...
         }

    The `anyOf` method can also be used for implementing long-running timeouts, as in the following example:

         Task<Void> activityTask = ctx.callActivity("SlowActivity");
         Task<Void> timeoutTask = ctx.createTimer(Duration.ofMinutes(30));

         Task<?> winner = ctx.anyOf(activityTask, timeoutTask).await();
         if (winner == activityTask) {
             // completion case
         } else {
             // timeout case
         }

    Parameters:
      `tasks` - the list of `Task` objects
    Returns:
      a new `Task` that is completed when any of the given `Task`s complete

  - ### createTimer

    Task<Void> createTimer(Duration duration)
    Creates a durable timer that expires after the specified delay.

    Specifying a long delay (for example, a delay of a few days or more) may result in the creation of multiple, internally-managed durable timers. The orchestration code doesn't need to be aware of this behavior. However, it may be visible in framework logs and the stored history state.

    Parameters:
      `duration` - the amount of time before the timer should expire
    Returns:
      a new `Task` that completes after the specified delay

  - ### createTimer

    Task<Void> createTimer(ZonedDateTime zonedDateTime)
    Creates a durable timer that expires after the specified timestamp with specific zone.

    Specifying a long delay (for example, a delay of a few days or more) may result in the creation of multiple, internally-managed timers. The workflow code doesn't need to be aware of this behavior. However, it may be visible in framework logs and the stored history state.

    Parameters:
      `zonedDateTime` - timestamp with specific zone when the timer should expire
    Returns:
      a new `Task` that completes after the specified delay

  - ### getInput

    <V> V getInput(Class<V> targetType)
    Gets the deserialized input of the current task orchestration.
    Type Parameters:
      `V` - the expected type of the workflow input
    Parameters:
      `targetType` - the `Class` object associated with `V`
    Returns:
      the deserialized input as an object of type `V` or `null` if no input was provided.

  - ### callChildWorkflow

    default Task<Void> callChildWorkflow(String name)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.

    See `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)` for a full description.

    Parameters:
      `name` - the name of the workflow to invoke
    Returns:
      a new `Task` that completes when the child-workflow completes or fails
    See Also:
      - `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)`

  - ### callChildWorkflow

    default Task<Void> callChildWorkflow(String name, Object input)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.

    See `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)` for a full description.

    Parameters:
      `name` - the name of the workflow to invoke
      `input` - the serializable input to send to the child-workflow
    Returns:
      a new `Task` that completes when the child-workflow completes or fails

  - ### callChildWorkflow

    default <V> Task<V> callChildWorkflow(String name, Object input, Class<V> returnType)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.

    See `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)` for a full description.

    Type Parameters:
      `V` - the expected type of the child-workflow output
    Parameters:
      `name` - the name of the workflow to invoke
      `input` - the serializable input to send to the child-workflow
      `returnType` - the expected class type of the child-workflow output
    Returns:
      a new `Task` that completes when the child-workflow completes or fails

  - ### callChildWorkflow

    default <V> Task<V> callChildWorkflow(String name, Object input, String instanceID, Class<V> returnType)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.

    See `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)` for a full description.

    Type Parameters:
      `V` - the expected type of the child-workflow output
    Parameters:
      `name` - the name of the workflow to invoke
      `input` - the serializable input to send to the child-workflow
      `instanceID` - the unique ID of the child-workflow
      `returnType` - the expected class type of the child-workflow output
    Returns:
      a new `Task` that completes when the child-workflow completes or fails

  - ### callChildWorkflow

    default Task<Void> callChildWorkflow(String name, Object input, String instanceID, WorkflowTaskOptions options)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes.

    See `callChildWorkflow(String, Object, String, WorkflowTaskOptions, Class)` for a full description.

    Parameters:
      `name` - the name of the workflow to invoke
      `input` - the serializable input to send to the child-workflow
      `instanceID` - the unique ID of the child-workflow
      `options` - additional options that control the execution and processing of the activity
    Returns:
      a new `Task` that completes when the child-workflow completes or fails

  - ### callChildWorkflow

    <V> Task<V> callChildWorkflow(String name, @Nullable Object input, @Nullable String instanceID, @Nullable WorkflowTaskOptions options, Class<V> returnType)
    Asynchronously invokes another workflow as a child-workflow and returns a `Task` that completes when the child-workflow completes. If the child-workflow completes successfully, the returned `Task`'s value will be the activity's output. If the child-workflow fails, the returned `Task` will complete exceptionally with a `TaskFailedException`.

    A child-workflow has its own instance ID, history, and status that is independent of the parent workflow that started it. There are many advantages to breaking down large orchestrations into child-workflows:

    - Splitting large orchestrations into a series of smaller child-workflows can make code more maintainable.
    - Distributing orchestration logic across multiple compute nodes concurrently is useful if orchestration logic otherwise needs to coordinate a lot of tasks.
    - Memory usage and CPU overhead can be reduced by keeping the history of parent orchestrations smaller.
    The disadvantage is that there is overhead associated with starting a child-workflow and processing its output. This is typically only an issue for very small orchestrations.

    Because child-workflows are independent of their parents, terminating a parent orchestration does not affect any child-workflows. child-workflows must be terminated independently using their unique instance ID, which is specified using the `instanceID` parameter

    Type Parameters:
      `V` - the expected type of the child-workflow output
    Parameters:
      `name` - the name of the workflow to invoke
      `input` - the serializable input to send to the child-workflow
      `instanceID` - the unique ID of the child-workflow
      `options` - additional options that control the execution and processing of the activity
      `returnType` - the expected class type of the child-workflow output
    Returns:
      a new `Task` that completes when the child-workflow completes or fails

  - ### continueAsNew

    default void continueAsNew(Object input)
    Restarts the orchestration with a new input and clears its history. See `continueAsNew(Object, boolean)` for a full description.
    Parameters:
      `input` - the serializable input data to re-initialize the instance with

  - ### continueAsNew

    void continueAsNew(Object input, boolean preserveUnprocessedEvents)
    Restarts the orchestration with a new input and clears its history.

    This method is primarily designed for eternal orchestrations, which are orchestrations that may not ever complete. It works by restarting the orchestration, providing it with a new input, and truncating the existing orchestration history. It allows an orchestration to continue running indefinitely without having its history grow unbounded. The benefits of periodically truncating history include decreased memory usage, decreased storage volumes, and shorter orchestrator replays when rebuilding state.

    The results of any incomplete tasks will be discarded when an orchestrator calls `continueAsNew`. For example, if a timer is scheduled and then `continueAsNew` is called before the timer fires, the timer event will be discarded. The only exception to this is external events. By default, if an external event is received by an orchestration but not yet processed, the event is saved in the orchestration state unit it is received by a call to `waitForExternalEvent(java.lang.String, java.time.Duration, java.lang.Class<V>)`. These events will remain in memory even after an orchestrator restarts using `continueAsNew`. This behavior can be disabled by specifying `false` for the `preserveUnprocessedEvents` parameter value.

    Orchestrator implementations should complete immediately after calling the`continueAsNew` method.

    Parameters:
      `input` - the serializable input data to re-initialize the instance with
      `preserveUnprocessedEvents` - `true` to push unprocessed external events into the new orchestration history, otherwise `false`

  - ### newUuid

    default UUID newUuid()
    Create a new UUID that is safe for replay within a workflow.

    The default implementation of this method creates a name-based UUID using the algorithm from RFC 4122 §4.3. The name input used to generate this value is a combination of the workflow instance ID and an internally managed sequence number.

    Returns:
      a deterministic UUID

  - ### setCustomStatus

    void setCustomStatus(Object status)
    Set a custom status to a workflow execution.
    Parameters:
      `status` - to be set to the current execution

  - ### isPatched

    boolean isPatched(String patchName)
    Checks if the patch has been applied.
    Parameters:
      `patchName` - the patch name to check
    Returns:
      true if already applied

  - ### getPropagatedHistory

    Optional<PropagatedHistory> getPropagatedHistory()
    Gets the propagated history from a parent workflow, if any was propagated.
    Returns:
      an Optional containing the propagated history, or empty if none was propagated