Package io.dapr.workflows

Interface WorkflowContext

All Known Implementing Classes:
DaprWorkflowContextImpl
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> com.microsoft.durabletask.Task<List<V>>
    allOf(List<com.microsoft.durabletask.Task<V>> tasks)
    Returns a new Task that is completed when all the given Tasks complete.
    default com.microsoft.durabletask.Task<com.microsoft.durabletask.Task<?>>
    anyOf(com.microsoft.durabletask.Task<?>... tasks)
    Returns a new Task that is completed when any of the given Tasks complete.
    com.microsoft.durabletask.Task<com.microsoft.durabletask.Task<?>>
    anyOf(List<com.microsoft.durabletask.Task<?>> tasks)
    Returns a new Task that is completed when any of the tasks in tasks completes.
    default com.microsoft.durabletask.Task<Void>
    callActivity(String name)
    Asynchronously invokes an activity by name and returns a new Task that completes when the activity completes.
    default <V> com.microsoft.durabletask.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 com.microsoft.durabletask.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 com.microsoft.durabletask.Task<Void>
    callActivity(String name, Object input, com.microsoft.durabletask.TaskOptions 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> com.microsoft.durabletask.Task<V>
    callActivity(String name, Object input, com.microsoft.durabletask.TaskOptions 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> com.microsoft.durabletask.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 com.microsoft.durabletask.Task<Void>
    callSubWorkflow(String name)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.
    default com.microsoft.durabletask.Task<Void>
    callSubWorkflow(String name, Object input)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.
    default <V> com.microsoft.durabletask.Task<V>
    callSubWorkflow(String name, Object input, Class<V> returnType)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.
    default com.microsoft.durabletask.Task<Void>
    callSubWorkflow(String name, Object input, String instanceID, com.microsoft.durabletask.TaskOptions options)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.
    <V> com.microsoft.durabletask.Task<V>
    callSubWorkflow(String name, Object input, String instanceID, com.microsoft.durabletask.TaskOptions options, Class<V> returnType)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.
    default <V> com.microsoft.durabletask.Task<V>
    callSubWorkflow(String name, Object input, String instanceID, Class<V> returnType)
    Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-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.
    com.microsoft.durabletask.Task<Void>
    createTimer(Duration duration)
    Creates a durable timer that expires after the specified delay.
    default com.microsoft.durabletask.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.
    SagaContext
    getSagaContext()
    get saga context.
    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.
    <V> com.microsoft.durabletask.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> com.microsoft.durabletask.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> com.microsoft.durabletask.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> com.microsoft.durabletask.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> com.microsoft.durabletask.Task<V> waitForExternalEvent(String name, Duration timeout, Class<V> dataType) throws com.microsoft.durabletask.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:
      com.microsoft.durabletask.TaskCanceledException - if the specified timeout value expires before the event is received

    • waitForExternalEvent

      <V> com.microsoft.durabletask.Task<Void> waitForExternalEvent(String name, Duration timeout) throws com.microsoft.durabletask.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:
      com.microsoft.durabletask.TaskCanceledException - if the specified timeout value expires before the event is received

    • waitForExternalEvent

      <V> com.microsoft.durabletask.Task<Void> waitForExternalEvent(String name) throws com.microsoft.durabletask.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:
      com.microsoft.durabletask.TaskCanceledException

    • waitForExternalEvent

      default <V> com.microsoft.durabletask.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> com.microsoft.durabletask.Task<V> callActivity(String name, Object input, com.microsoft.durabletask.TaskOptions 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 com.microsoft.durabletask.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, TaskOptions, 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

      default com.microsoft.durabletask.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, TaskOptions, 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> com.microsoft.durabletask.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, TaskOptions, 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> com.microsoft.durabletask.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, TaskOptions, 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 com.microsoft.durabletask.Task<Void> callActivity(String name, Object input, com.microsoft.durabletask.TaskOptions 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, TaskOptions, 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> com.microsoft.durabletask.Task<List<V>> allOf(List<com.microsoft.durabletask.Task<V>> tasks) throws com.microsoft.durabletask.CompositeTaskFailedException
      Returns a new Task that is completed when all the given Tasks complete. If any of the given Tasks 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 Tasks. 

      
 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:
      com.microsoft.durabletask.CompositeTaskFailedException - if the specified timeout value expires before the event is received

    • anyOf

      com.microsoft.durabletask.Task<com.microsoft.durabletask.Task<?>> anyOf(List<com.microsoft.durabletask.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 Tasks complete
      See Also:

    • anyOf

      default com.microsoft.durabletask.Task<com.microsoft.durabletask.Task<?>> anyOf(com.microsoft.durabletask.Task<?>... tasks)
      Returns a new Task that is completed when any of the given Tasks 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 Tasks complete

    • createTimer

      com.microsoft.durabletask.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

      default com.microsoft.durabletask.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.

    • callSubWorkflow

      default com.microsoft.durabletask.Task<Void> callSubWorkflow(String name)
      Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.

      See callSubWorkflow(String, Object, String, TaskOptions, Class) for a full description.

      Parameters:
      name - the name of the workflow to invoke
      Returns:
      a new Task that completes when the sub-workflow completes or fails
      See Also:

    • callSubWorkflow

      default com.microsoft.durabletask.Task<Void> callSubWorkflow(String name, Object input)
      Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.

      See callSubWorkflow(String, Object, String, TaskOptions, Class) for a full description.

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

    • callSubWorkflow

      default <V> com.microsoft.durabletask.Task<V> callSubWorkflow(String name, Object input, Class<V> returnType)
      Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.

      See callSubWorkflow(String, Object, String, TaskOptions, Class) for a full description.

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

    • callSubWorkflow

      default <V> com.microsoft.durabletask.Task<V> callSubWorkflow(String name, Object input, String instanceID, Class<V> returnType)
      Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.

      See callSubWorkflow(String, Object, String, TaskOptions, Class) for a full description.

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

    • callSubWorkflow

      default com.microsoft.durabletask.Task<Void> callSubWorkflow(String name, Object input, String instanceID, com.microsoft.durabletask.TaskOptions options)
      Asynchronously invokes another workflow as a sub-workflow and returns a Task that completes when the sub-workflow completes.

      See callSubWorkflow(String, Object, String, TaskOptions, Class) for a full description.

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

    • callSubWorkflow

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

      A sub-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 sub-workflows:

      • Splitting large orchestrations into a series of smaller sub-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 sub-workflow and processing its output. This is typically only an issue for very small orchestrations.

      Because sub-workflows are independent of their parents, terminating a parent orchestration does not affect any sub-workflows. sub-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 sub-workflow output
      Parameters:
      name - the name of the workflow to invoke
      input - the serializable input to send to the sub-workflow
      instanceID - the unique ID of the sub-workflow
      options - additional options that control the execution and processing of the activity
      returnType - the expected class type of the sub-workflow output
      Returns:
      a new Task that completes when the sub-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 thecontinueAsNew 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

    • getSagaContext

      SagaContext getSagaContext()
      get saga context.
      Returns:
      saga context
      Throws:
      UnsupportedOperationException - if saga is not enabled.