DurableTaskClient Class

Package:

com.microsoft.durabletask

Maven Artifact:

com.microsoft:durabletask-client:1.0.0

• java.lang.Object
• • com.microsoft.durabletask.DurableTaskClient

Implements

java.lang.AutoCloseable

public abstract class DurableTaskClient
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.

Constructor Summary

Constructor	Description
DurableTaskClient()

Method Summary

Modifier and Type	Method and 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(String instanceId, boolean getInputsAndOutputs) Fetches orchestration instance metadata from the configured durable store.
abstract PurgeResult	purgeInstance(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(String instanceId, String eventName) Sends an event notification message to a waiting orchestration instance.
abstract void	raiseEvent(String instanceId, String eventName, Object eventPayload) Sends an event notification message with a payload to a waiting orchestration instance.
java.lang.String	scheduleNewOrchestrationInstance(String orchestratorName) Schedules a new orchestration instance with a random ID for execution.
abstract java.lang.String	scheduleNewOrchestrationInstance(String orchestratorName, NewOrchestrationInstanceOptions options) Schedules a new orchestration instance with a specified set of options for execution.
java.lang.String	scheduleNewOrchestrationInstance(String orchestratorName, Object input) Schedules a new orchestration instance with a specified input and a random ID for execution.
java.lang.String	scheduleNewOrchestrationInstance(String orchestratorName, Object input, String instanceId) Schedules a new orchestration instance with a specified input and ID for execution.
abstract void	terminate(String instanceId, Object output) Terminates a running orchestration instance and updates its runtime status to Terminated.
abstract OrchestrationMetadata	waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs) Waits for an orchestration to complete and returns an OrchestrationMetadata object that contains metadata about the completed instance.
OrchestrationMetadata	waitForInstanceStart(String instanceId, Duration timeout) Waits for an orchestration to start running and returns an OrchestrationMetadata object that contains metadata about the started instance.
abstract OrchestrationMetadata	waitForInstanceStart(String instanceId, 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 java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

DurableTaskClient

public DurableTaskClient()

Method Details

close

public void close()

Releases any network resources held by this object.

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.

getInstanceMetadata

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 isInstanceFound() to check if an instance is found.

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)

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

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

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 waitForExternalEvent(String name) 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 waitForExternalEvent(String name). 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, 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 waitForExternalEvent(String name) 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 waitForExternalEvent(String name). 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

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 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

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

terminate

public abstract void terminate(String instanceId, 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 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.

waitForInstanceCompletion

public abstract OrchestrationMetadata waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs)

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

waitForInstanceStart

public OrchestrationMetadata waitForInstanceStart(String instanceId, Duration timeout)

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

public abstract OrchestrationMetadata waitForInstanceStart(String instanceId, 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.

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