TaskOrchestrationContext Interface

Package:: com.microsoft.durabletask

Maven Artifact:: com.microsoft:durabletask-client:1.0.0

public interface TaskOrchestrationContext

Used by orchestrators to perform actions such as scheduling tasks, durable timers, waiting for external events, and for getting basic information about the current orchestration.

Method Summary

Modifier and Type	Method and Description
abstract Task<java.util.List<V>>	allOf(List<Task<V>> tasks) Returns a new `Task` that is completed when all the given `Task`s complete.
default Task<V>	callActivity(String name, Class<V> returnType) Asynchronously invokes an activity by name and returns a new Task<V> that completes when the activity completes.
abstract Task<V>	callActivity(String name, Object input, TaskOptions options, Class<V> returnType) Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> that completes when the activity completes.
default 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<V> that completes when the activity completes.If the activity completes successfully, the returned `Task`'s value will be the activity's output.
default Task<V>	callSubOrchestrator(String name, Object input, Class<V> returnType) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
abstract Task<V>	callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
default Task<V>	callSubOrchestrator(String name, Object input, String instanceID, Class<V> returnType) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
abstract V	getInput(Class<V> targetType) Gets the deserialized input of the current task orchestration.
default Task<V>	waitForExternalEvent(String name, Class<V> dataType) Waits for an event to be raised named `name` and returns a Task<V> that completes when the event is received.
abstract Task<V>	waitForExternalEvent(String name, Duration timeout, Class<V> dataType) Waits for an event to be raised named `name` and returns a Task<V> that completes when the event is received or is canceled when `timeout` expires.
default Task<Task<?>>	anyOf(Task<?>[] tasks) Returns a new `Task` that is completed when any of the given `Task`s complete.
abstract Task<Task<?>>	anyOf(List<Task<?>> tasks) Returns a new `Task` that is completed when any of the tasks in `tasks` completes.
default Task<java.lang.Void>	callActivity(String name) Asynchronously invokes an activity by name and returns a new Task<V> that completes when the activity completes.
default Task<java.lang.Void>	callActivity(String name, Object input) Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> that completes when the activity completes.
default Task<java.lang.Void>	callActivity(String name, Object input, TaskOptions options) Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> that completes when the activity completes.
default Task<java.lang.Void>	callSubOrchestrator(String name) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
default Task<java.lang.Void>	callSubOrchestrator(String name, Object input) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
default Task<java.lang.Void>	callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options) Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.
abstract void	clearCustomStatus() Clears the orchestration's custom status.
abstract void	complete(Object output) Transitions the orchestration into the COMPLETED state with the given output.
default void	continueAsNew(Object input) Restarts the orchestration with a new input and clears its history.
abstract void	continueAsNew(Object input, boolean preserveUnprocessedEvents) Restarts the orchestration with a new input and clears its history.
abstract Task<java.lang.Void>	createTimer(Duration delay) Creates a durable timer that expires after the specified delay.
abstract java.time.Instant	getCurrentInstant() Gets the current orchestration time in UTC.
abstract java.lang.String	getInstanceId() Gets the unique ID of the current orchestration instance.
abstract boolean	getIsReplaying() Gets a value indicating whether the orchestrator is currently replaying a previous execution.
abstract java.lang.String	getName() Gets the name of the current task orchestration.
default void	sendEvent(String instanceID, String eventName) Sends an external event to another orchestration instance.
abstract void	sendEvent(String instanceId, String eventName, Object eventData) Sends an external event to another orchestration instance.
abstract void	setCustomStatus(Object customStatus) Assigns a custom status value to the current orchestration.
default Task<java.lang.Void>	waitForExternalEvent(String name) Waits for an event to be raised named `name` and returns a Task<V> that completes when the event is received.
default Task<java.lang.Void>	waitForExternalEvent(String name, Duration timeout) Waits for an event to be raised named `name` and returns a Task<V> that completes when the event is received or is canceled when `timeout` expires.

Method Details

allOf

public abstract Task> allOf(List> tasks)

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 t1 = ctx.callActivity("MyActivity", String.class);
 Task t2 = ctx.callActivity("MyActivity", String.class);
 Task t3 = ctx.callActivity("MyActivity", String.class);

 List 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 Task<V>s.

try {
     List orderedResults = ctx.allOf(List.of(t1, t2, t3)).await();
 } catch (CompositeTaskFailedException e) {
     List exceptions = e.getExceptions()
 }

Parameters:

tasks - the list of Task objects

Returns:

the values of the completed Task objects in the same order as the source list

callActivity

public default Task callActivity(String name, Class returnType)

Asynchronously invokes an activity by name and returns a new Task<V> 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 name, Object input, TaskOptions options, Class<V> returnType) for a complete description.

Parameters:

name - the name of the activity to call

returnType - the expected class type of the activity output

Returns:

a new Task<V> that completes when the activity completes or fails

callActivity

public abstract Task callActivity(String name, Object input, TaskOptions options, Class returnType)

Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> 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.

Activities are the basic unit of work in a durable task orchestration. Unlike orchestrators, which are not allowed to do any I/O or call non-deterministic APIs, activities have no implementation restrictions.

An activity may execute in the local machine or a remote machine. The exact behavior depends on the underlying storage provider, which is responsible for distributing tasks across machines. In general, you should never make any assumptions about where an activity will run. You should also assume at-least-once execution guarantees for activities, meaning that an activity may be executed twice if, for example, there is a process failure before the activities result is saved into storage.

Both the inputs and outputs of activities are serialized and stored in durable storage. It's highly recommended to not include any sensitive data in activity inputs or outputs. It's also recommended to not use large payloads for activity inputs and outputs, which can result in expensive serialization and network utilization. For data that cannot be cheaply or safely persisted to storage, it's recommended to instead pass references (for example, a URL to a storage blog) to the data and have activities fetch the data directly as part of their implementation.

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<V> that completes when the activity completes or fails

callActivity

public default Task callActivity(String name, Object input, Class returnType)

Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> 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 name, Object input, TaskOptions options, Class<V> returnType) for a complete description.

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<V> that completes when the activity completes or fails

callSubOrchestrator

public default Task callSubOrchestrator(String name, Object input, Class returnType)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.

See callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) for a full description.

Parameters:

name - the name of the orchestrator to invoke

input - the serializable input to send to the sub-orchestration

returnType - the expected class type of the sub-orchestration output

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

callSubOrchestrator

public abstract Task callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class returnType)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes. If the sub-orchestration completes successfully, the returned Task's value will be the activity's output. If the sub-orchestration fails, the returned Task will complete exceptionally with a TaskFailedException.

A sub-orchestration has its own instance ID, history, and status that is independent of the parent orchestrator that started it. There are many advantages to breaking down large orchestrations into sub-orchestrations:

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

Because sub-orchestrations are independent of their parents, terminating a parent orchestration does not affect any sub-orchestrations. Sub-orchestrations must be terminated independently using their unique instance ID, which is specified using the instanceID parameter

Parameters:

name - the name of the orchestrator to invoke

input - the serializable input to send to the sub-orchestration

instanceID - the unique ID of the sub-orchestration

options - additional options that control the execution and processing of the activity

returnType - the expected class type of the sub-orchestration output

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

callSubOrchestrator

public default Task callSubOrchestrator(String name, Object input, String instanceID, Class returnType)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.

See callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) for a full description.

Parameters:

name - the name of the orchestrator to invoke

input - the serializable input to send to the sub-orchestration

instanceID - the unique ID of the sub-orchestration

returnType - the expected class type of the sub-orchestration output

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

getInput

public abstract V getInput(Class targetType)

Gets the deserialized input of the current task orchestration.

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.

waitForExternalEvent

public default Task waitForExternalEvent(String name, Class dataType)

Waits for an event to be raised named name and returns a Task<V> that completes when the event is received.

See waitForExternalEvent(String name, Duration timeout, Class<V> dataType) for a full description.

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<V> that completes when the external event is received

waitForExternalEvent

public abstract Task waitForExternalEvent(String name, Duration timeout, Class dataType)

Waits for an event to be raised named name and returns a Task<V> that completes when the event is received or is canceled when timeout expires.

External clients can raise events to a waiting orchestration instance using the DurableTaskClient#raiseEvent method.

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.

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<V> that completes when the external event is received or when timeout expires

Throws:

TaskCanceledException - if the specified timeout value expires before the event is received

anyOf

public default Task> anyOf(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 event1 = ctx.waitForExternalEvent("Event1");
 Task event2 = ctx.waitForExternalEvent("Event2");
 Task 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 activityTask = ctx.callActivity("SlowActivity");
 Task 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

anyOf

public abstract Task> anyOf(List> tasks)

Returns a new Task that is completed when any of the tasks in tasks completes. See anyOf(Task<?>[] tasks) 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

callActivity

public default Task callActivity(String name)

Asynchronously invokes an activity by name and returns a new Task<V> that completes when the activity completes. See callActivity(String name, Object input, TaskOptions options, Class<V> returnType) for a complete description.

Parameters:

name - the name of the activity to call

Returns:

a new Task<V> that completes when the activity completes or fails

callActivity

public default Task callActivity(String name, Object input)

Asynchronously invokes an activity by name and with the specified input value and returns a new Task<V> that completes when the activity completes. See callActivity(String name, Object input, TaskOptions options, Class<V> returnType) 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<V> that completes when the activity completes or fails

callActivity

public default Task callActivity(String name, Object input, TaskOptions options)

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<V> that completes when the activity completes or fails

callSubOrchestrator

public default Task callSubOrchestrator(String name)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.

See callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) for a full description.

Parameters:

name - the name of the orchestrator to invoke

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

callSubOrchestrator

public default Task callSubOrchestrator(String name, Object input)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.

See callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) for a full description.

Parameters:

name - the name of the orchestrator to invoke

input - the serializable input to send to the sub-orchestration

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

callSubOrchestrator

public default Task callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options)

Asynchronously invokes another orchestrator as a sub-orchestration and returns a Task<V> that completes when the sub-orchestration completes.

See callSubOrchestrator(String name, Object input, String instanceID, TaskOptions options, Class<V> returnType) for a full description.

Parameters:

name - the name of the orchestrator to invoke

input - the serializable input to send to the sub-orchestration

instanceID - the unique ID of the sub-orchestration

options - additional options that control the execution and processing of the activity

Returns:

a new Task<V> that completes when the sub-orchestration completes or fails

clearCustomStatus

public abstract void clearCustomStatus()

Clears the orchestration's custom status.

complete

public abstract void complete(Object output)

Transitions the orchestration into the COMPLETED state with the given output.

Parameters:

output - the serializable output of the completed orchestration

continueAsNew

public default void continueAsNew(Object input)

Restarts the orchestration with a new input and clears its history. See continueAsNew(Object input, boolean preserveUnprocessedEvents) for a full description.

Parameters:

input - the serializable input data to re-initialize the instance with

continueAsNew

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

createTimer

public abstract Task createTimer(Duration delay)

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:

delay - the amount of time before the timer should expire

Returns:

a new Task that completes after the specified delay

getCurrentInstant

public abstract Instant getCurrentInstant()

Gets the current orchestration time in UTC.

Returns:

the current orchestration time in UTC

getInstanceId

public abstract String getInstanceId()

Gets the unique ID of the current orchestration instance.

Returns:

the unique ID of the current orchestration instance

getIsReplaying

public abstract boolean getIsReplaying()

Gets a value indicating whether the orchestrator is currently replaying a previous execution.

Orchestrator 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 orchestration history. One the orchestrator reaches the point in the orchestrator 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 orchestrator is replaying, otherwise false

getName

public abstract String getName()

Gets the name of the current task orchestration.

Returns:

the name of the current task orchestration

sendEvent

public default void sendEvent(String instanceID, String eventName)

Sends an external event to another orchestration instance.

Parameters:

instanceID - the unique ID of the receiving orchestration instance.

eventName - the name of the event to send

sendEvent

public abstract void sendEvent(String instanceId, String eventName, Object eventData)

Sends an external event to another orchestration instance.

Parameters:

instanceId - the unique ID of the receiving orchestration instance.

eventName - the name of the event to send

eventData - the payload of the event to send

setCustomStatus

public abstract void setCustomStatus(Object customStatus)

Assigns a custom status value to the current orchestration.

The customStatus value is serialized and stored in orchestration state and will be made available to the orchestration status query APIs, such as DurableTaskClient#getInstanceMetadata. The serialized value must not exceed 16 KB of UTF-16 encoded text.

Use clearCustomStatus() to remove the custom status value from the orchestration state.

Parameters:

customStatus - A serializable value to assign as the custom status value.

waitForExternalEvent

public default Task waitForExternalEvent(String name)

Waits for an event to be raised named name and returns a Task<V> that completes when the event is received.

See waitForExternalEvent(String name, Duration timeout, Class<V> dataType) for a full description.

Parameters:

name - the case-insensitive name of the event to wait for

Returns:

a new Task<V> that completes when the external event is received

waitForExternalEvent

public default Task waitForExternalEvent(String name, Duration timeout)

Waits for an event to be raised named name and returns a Task<V> that completes when the event is received or is canceled when timeout expires.

See waitForExternalEvent(String name, Duration timeout, Class<V> dataType) for a full description.

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<V> that completes when the external event is received or when timeout expires

Throws:

TaskCanceledException - if the specified timeout value expires before the event is received

Share via

TaskOrchestrationContext Interface

Method Summary

Method Details

allOf

callActivity

callActivity

callActivity

callSubOrchestrator

callSubOrchestrator

callSubOrchestrator

getInput

waitForExternalEvent

waitForExternalEvent

anyOf

anyOf

callActivity

callActivity

callActivity

callSubOrchestrator

callSubOrchestrator

callSubOrchestrator

clearCustomStatus

complete

continueAsNew

continueAsNew

createTimer

getCurrentInstant

getInstanceId

getIsReplaying

getName

sendEvent

sendEvent

setCustomStatus

waitForExternalEvent

waitForExternalEvent

Applies to