Package io.dapr.durabletask

Class DurableTaskGrpcClient

java.lang.Object
io.dapr.durabletask.DurableTaskClient
io.dapr.durabletask.DurableTaskGrpcClient
All Implemented Interfaces:
AutoCloseable
public final class DurableTaskGrpcClient extends DurableTaskClient
Durable Task client implementation that uses gRPC to connect to a remote "sidecar" process.

  • Method Details

    • close

      public void close()
      Closes the internally managed gRPC channel, if one exists.

      This method is a no-op if this client object was created using a builder with a gRPC channel object explicitly configured.

      Specified by:
      close in interface AutoCloseable
      Overrides:
      close in class DurableTaskClient

    • scheduleNewOrchestrationInstance

      public String scheduleNewOrchestrationInstance(String orchestratorName, NewOrchestrationInstanceOptions options)
      Description copied from class: DurableTaskClient
      Schedules a new orchestration instance with a specified set of options for execution.
      Specified by:
      scheduleNewOrchestrationInstance in class DurableTaskClient
      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, Object eventPayload)
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      raiseEvent in class DurableTaskClient
      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

      public OrchestrationMetadata getInstanceMetadata(String instanceId, boolean getInputsAndOutputs)
      Description copied from class: DurableTaskClient
      Fetches orchestration instance metadata from the configured durable store.
      Specified by:
      getInstanceMetadata in class DurableTaskClient
      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

      public OrchestrationMetadata waitForInstanceStart(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      waitForInstanceStart in class DurableTaskClient
      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

      public OrchestrationMetadata waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      waitForInstanceCompletion in class DurableTaskClient
      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 void terminate(String instanceId, @Nullable Object output)
      Description copied from class: DurableTaskClient
      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 DurableTaskClient.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.

      Specified by:
      terminate in class DurableTaskClient
      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 OrchestrationStatusQueryResult queryInstances(OrchestrationStatusQuery query)
      Description copied from class: DurableTaskClient
      Fetches orchestration instance metadata from the configured durable store using a status query filter.
      Specified by:
      queryInstances in class DurableTaskClient
      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 void createTaskHub(boolean recreateIfExists)
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      createTaskHub in class DurableTaskClient
      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 void deleteTaskHub()
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      deleteTaskHub in class DurableTaskClient

    • purgeInstance

      public PurgeResult purgeInstance(String instanceId)
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      purgeInstance in class DurableTaskClient
      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 PurgeResult purgeInstances(PurgeInstanceCriteria purgeInstanceCriteria) throws TimeoutException
      Description copied from class: DurableTaskClient
      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.

      Specified by:
      purgeInstances in class DurableTaskClient
      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

    • suspendInstance

      public void suspendInstance(String instanceId, @Nullable String reason)
      Description copied from class: DurableTaskClient
      Suspends a running orchestration instance.
      Specified by:
      suspendInstance in class DurableTaskClient
      Parameters:
      instanceId - the ID of the orchestration instance to suspend
      reason - the reason for suspending the orchestration instance

    • resumeInstance

      public void resumeInstance(String instanceId, @Nullable String reason)
      Description copied from class: DurableTaskClient
      Resumes a running orchestration instance.
      Specified by:
      resumeInstance in class DurableTaskClient
      Parameters:
      instanceId - the ID of the orchestration instance to resume
      reason - the reason for resuming the orchestration instance

    • restartInstance

      public String restartInstance(String instanceId, boolean restartWithNewInstanceId)
      Description copied from class: DurableTaskClient
      Restarts an existing orchestration instance with the original input.
      Specified by:
      restartInstance in class DurableTaskClient
      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