Package io.dapr.workflows.client

# Class DaprWorkflowClient

java.lang.Object
io.dapr.workflows.client.DaprWorkflowClient

All Implemented Interfaces:
  `AutoCloseable`

public class DaprWorkflowClient extends Object implements AutoCloseable
Defines client operations for managing Dapr Workflow instances.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `DaprWorkflowClient()`
  Public constructor for DaprWorkflowClient.
  ``
  `DaprWorkflowClient(io.dapr.config.Properties properties)`
  Public constructor for DaprWorkflowClient.
  `protected`
  `DaprWorkflowClient(io.dapr.config.Properties properties, io.grpc.ClientInterceptor... additionalInterceptors)`
  Protected constructor for DaprWorkflowClient that allows subclasses to inject additional gRPC `ClientInterceptor`s onto the channel (e.g.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes the inner DurableTask client and shutdown the GRPC channel.
  `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.
  `WorkflowState`
  `getWorkflowState(String instanceId, boolean getInputsAndOutputs)`
  Fetches workflow instance metadata from the configured durable store.
  `boolean`
  `purgeInstance(String workflowInstanceId)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `purgeWorkflow(String)` instead.
  `boolean`
  `purgeWorkflow(String workflowInstanceId)`
  Purges workflow instance state from the workflow state store.
  `void`
  `raiseEvent(String workflowInstanceId, String eventName, Object eventPayload)`
  Sends an event notification message to awaiting workflow instance.
  `void`
  `resumeWorkflow(String workflowInstanceId, String reason)`
  Resume the workflow associated with the provided instance id.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(Class<T> clazz)`
  Schedules a new workflow using DurableTask client.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(Class<T> clazz, NewWorkflowOptions options)`
  Schedules a new workflow with a specified set of options for execution.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(Class<T> clazz, Object input)`
  Schedules a new workflow using DurableTask client.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(Class<T> clazz, Object input, String instanceId)`
  Schedules a new workflow using DurableTask client.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(String name)`
  Schedules a new workflow using DurableTask client.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(String name, NewWorkflowOptions options)`
  Schedules a new workflow with a specified set of options for execution.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(String name, Object input)`
  Schedules a new workflow using DurableTask client.
  `<T extends Workflow>
  String`
  `scheduleNewWorkflow(String name, Object input, String instanceId)`
  Schedules a new workflow using DurableTask client.
  `void`
  `suspendWorkflow(String workflowInstanceId, String reason)`
  Suspend the workflow associated with the provided instance id.
  `void`
  `terminateWorkflow(String workflowInstanceId, Object output)`
  Terminates the workflow associated with the provided instance id.
  `WorkflowInstanceStatus`
  `waitForInstanceCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `waitForWorkflowCompletion(String, Duration, boolean)` instead.
  `WorkflowInstanceStatus`
  `waitForInstanceStart(String instanceId, Duration timeout, boolean getInputsAndOutputs)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `waitForWorkflowStart(String, Duration, boolean)` instead.
  `WorkflowState`
  `waitForWorkflowCompletion(String instanceId, Duration timeout, boolean getInputsAndOutputs)`
  Waits for an workflow to complete and returns an `WorkflowState` object that contains metadata about the completed instance.
  `WorkflowState`
  `waitForWorkflowStart(String instanceId, Duration timeout, boolean getInputsAndOutputs)`
  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.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DaprWorkflowClient

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

  - ### DaprWorkflowClient

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

  - ### DaprWorkflowClient

    protected DaprWorkflowClient(io.dapr.config.Properties properties, io.grpc.ClientInterceptor... additionalInterceptors)
    Protected constructor for DaprWorkflowClient that allows subclasses to inject additional gRPC `ClientInterceptor`s 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.

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

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

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

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

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

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

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

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

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

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

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

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