Package io.dapr.workflows.client

Class DaprWorkflowClient

java.lang.Object
io.dapr.workflows.client.DaprWorkflowClient
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
ObservationDaprWorkflowClient
public class DaprWorkflowClient extends Object implements AutoCloseable
Defines client operations for managing Dapr Workflow instances.

  • Constructor Details

    • DaprWorkflowClient

      public DaprWorkflowClient()
      Public constructor for DaprWorkflowClient. This layer constructs the GRPC Channel.

    • DaprWorkflowClient

      public DaprWorkflowClient(Properties properties)
      Public constructor for DaprWorkflowClient. This layer constructs the GRPC Channel.
      Parameters:
      properties - Properties for the GRPC Channel.

    • DaprWorkflowClient

      public DaprWorkflowClient(Properties properties, @Nullable io.opentelemetry.api.trace.Tracer tracer)
      Public constructor for DaprWorkflowClient. This layer constructs the GRPC Channel.

      When a Tracer is provided, scheduling a workflow emits a client span as a child of the caller's current OpenTelemetry context and propagates that trace context to the Dapr sidecar, so the workflow execution is recorded as part of the caller's trace.

      Parameters:
      properties - Properties for the GRPC Channel.
      tracer - OpenTelemetry Tracer used to emit and propagate trace context when scheduling workflows. May be null, in which case tracing is disabled and this constructor behaves exactly like DaprWorkflowClient(Properties).

    • DaprWorkflowClient

      protected DaprWorkflowClient(Properties properties, io.grpc.ClientInterceptor... additionalInterceptors)
      Protected constructor for DaprWorkflowClient that allows subclasses to inject additional gRPC ClientInterceptors onto the channel (e.g. for tracing). The ApiTokenClientInterceptor is always prepended before the additional ones.
      Parameters:
      properties - Properties for the GRPC Channel.
      additionalInterceptors - extra interceptors appended after the API-token interceptor.

  • Method Details

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(Class<T> clazz)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      clazz - Class extending Workflow to start an instance of.
      Returns:
      the randomly-generated instance ID for new Workflow instance.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(String name)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      name - Workflow name
      Returns:
      the randomly-generated instance ID for new Workflow instance.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(Class<T> clazz, Object input)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      clazz - Class extending Workflow to start an instance of.
      input - the input to pass to the scheduled orchestration instance. Must be serializable.
      Returns:
      the randomly-generated instance ID for new Workflow instance.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(String name, Object input)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      name - Workflow name
      input - the input to pass to the scheduled orchestration instance. Must be serializable.
      Returns:
      the randomly-generated instance ID for new Workflow instance.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(Class<T> clazz, Object input, String instanceId)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      clazz - Class extending Workflow to start an instance of.
      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.
      Throws:
      WorkflowInstanceAlreadyExistsException - if an active workflow with instanceId already exists.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(String name, Object input, String instanceId)
      Schedules a new workflow using DurableTask client.
      Type Parameters:
      T - any Workflow type
      Parameters:
      name - Workflow name
      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.
      Throws:
      WorkflowInstanceAlreadyExistsException - if an active workflow with instanceId already exists.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(Class<T> clazz, NewWorkflowOptions options)
      Schedules a new workflow with a specified set of options for execution.
      Type Parameters:
      T - any Workflow type
      Parameters:
      clazz - Class extending Workflow to start an instance of.
      options - the options for the new workflow, including input, instance ID, etc.
      Returns:
      the instanceId parameter value.
      Throws:
      WorkflowInstanceAlreadyExistsException - if an active workflow with the requested instance ID already exists.

    • scheduleNewWorkflow

      public <T extends Workflow> String scheduleNewWorkflow(String name, NewWorkflowOptions options)
      Schedules a new workflow with a specified set of options for execution.
      Type Parameters:
      T - any Workflow type
      Parameters:
      name - name of the workflow to schedule
      options - the options for the new workflow, including input, instance ID, etc.
      Returns:
      the instanceId parameter value.
      Throws:
      WorkflowInstanceAlreadyExistsException - if an active workflow with the requested instance ID already exists.

    • suspendWorkflow

      public void suspendWorkflow(String workflowInstanceId, @Nullable String reason)
      Suspend the workflow associated with the provided instance id.
      Parameters:
      workflowInstanceId - Workflow instance id to suspend.
      reason - reason for suspending the workflow instance.

    • suspendWorkflow

      public void suspendWorkflow(String workflowInstanceId, @Nullable String reason, @Nullable String appId)
      Suspend the workflow associated with the provided instance id, owned by another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      workflowInstanceId - Workflow instance id to suspend.
      reason - reason for suspending the workflow instance.
      appId - ID of the app that owns the workflow instance. May be null to target the local app.

    • resumeWorkflow

      public void resumeWorkflow(String workflowInstanceId, @Nullable String reason)
      Resume the workflow associated with the provided instance id.
      Parameters:
      workflowInstanceId - Workflow instance id to resume.
      reason - reason for resuming the workflow instance.

    • resumeWorkflow

      public void resumeWorkflow(String workflowInstanceId, @Nullable String reason, @Nullable String appId)
      Resume the workflow associated with the provided instance id, owned by another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      workflowInstanceId - Workflow instance id to resume.
      reason - reason for resuming the workflow instance.
      appId - ID of the app that owns the workflow instance. May be null to target the local app.

    • terminateWorkflow

      public void terminateWorkflow(String workflowInstanceId, @Nullable Object output)
      Terminates the workflow associated with the provided instance id.
      Parameters:
      workflowInstanceId - Workflow instance id to terminate.
      output - the optional output to set for the terminated orchestration instance.

    • terminateWorkflow

      public void terminateWorkflow(String workflowInstanceId, @Nullable Object output, @Nullable String appId)
      Terminates the workflow associated with the provided instance id, owned by another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      workflowInstanceId - Workflow instance id to terminate.
      output - the optional output to set for the terminated orchestration instance.
      appId - ID of the app that owns the workflow instance. May be null to target the local app.

    • getInstanceState

      @Nullable @Deprecated(forRemoval=true) public WorkflowInstanceStatus getInstanceState(String instanceId, boolean getInputsAndOutputs)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getWorkflowState(String, boolean) instead.
      Fetches workflow instance metadata from the configured durable store.
      Parameters:
      instanceId - the unique ID of the workflow instance to fetch
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      a metadata record that describes the workflow instance and it execution status, or a default instance

    • getWorkflowState

      @Nullable public WorkflowState getWorkflowState(String instanceId, boolean getInputsAndOutputs)
      Fetches workflow instance metadata from the configured durable store.
      Parameters:
      instanceId - the unique ID of the workflow instance to fetch
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      a metadata record that describes the workflow instance and it execution status, or a default instance

    • getWorkflowState

      @Nullable public WorkflowState getWorkflowState(String instanceId, boolean getInputsAndOutputs, @Nullable String appId)
      Fetches workflow instance metadata from the durable store of another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      instanceId - the unique ID of the workflow instance to fetch
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      appId - ID of the app that owns the workflow instance. May be null to target the local app.
      Returns:
      a metadata record that describes the workflow instance and its execution status, or a default instance when no such instance is found, matching getWorkflowState(String, boolean). Null only when the underlying client returns no metadata at all.

    • waitForInstanceStart

      @Deprecated(forRemoval=true) @Nullable public WorkflowInstanceStatus waitForInstanceStart(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use waitForWorkflowStart(String, Duration, boolean) instead.
      Waits for an workflow to start running and returns an WorkflowInstanceStatus object that contains metadata about the started instance and optionally its input, output, and custom status payloads.

      A "started" workflow instance is any instance not in the Pending state.

      If an workflow instance is already running when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to start
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not started within the specified amount of time

    • waitForWorkflowStart

      @Nullable public WorkflowState waitForWorkflowStart(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Waits for a workflow to start running and returns an WorkflowState object that contains metadata about the started instance and optionally its input, output, and custom status payloads.

      A "started" workflow instance is any instance not in the Pending state.

      If an workflow instance is already running when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to start
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not started within the specified amount of time

    • waitForWorkflowStart

      @Nullable public WorkflowState waitForWorkflowStart(String instanceId, Duration timeout, boolean getInputsAndOutputs, @Nullable String appId) throws TimeoutException
      Waits for a workflow owned by another app to start running.

      See waitForWorkflowStart(String, Duration, boolean) for the wait semantics. Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to start
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      appId - ID of the app that owns the workflow instance. May be null to target the local app.
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not started within the specified amount of time

    • waitForInstanceCompletion

      @Nullable @Deprecated(forRemoval=true) public WorkflowInstanceStatus waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use waitForWorkflowCompletion(String, Duration, boolean) instead.
      Waits for an workflow to complete and returns an WorkflowInstanceStatus object that contains metadata about the completed instance.

      A "completed" workflow instance is any instance in one of the terminal states. For example, the Completed, Failed, or Terminated states.

      Workflows are long-running and could take hours, days, or months before completing. Workflows 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 workflow instance is already complete when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to complete
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not completed within the specified amount of time

    • waitForWorkflowCompletion

      @Nullable public WorkflowState waitForWorkflowCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs) throws TimeoutException
      Waits for an workflow to complete and returns an WorkflowState object that contains metadata about the completed instance.

      A "completed" workflow instance is any instance in one of the terminal states. For example, the Completed, Failed, or Terminated states.

      Workflows are long-running and could take hours, days, or months before completing. Workflows 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 workflow instance is already complete when this method is called, the method will return immediately.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to complete
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not completed within the specified amount of time

    • waitForWorkflowCompletion

      @Nullable public WorkflowState waitForWorkflowCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs, @Nullable String appId) throws TimeoutException
      Waits for a workflow owned by another app to complete.

      See waitForWorkflowCompletion(String, Duration, boolean) for the wait semantics. Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      instanceId - the unique ID of the workflow instance to wait for
      timeout - the amount of time to wait for the workflow instance to complete
      getInputsAndOutputs - true to fetch the workflow instance's inputs, outputs, and custom status, or false to omit them
      appId - ID of the app that owns the workflow instance. May be null to target the local app.
      Returns:
      the workflow instance metadata or null if no such instance is found
      Throws:
      TimeoutException - when the workflow instance is not completed within the specified amount of time

    • raiseEvent

      public void raiseEvent(String workflowInstanceId, String eventName, Object eventPayload)
      Sends an event notification message to awaiting workflow instance.
      Parameters:
      workflowInstanceId - The ID of the workflow instance that will handle the event.
      eventName - The name of the event. Event names are case-insensitive.
      eventPayload - The serializable data payload to include with the event.

    • raiseEvent

      public void raiseEvent(String workflowInstanceId, String eventName, Object eventPayload, @Nullable String appId)
      Sends an event notification message to a waiting workflow instance owned by another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      workflowInstanceId - The ID of the workflow instance that will handle the event.
      eventName - The name of the event. Event names are case-insensitive.
      eventPayload - The serializable data payload to include with the event.
      appId - ID of the app that owns the workflow instance. May be null to target the local app.

    • purgeInstance

      @Deprecated(forRemoval=true) public boolean purgeInstance(String workflowInstanceId)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use purgeWorkflow(String) instead.
      Purges workflow instance state from the workflow state store.
      Parameters:
      workflowInstanceId - The unique ID of the workflow instance to purge.
      Returns:
      Return true if the workflow state was found and purged successfully otherwise false.

    • listInstanceIds

      public WorkflowInstancePage listInstanceIds()
      Lists workflow instance IDs. Returns the first page with no size limit.
      Returns:
      a page of workflow instance IDs

    • listInstanceIds

      public WorkflowInstancePage listInstanceIds(@Nullable String continuationToken, @Nullable Integer pageSize)
      Lists workflow instance IDs with pagination.
      Parameters:
      continuationToken - the continuation token from a previous call, or null for the first page
      pageSize - the maximum number of instance IDs to return, or null for no limit; must be greater than zero when set
      Returns:
      a page of workflow instance IDs and an optional continuation token for the next page

    • getInstanceHistory

      public List<WorkflowHistoryEvent> getInstanceHistory(String instanceId)
      Gets the full execution history of a workflow instance.
      Parameters:
      instanceId - the unique ID of the workflow instance to get history for
      Returns:
      the list of history events for the workflow instance

    • rerunWorkflowFromEvent

      public String rerunWorkflowFromEvent(String sourceInstanceId, int eventId)
      Reruns a workflow from a history event, creating a new workflow instance.
      Parameters:
      sourceInstanceId - the ID of the source workflow instance to rerun from
      eventId - the history event ID to rerun from; must not be negative
      Returns:
      the instance ID of the new workflow instance
      Throws:
      IllegalArgumentException - if sourceInstanceId is null or empty, or eventId is negative

    • rerunWorkflowFromEvent

      public String rerunWorkflowFromEvent(String sourceInstanceId, int eventId, @Nullable RerunWorkflowFromEventOptions options)
      Reruns a workflow from a history event with options, creating a new workflow instance.
      Parameters:
      sourceInstanceId - the ID of the source workflow instance to rerun from
      eventId - the history event ID to rerun from; must not be negative
      options - optional rerun configuration; may be null
      Returns:
      the instance ID of the new workflow instance
      Throws:
      IllegalArgumentException - if sourceInstanceId is null or empty, if eventId is negative, or if input is set on options without overwriteInput being true

    • purgeWorkflow

      public boolean purgeWorkflow(String workflowInstanceId, @Nullable String appId)
      Purges workflow instance state from the workflow state store of another app.

      Permission to operate on workflows owned by another app is governed by the target app's WorkflowAccessPolicy.

      Requires a Dapr runtime with cross-app workflow support; against an older runtime the target app ID is ignored and the operation applies to the local app instead.

      Parameters:
      workflowInstanceId - The unique ID of the workflow instance to purge.
      appId - ID of the app that owns the workflow instance. May be null to target the local app.
      Returns:
      Return true if the workflow state was found and purged successfully otherwise false.

    • purgeWorkflow

      public boolean purgeWorkflow(String workflowInstanceId)
      Purges workflow instance state from the workflow state store.
      Parameters:
      workflowInstanceId - The unique ID of the workflow instance to purge.
      Returns:
      Return true if the workflow state was found and purged successfully otherwise false.

    • close

      public void close() throws InterruptedException
      Closes the inner DurableTask client and shutdown the GRPC channel.
      Specified by:
      close in interface AutoCloseable
      Throws:
      InterruptedException