Skip to main content
Version: june-2022

Java ActivityOptions reference

Use ActivityOptions to configure how to invoke an Activity Execution.

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.

The following table lists all ActivityOptions that can be configured for an Activity invocation.

OptionRequiredType
setScheduleToCloseTimeoutYes (if StartToCloseTimeout is not specified)Duration
setScheduleToStartTimeoutNoDuration
setStartToCloseTimeoutYes (if ScheduleToCloseTimeout is not specified)Duration
setHeartbeatTimeoutNoDuration
setTaskQueueNoString
setRetryOptionsNoRetryOptions
setCancellationTypeNoActivityCancellationType

ScheduleToCloseTimeout

To set a Schedule-To-Close Timeout, use ActivityOptions.newBuilder.setScheduleToCloseTimeout​.

This or StartToCloseTimeout must be set.

  • Type: Duration
  • Default: Unlimited. Note that if WorkflowRunTimeout and/or WorkflowExecutionTimeout are defined in the Workflow, all Activity retries will stop when either or both of these timeouts are reached.

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

    GreetingActivities activities = Workflow.newActivityStub(GreetingActivities.class,
    ActivityOptions.newBuilder()
    .setScheduleToCloseTimeout(Duration.ofSeconds(5))
    .build());
  • With WorkflowImplementationOptions

    WorkflowImplementationOptions options =
    WorkflowImplementationOptions.newBuilder()
    .setActivityOptions(
    ImmutableMap.of(
    "GetCustomerGreeting",
    ActivityOptions.newBuilder()
    .setScheduleToCloseTimeout(Duration.ofSeconds(5))
    .build()))
    .build();

ScheduleToStartTimeout

To set a Schedule-To-Start Timeout, use ActivityOptions.newBuilder.setScheduleToStartTimeout​.

  • Type: Duration
  • Default: Unlimited. This timeout is non-retryable.

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

    GreetingActivities activities = Workflow.newActivityStub(GreetingActivities.class,
    ActivityOptions.newBuilder()
    .setScheduleToStartTimeout(Duration.ofSeconds(5))
    // note that either StartToCloseTimeout or ScheduleToCloseTimeout are
    // required when setting Activity options.
    .setScheduletoCloseTimeout(Duration.ofSeconds(20))
    .build());
  • With WorkflowImplementationOptions

    WorkflowImplementationOptions options =
    WorkflowImplementationOptions.newBuilder()
    .setActivityOptions(
    ImmutableMap.of(
    "GetCustomerGreeting",
    ActivityOptions.newBuilder()
    .setScheduleToStartTimeout(Duration.ofSeconds(5))
    .build()))
    .build();

StartToCloseTimeout

To set a Start-To-Close Timeout, use ActivityOptions.newBuilder.setStartToCloseTimeout​.

This or ScheduleToClose must be set.

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

    GreetingActivities activities = Workflow.newActivityStub(GreetingActivities.class,
    ActivityOptions.newBuilder()
    .setStartToCloseTimeout(Duration.ofSeconds(2))
    .build());
  • With WorkflowImplementationOptions

    WorkflowImplementationOptions options =
    WorkflowImplementationOptions.newBuilder()
    .setActivityOptions(
    ImmutableMap.of(
    "EmailCustomerGreeting",
    ActivityOptions.newBuilder()
    // Set Activity Execution timeout (single run)
    .setStartToCloseTimeout(Duration.ofSeconds(2))
    .build()))
    .build();

HeartbeatTimeout

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();

TaskQueue

  • Type: String

  • Default: Defaults to the Task Queue that the Workflow was started with.

  • With ActivityStub

    GreetingActivities activities = Workflow.newActivityStub(GreetingActivities.class,
    ActivityOptions.newBuilder()
    // note that either StartToCloseTimeout or ScheduleToCloseTimeout are required when
    // setting Activity options.
    .setStartToCloseTimeout(Duration.ofSeconds(5))
    .setTaskQueue("yourTaskQueue")
    .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))
    .setTaskQueue("yourTaskQueue")
    .build()))
    .build();

See Task Queue

RetryOptions

To set Retry Options, 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();

setCancellationType

  • Type: ActivityCancellationType

  • Default: ActivityCancellationType.TRY_CANCEL

  • With ActivityStub

    private final GreetingActivities activities =
    Workflow.newActivityStub(
    GreetingActivities.class,
    ActivityOptions.newBuilder()
    .setCancellationType(ActivityCancellationType.WAIT_CANCELLATION_COMPLETED)
    .build());
  • With WorkflowImplementationOptions

    WorkflowImplementationOptions options =
    WorkflowImplementationOptions.newBuilder()
    .setActivityOptions(
    ImmutableMap.of(
    "EmailCustomerGreeting",
    ActivityOptions.newBuilder()
    .setCancellationType(ActivityCancellationType.WAIT_CANCELLATION_COMPLETED)
    .build()))
    .build();