Failure detection - Temporal Java SDK feature guide

This page shows how to do the following:

Workflow timeouts

How to set Workflow timeouts using the Java SDK.

Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution.

Workflow timeouts are set when starting the Workflow Execution.

Workflow Execution Timeout - restricts the maximum amount of time that a single Workflow Execution can be executed.
Workflow Run Timeout: restricts the maximum amount of time that a single Workflow Run can last.
Workflow Task Timeout: restricts the maximum amount of time that a Worker can execute a Workflow Task.

Create an instance of WorkflowStub in the Client code and set your timeout.

Available timeouts are:

//create Workflow stub for YourWorkflowInterface
YourWorkflowInterface workflow1 =
    WorkerGreet.greetclient.newWorkflowStub(
        GreetWorkflowInterface.class,
        WorkflowOptions.newBuilder()
                .setWorkflowId("YourWorkflow")
                .setTaskQueue(WorkerGreet.TASK_QUEUE)
                // Set Workflow Timeout duration
                .setWorkflowExecutionTimeout(Duration.ofSeconds(10))
                // .setWorkflowRunTimeout(Duration.ofSeconds(10))
                // .setWorkflowTaskTimeout(Duration.ofSeconds(10))
                .build());

Workflow Retry Policy

How to set a Workflow Retry Policy in Java.

A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience.

Use a Retry Policy to retry a Workflow Execution in the event of a failure.

Workflow Executions do not retry by default, and Retry Policies should be used with Workflow Executions only in certain situations.

To set a Workflow Retry Options in the WorkflowStub instance use WorkflowOptions.Builder.setWorkflowRetryOptions.

Type: RetryOptions
Default: Null which means no retries will be attempted.

//create Workflow stub for GreetWorkflowInterface
GreetWorkflowInterface workflow1 =
    WorkerGreet.greetclient.newWorkflowStub(
        GreetWorkflowInterface.class,
        WorkflowOptions.newBuilder()
                .setWorkflowId("GreetWF")
                .setTaskQueue(WorkerGreet.TASK_QUEUE)
                // Set Workflow Retry Options
                .setRetryOptions(RetryOptions.newBuilder()
                .build());

Activity timeouts

How to set Activity timeouts using the Java SDK.

Each Activity timeout controls the maximum duration of a different aspect of an Activity Execution.

The following timeouts are available in the Activity Options.

Schedule-To-Close Timeout: is the maximum amount of time allowed for the overall Activity Execution.
Start-To-Close Timeout: is the maximum time allowed for a single Activity Task Execution.
Schedule-To-Start Timeout: is the maximum amount of time that is allowed from when an Activity Task is scheduled to when a Worker starts that Activity Task.

An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set.

Set your Activity Timeout from the ActivityOptions.Builder class.

Available timeouts are:

ScheduleToCloseTimeout()
ScheduleToStartTimeout()
StartToCloseTimeout()

You can set Activity Options using an ActivityStub within a Workflow implementation, or per-Activity using WorkflowImplementationOptions within a Worker.

The following uses ActivityStub.

GreetingActivities activities = Workflow.newActivityStub(GreetingActivities.class,
                ActivityOptions.newBuilder()
                        .setScheduleToCloseTimeout(Duration.ofSeconds(5))
                        // .setStartToCloseTimeout(Duration.ofSeconds(2)
                        // .setScheduletoCloseTimeout(Duration.ofSeconds(20))
                        .build());

The following uses WorkflowImplementationOptions.

WorkflowImplementationOptions options =
            WorkflowImplementationOptions.newBuilder()
                    .setActivityOptions(
                            ImmutableMap.of(
                                    "GetCustomerGreeting",
                                    // Set Activity Execution timeout
                                    ActivityOptions.newBuilder()
                                        .setScheduleToCloseTimeout(Duration.ofSeconds(5))
                                        // .setStartToCloseTimeout(Duration.ofSeconds(2))
                                        // .setScheduleToStartTimeout(Duration.ofSeconds(5))
                                        .build()))
                    .build();

note

If you define options per-Activity Type options with WorkflowImplementationOptions.setActivityOptions(), setting them again specifically with ActivityStub in a Workflow will override this setting.

Custom Activity Retry Policy

How to set a custom Activity Retry Policy in Java.

A Retry Policy works in cooperation with the timeouts to provide fine controls to optimize the execution experience.

Activity Executions are automatically associated with a default Retry Policy if a custom one is not provided.

To set a Retry Policy, known as the Retry Options in Java, use ActivityOptions.newBuilder.setRetryOptions().

Type: RetryOptions
Default: Server-defined Activity Retry policy.

With ActivityStub

private final ActivityOptions options =
    ActivityOptions.newBuilder()
        // note that either StartToCloseTimeout or ScheduleToCloseTimeout are
        // required when setting Activity options.
        .setStartToCloseTimeout(Duration.ofSeconds(5))
        .setRetryOptions(
            RetryOptions.newBuilder()
                .setInitialInterval(Duration.ofSeconds(1))
                .setMaximumInterval(Duration.ofSeconds(10))
                .build())
        .build();

With WorkflowImplementationOptions

WorkflowImplementationOptions options =
        WorkflowImplementationOptions.newBuilder()
               .setActivityOptions(
                    ImmutableMap.of(
                        "EmailCustomerGreeting",
                        ActivityOptions.newBuilder()
                              // note that either StartToCloseTimeout or ScheduleToCloseTimeout are
                              // required when setting Activity options.
                              .setStartToCloseTimeout(Duration.ofSeconds(5))
                              .setRetryOptions(
                                    RetryOptions.newBuilder()
                                        .setDoNotRetry(NullPointerException.class.getName())
                                        .build())
                              .build()))
              .build();

Overriding the retry interval with Next Retry Delay

You may throw an Application Failure with the NextRetryDelay field set. This value will replace and override whatever the retry interval would be on the retry policy.

For example, if in an activity, you want to base the interval on the number of attempts, you might do:

int attempt = Activity.getExecutionContext().getInfo().getAttempt();

throw ApplicationFailure.newFailureWithCauseAndDelay(
    "Something bad happened on attempt " + attempt,
    "my_failure_type",
    null,
    3 * Duration.ofSeconds(attempt));

Heartbeat an Activity

How to Heartbeat an Activity using the Java SDK.

An Activity Heartbeat is a ping from the Worker Process that is executing the Activity to the Temporal Service. Each Heartbeat informs the Temporal Service that the Activity Execution is making progress and the Worker has not crashed. If the Temporal Service does not receive a Heartbeat within a Heartbeat Timeout time period, the Activity will be considered failed and another Activity Task Execution may be scheduled according to the Retry Policy.

Heartbeats may not always be sent to the Temporal Service—they may be throttled by the Worker.

Activity Cancellations are delivered to Activities from the Temporal Service when they Heartbeat. Activities that don't Heartbeat can't receive a Cancellation. Heartbeat throttling may lead to Cancellation getting delivered later than expected.

Heartbeats can contain a details field describing the Activity's current progress. If an Activity gets retried, the Activity can access the details from the last Heartbeat that was sent to the Temporal Service.

To Heartbeat an Activity Execution in Java, use the Activity.getExecutionContext().heartbeat() Class method.

public class YourActivityDefinitionImpl implements YourActivityDefinition {

  @Override
  public String yourActivityMethod(YourActivityMethodParam param) {
    // ...
    Activity.getExecutionContext().heartbeat(details);
    // ...
  }
  // ...
}

The method takes an optional argument, the details variable above that represents latest progress of the Activity Execution. This method can take a variety of types such as an exception object, custom object, or string.

If the Activity Execution times out, the last Heartbeat details are included in the thrown ActivityTimeoutException, which can be caught by the calling Workflow. The Workflow can then use the details information to pass to the next Activity invocation if needed.

In the case of Activity retries, the last Heartbeat's details are available and can be extracted from the last failed attempt by using Activity.getExecutionContext().getHeartbeatDetails(Class<V> detailsClass)

Heartbeat Timeout

How to set a Heartbeat Timeout using the Java SDK.

A Heartbeat Timeout works in conjunction with Activity Heartbeats.

To set a Heartbeat Timeout, use ActivityOptions.newBuilder.setHeartbeatTimeout.

Type: Duration
Default: None

You can set Activity Options using an ActivityStub within a Workflow implementation, or per-Activity using WorkflowImplementationOptions within a Worker. Note that if you define options per-Activity Type options with WorkflowImplementationOptions.setActivityOptions(), setting them again specifically with ActivityStub in a Workflow will override this setting.

With ActivityStub

private final GreetingActivities activities =
    Workflow.newActivityStub(
        GreetingActivities.class,
        ActivityOptions.newBuilder()
            // note that either StartToCloseTimeout or ScheduleToCloseTimeout are
            // required when setting Activity options.
            .setStartToCloseTimeout(Duration.ofSeconds(5))
            .setHeartbeatTimeout(Duration.ofSeconds(2))
            .build());

With WorkflowImplementationOptions

WorkflowImplementationOptions options =
            WorkflowImplementationOptions.newBuilder()
                    .setActivityOptions(
                            ImmutableMap.of(
                              "EmailCustomerGreeting",
                                    ActivityOptions.newBuilder()
                                        // note that either StartToCloseTimeout or ScheduleToCloseTimeout are
                                        // required when setting Activity options.
                                          .setStartToCloseTimeout(Duration.ofSeconds(5))
                                          .setHeartbeatTimeout(Duration.ofSeconds(2))
                                          .build()))
                    .build();

Workflow timeouts​

Workflow Retry Policy​

Activity timeouts​

Custom Activity Retry Policy​

Overriding the retry interval with Next Retry Delay​

Heartbeat an Activity​

Heartbeat Timeout​