Package io.dapr.durabletask

Class DurableTaskClient

java.lang.Object
io.dapr.durabletask.DurableTaskClient
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
DurableTaskGrpcClient
public abstract class DurableTaskClient extends Object implements AutoCloseable
Base class that defines client operations for managing orchestration instances.

Instances of this class can be used to start, query, raise events to, and terminate orchestration instances. In most cases, methods on this class accept an instance ID as a parameter, which identifies the orchestration instance.

At the time of writing, the most common implementation of this class is DurableTaskGrpcClient, which works by making gRPC calls to a remote service (e.g. a sidecar) that implements the operation behavior. To ensure any owned network resources are properly released, instances of this class should be closed when they are no longer needed.

Instances of this class are expected to be safe for multithreaded apps. You can therefore safely cache instances of this class and reuse them across multiple contexts. Caching these objects is useful to improve overall performance.

  • Constructor Details

    • DurableTaskClient

      public DurableTaskClient()

  • Method Details

    • close

      public void close()
      Releases any network resources held by this object.
      Specified by:
      close in interface AutoCloseable

    • scheduleNewOrchestrationInstance

      public String scheduleNewOrchestrationInstance(String orchestratorName)
      Schedules a new orchestration instance with a random ID for execution.
      Parameters:
      orchestratorName - the name of the orchestrator to schedule
      Returns:
      the randomly-generated instance ID of the scheduled orchestration instance

    • scheduleNewOrchestrationInstance

      public String scheduleNewOrchestrationInstance(String orchestratorName, Object input)
      Schedules a new orchestration instance with a specified input and a random ID for execution.
      Parameters:
      orchestratorName - the name of the orchestrator to schedule
      input - the input to pass to the scheduled orchestration instance. Must be serializable.
      Returns:
      the randomly-generated instance ID of the scheduled orchestration instance

    • scheduleNewOrchestrationInstance

      public String scheduleNewOrchestrationInstance(String orchestratorName, Object input, String instanceId)
      Schedules a new orchestration instance with a specified input and ID for execution.
      Parameters:
      orchestratorName - the name of the orchestrator to schedule
      input - the input to pass to the scheduled orchestration instance. Must be serializable.
      instanceId - the unique ID of the orchestration instance to schedule
      Returns:
      the instanceId parameter value

    • scheduleNewOrchestrationInstance

      public abstract String scheduleNewOrchestrationInstance(String orchestratorName, NewOrchestrationInstanceOptions options)
      Schedules a new orchestration instance with a specified set of options for execution.
      Parameters:
      orchestratorName - the name of the orchestrator to schedule
      options - the options for the new orchestration instance, including input, instance ID, etc.
      Returns:
      the ID of the scheduled orchestration instance, which was either provided in options or randomly generated

    • raiseEvent

      public void raiseEvent(String instanceId, String eventName)
      Sends an event notification message to a waiting orchestration instance.

      In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the TaskOrchestrationContext.waitForExternalEvent(String) method. If the target orchestration instance is not yet waiting for an event named eventName, then the event will be saved in the orchestration instance state and dispatched immediately when the orchestrator calls TaskOrchestrationContext.waitForExternalEvent(String). This event saving occurs even if the orchestrator has canceled its wait operation before the event was received.

      Raised events for a completed or non-existent orchestration instance will be silently discarded.

      Parameters:
      instanceId - the ID of the orchestration instance that will handle the event
      eventName - the case-insensitive name of the event

    • raiseEvent

      public abstract void raiseEvent(String instanceId, String eventName, @Nullable Object eventPayload)
      Sends an event notification message with a payload to a waiting orchestration instance.

      In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the TaskOrchestrationContext.waitForExternalEvent(String) method. If the target orchestration instance is not yet waiting for an event named eventName, then the event will be saved in the orchestration instance state and dispatched immediately when the orchestrator calls TaskOrchestrationContext.waitForExternalEvent(String). This event saving occurs even if the orchestrator has canceled its wait operation before the event was received.

      Raised events for a completed or non-existent orchestration instance will be silently discarded.

      Parameters:
      instanceId - the ID of the orchestration instance that will handle the event
      eventName - the case-insensitive name of the event
      eventPayload - the serializable data payload to include with the event

    • getInstanceMetadata

      @Nullable public abstract OrchestrationMetadata getInstanceMetadata(String instanceId, boolean getInputsAndOutputs)
      Fetches orchestration instance metadata from the configured durable store.
      Parameters:
      instanceId - the unique ID of the orchestration instance to fetch
      getInputsAndOutputs - true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      a metadata record that describes the orchestration instance and its execution status, or a default instance if no such instance is found. Please refer to method OrchestrationMetadata.isInstanceFound() to check if an instance is found.

    • waitForInstanceStart

      @Nullable public OrchestrationMetadata waitForInstanceStart(String instanceId, Duration timeout) throws TimeoutException
      Waits for an orchestration to start running and returns an OrchestrationMetadata object that contains metadata about the started instance.

      A "started" orchestration instance is any instance not in the Pending state.

      If an orchestration instance is already running when this method is called, the method will return immediately.

      Note that this method overload will not fetch the orchestration's inputs, outputs, or custom status payloads.

      Parameters:
      instanceId - the unique ID of the orchestration instance to wait for
      timeout - the amount of time to wait for the orchestration instance to start
      Returns:
      the orchestration instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the orchestration instance is not started within the specified amount of time

    • waitForInstanceStart

      @Nullable public abstract OrchestrationMetadata waitForInstanceStart(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Waits for an orchestration to start running and returns an OrchestrationMetadata object that contains metadata about the started instance and optionally its input, output, and custom status payloads.

      A "started" orchestration instance is any instance not in the Pending state.

      If an orchestration instance is already running when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the orchestration instance to wait for
      timeout - the amount of time to wait for the orchestration instance to start
      getInputsAndOutputs - true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the orchestration instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the orchestration instance is not started within the specified amount of time

    • waitForInstanceCompletion

      @Nullable public abstract OrchestrationMetadata waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Waits for an orchestration to complete and returns an OrchestrationMetadata object that contains metadata about the completed instance.

      A "completed" orchestration instance is any instance in one of the terminal states. For example, the Completed, Failed, or Terminated states.

      Orchestrations are long-running and could take hours, days, or months before completing. Orchestrations can also be eternal, in which case they'll never complete unless terminated. In such cases, this call may block indefinitely, so care must be taken to ensure appropriate timeouts are used.

      If an orchestration instance is already complete when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the orchestration instance to wait for
      timeout - the amount of time to wait for the orchestration instance to complete
      getInputsAndOutputs - true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the orchestration instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the orchestration instance is not completed within the specified amount of time

    • terminate

      public abstract void terminate(String instanceId, @Nullable Object output)
      Terminates a running orchestration instance and updates its runtime status to Terminated.

      This method internally enqueues a "terminate" message in the task hub. When the task hub worker processes this message, it will update the runtime status of the target instance to Terminated. You can use the waitForInstanceCompletion(java.lang.String, java.time.Duration, boolean) to wait for the instance to reach the terminated state.

      Terminating an orchestration instance has no effect on any in-flight activity function executions or sub-orchestrations that were started by the terminated instance. Those actions will continue to run without interruption. However, their results will be discarded. If you want to terminate sub-orchestrations, you must issue separate terminate commands for each sub-orchestration instance.

      At the time of writing, there is no way to terminate an in-flight activity execution.

      Attempting to terminate a completed or non-existent orchestration instance will fail silently.

      Parameters:
      instanceId - the unique ID of the orchestration instance to terminate
      output - the optional output to set for the terminated orchestration instance. This value must be serializable.

    • queryInstances

      public abstract OrchestrationStatusQueryResult queryInstances(OrchestrationStatusQuery query)
      Fetches orchestration instance metadata from the configured durable store using a status query filter.
      Parameters:
      query - filter criteria that determines which orchestrations to fetch data for.
      Returns:
      the result of the query operation, including instance metadata and possibly a continuation token

    • createTaskHub

      public abstract void createTaskHub(boolean recreateIfExists)
      Initializes the target task hub data store.

      This is an administrative operation that only needs to be done once for the lifetime of the task hub.

      Parameters:
      recreateIfExists - true to delete any existing task hub first; false to make this operation a no-op if the task hub data store already exists. Note that deleting a task hub will result in permanent data loss. Use this operation with care.

    • deleteTaskHub

      public abstract void deleteTaskHub()
      Permanently deletes the target task hub data store and any orchestration data it may contain.

      This is an administrative operation that is irreversible. It should be used with great care.

    • purgeInstance

      public abstract PurgeResult purgeInstance(String instanceId)
      Purges orchestration instance metadata from the durable store.

      This method can be used to permanently delete orchestration metadata from the underlying storage provider, including any stored inputs, outputs, and orchestration history records. This is often useful for implementing data retention policies and for keeping storage costs minimal. Only orchestration instances in the Completed, Failed, or Terminated state can be purged.

      If the target orchestration instance is not found in the data store, or if the instance is found but not in a terminal state, then the returned PurgeResult will report that zero instances were purged. Otherwise, the existing data will be purged and the returned PurgeResult will report that one instance was purged.

      Parameters:
      instanceId - the unique ID of the orchestration instance to purge
      Returns:
      the result of the purge operation, including the number of purged orchestration instances (0 or 1)

    • purgeInstances

      public abstract PurgeResult purgeInstances(PurgeInstanceCriteria purgeInstanceCriteria) throws TimeoutException
      Purges orchestration instance metadata from the durable store using a filter that determines which instances to purge data for.

      This method can be used to permanently delete orchestration metadata from the underlying storage provider, including any stored inputs, outputs, and orchestration history records. This is often useful for implementing data retention policies and for keeping storage costs minimal. Only orchestration instances in the Completed, Failed, or Terminated state can be purged.

      Depending on the type of the durable store, purge operations that target multiple orchestration instances may take a long time to complete and be resource intensive. It may therefore be useful to break up purge operations into multiple method calls over a period of time and have them cover smaller time windows.

      Parameters:
      purgeInstanceCriteria - orchestration instance filter criteria used to determine which instances to purge
      Returns:
      the result of the purge operation, including the number of purged orchestration instances (0 or 1)
      Throws:
      TimeoutException - when purging instances is not completed within the specified amount of time. The default timeout for purging instances is 10 minutes

    • restartInstance

      public abstract String restartInstance(String instanceId, boolean restartWithNewInstanceId)
      Restarts an existing orchestration instance with the original input.
      Parameters:
      instanceId - the ID of the previously run orchestration instance to restart.
      restartWithNewInstanceId - true to restart the orchestration instance with a new instance ID false to restart the orchestration instance with same instance ID
      Returns:
      the ID of the scheduled orchestration instance, which is either instanceId or randomly generated depending on the value of restartWithNewInstanceId

    • suspendInstance

      public void suspendInstance(String instanceId)
      Suspends a running orchestration instance.
      Parameters:
      instanceId - the ID of the orchestration instance to suspend

    • suspendInstance

      public abstract void suspendInstance(String instanceId, @Nullable String reason)
      Suspends a running orchestration instance.
      Parameters:
      instanceId - the ID of the orchestration instance to suspend
      reason - the reason for suspending the orchestration instance

    • resumeInstance

      public void resumeInstance(String instanceId)
      Resumes a running orchestration instance.
      Parameters:
      instanceId - the ID of the orchestration instance to resume

    • resumeInstance

      public abstract void resumeInstance(String instanceId, @Nullable String reason)
      Resumes a running orchestration instance.
      Parameters:
      instanceId - the ID of the orchestration instance to resume
      reason - the reason for resuming the orchestration instance