Package com.microsoft.durabletask

Class DurableTaskClient

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public abstract class DurableTaskClient
extends java.lang.Object
implements java.lang.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.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Releases any network resources held by this object.
      abstract void createTaskHub​(boolean recreateIfExists)
      Initializes the target task hub data store.
      abstract void deleteTaskHub()
      Permanently deletes the target task hub data store and any orchestration data it may contain.
      abstract OrchestrationMetadata getInstanceMetadata​(java.lang.String instanceId, boolean getInputsAndOutputs)
      Fetches orchestration instance metadata from the configured durable store.
      abstract PurgeResult purgeInstance​(java.lang.String instanceId)
      Purges orchestration instance metadata from the durable store.
      abstract PurgeResult purgeInstances​(PurgeInstanceCriteria purgeInstanceCriteria)
      Purges orchestration instance metadata from the durable store using a filter that determines which instances to purge data for.
      abstract OrchestrationStatusQueryResult queryInstances​(OrchestrationStatusQuery query)
      Fetches orchestration instance metadata from the configured durable store using a status query filter.
      void raiseEvent​(java.lang.String instanceId, java.lang.String eventName)
      Sends an event notification message to a waiting orchestration instance.
      abstract void raiseEvent​(java.lang.String instanceId, java.lang.String eventName, java.lang.Object eventPayload)
      Sends an event notification message with a payload to a waiting orchestration instance.
      abstract java.lang.String restartInstance​(java.lang.String instanceId, boolean restartWithNewInstanceId)
      Restarts an existing orchestration instance with the original input.
      void resumeInstance​(java.lang.String instanceId)
      Resumes a running orchestration instance.
      abstract void resumeInstance​(java.lang.String instanceId, java.lang.String reason)
      Resumes a running orchestration instance.
      java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName)
      Schedules a new orchestration instance with a random ID for execution.
      abstract java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName, NewOrchestrationInstanceOptions options)
      Schedules a new orchestration instance with a specified set of options for execution.
      java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName, java.lang.Object input)
      Schedules a new orchestration instance with a specified input and a random ID for execution.
      java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName, java.lang.Object input, java.lang.String instanceId)
      Schedules a new orchestration instance with a specified input and ID for execution.
      void suspendInstance​(java.lang.String instanceId)
      Suspends a running orchestration instance.
      abstract void suspendInstance​(java.lang.String instanceId, java.lang.String reason)
      Suspends a running orchestration instance.
      abstract void terminate​(java.lang.String instanceId, java.lang.Object output)
      Terminates a running orchestration instance and updates its runtime status to Terminated.
      abstract OrchestrationMetadata waitForInstanceCompletion​(java.lang.String instanceId, java.time.Duration timeout, boolean getInputsAndOutputs)
      Waits for an orchestration to complete and returns an OrchestrationMetadata object that contains metadata about the completed instance.
      OrchestrationMetadata waitForInstanceStart​(java.lang.String instanceId, java.time.Duration timeout)
      Waits for an orchestration to start running and returns an OrchestrationMetadata object that contains metadata about the started instance.
      abstract OrchestrationMetadata waitForInstanceStart​(java.lang.String instanceId, java.time.Duration timeout, boolean getInputsAndOutputs)
      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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • DurableTaskClient

        public DurableTaskClient()

    • Method Detail

      • close

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

      • scheduleNewOrchestrationInstance

        public java.lang.String scheduleNewOrchestrationInstance​(java.lang.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 java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName,
                                                         java.lang.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 java.lang.String scheduleNewOrchestrationInstance​(java.lang.String orchestratorName,
                                                         java.lang.Object input,
                                                         java.lang.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 java.lang.String scheduleNewOrchestrationInstance​(java.lang.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​(java.lang.String instanceId,
                       java.lang.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​(java.lang.String instanceId,
                                java.lang.String eventName,
                                @Nullable
                                java.lang.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​(java.lang.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​(java.lang.String instanceId,
                                                  java.time.Duration timeout)
                                           throws java.util.concurrent.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:
        java.util.concurrent.TimeoutException - when the orchestration instance is not started within the specified amount of time

      • waitForInstanceStart

        @Nullable
public abstract OrchestrationMetadata waitForInstanceStart​(java.lang.String instanceId,
                                                           java.time.Duration timeout,
                                                           boolean getInputsAndOutputs)
                                                    throws java.util.concurrent.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:
        java.util.concurrent.TimeoutException - when the orchestration instance is not started within the specified amount of time

      • waitForInstanceCompletion

        @Nullable
public abstract OrchestrationMetadata waitForInstanceCompletion​(java.lang.String instanceId,
                                                                java.time.Duration timeout,
                                                                boolean getInputsAndOutputs)
                                                         throws java.util.concurrent.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:
        java.util.concurrent.TimeoutException - when the orchestration instance is not completed within the specified amount of time

      • terminate

        public abstract void terminate​(java.lang.String instanceId,
                               @Nullable
                               java.lang.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​(java.lang.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 java.util.concurrent.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:
        java.util.concurrent.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 java.lang.String restartInstance​(java.lang.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​(java.lang.String instanceId)
        Suspends a running orchestration instance.
        Parameters:
        instanceId - the ID of the orchestration instance to suspend

      • resumeInstance

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

      • suspendInstance

        public abstract void suspendInstance​(java.lang.String instanceId,
                                     @Nullable
                                     java.lang.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 abstract void resumeInstance​(java.lang.String instanceId,
                                    @Nullable
                                    java.lang.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