Interface WorkflowStub

public interface WorkflowStub
WorkflowStub is a client side stub to a single workflow instance. It can be used to start, signal, query, update, wait for completion and cancel a workflow execution. Created through WorkflowClient.newUntypedWorkflowStub(String, WorkflowOptions) or WorkflowClient.newUntypedWorkflowStub(WorkflowTargetOptions, Optional).

  • Method Details

    • fromTyped

      static <T> WorkflowStub fromTyped(T typed)
      Extracts untyped WorkflowStub from a typed workflow stub created through WorkflowClient.newWorkflowStub(Class, WorkflowOptions).
      Type Parameters:
      T - type of the workflow stub interface
      Parameters:
      typed - typed workflow stub
      Returns:
      untyped workflow stub for the same workflow instance

    • signal

      void signal(String signalName, Object... args)
      Synchronously signals a workflow by invoking its signal handler. Usually a signal handler is a method annotated with SignalMethod.
      Parameters:
      signalName - name of the signal handler. Usually it is a method name.
      args - signal method arguments
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or completed and can't be signalled
      WorkflowServiceException - for all other failures including networking and service availability issues

    • update

      <R> R update(String updateName, Class<R> resultClass, Object... args)
      Synchronously update a workflow execution by invoking its update handler. Usually a update handler is a method annotated with UpdateMethod.
      Type Parameters:
      R - type of the update return value
      Parameters:
      updateName - name of the update handler. Usually it is a method name.
      resultClass - class of the update return value
      args - update method arguments
      Returns:
      update result
      Throws:
      WorkflowUpdateException - if the update is rejected or failed during it's execution by the workflow.
      WorkflowNotFoundException - if the workflow execution doesn't exist or is completed.
      WorkflowServiceException - for all other failures including networking and service availability issues.

    • startUpdate

      <R> WorkflowUpdateHandle<R> startUpdate(String updateName, WorkflowUpdateStage waitForStage, Class<R> resultClass, Object... args)
      Asynchronously update a workflow execution by invoking its update handler and returning a handle to the update request. Usually an update handler is a method annotated with UpdateMethod.
      Type Parameters:
      R - type of the update return value
      Parameters:
      updateName - name of the update handler. Usually it is a method name.
      waitForStage - stage to wait for before returning the update handle. Admitted is not allowed as a value.
      resultClass - class of the update return value
      args - update method arguments
      Returns:
      update handle that can be used to get the result of the update.
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or completed.
      WorkflowServiceException - for all other failures including networking and service availability issues.

    • startUpdate

      <R> WorkflowUpdateHandle<R> startUpdate(UpdateOptions<R> options, Object... args)
      Asynchronously update a workflow execution by invoking its update handler and returning a handle to the update request. If WorkflowUpdateStage.COMPLETED is specified, in the options, the handle will not be returned until the update is completed.
      Parameters:
      options - options that will be used to configure and start a new update request.
      args - update method arguments
      Returns:
      update handle that can be used to get the result of the update.
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or completed.
      WorkflowServiceException - for all other failures including networking and service availability issues.

    • getUpdateHandle

      <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass)
      Get an update handle to a previously started update request. Getting an update handle does not guarantee the update ID exists.
      Type Parameters:
      R - type of the update return value.
      Parameters:
      updateId - the identifier for the requested update.
      resultClass - class of the update return value.
      Returns:
      update handle that can be used to get the result of the update.

    • getUpdateHandle

      <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass, Type resultType)
      Get an update handle to a previously started update request. Getting an update handle does not guarantee the update ID exists.
      Type Parameters:
      R - type of the update return value.
      Parameters:
      updateId - is an application-layer identifier for the requested update. It must be unique within the scope of a workflow execution.
      resultClass - class of the update return value.
      resultType - type of the update return value. Differs from resultClass for generic types.
      Returns:
      update handle that can be used to get the result of the update.

    • start

      io.temporal.api.common.v1.WorkflowExecution start(Object... args)

    • startUpdateWithStart

      <R> WorkflowUpdateHandle<R> startUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs)
      Asynchronously update a workflow execution by invoking its update handler, and start the workflow according to the option's WorkflowIdConflictPolicy. It returns a handle to the update request. If WorkflowUpdateStage.COMPLETED is specified, in the options, the handle will not be returned until the update is completed.
      Type Parameters:
      R - type of the update workflow result
      Parameters:
      updateOptions - options that will be used to configure and start a new update request
      updateArgs - update method arguments
      startArgs - workflow start arguments
      Returns:
      WorkflowUpdateHandle that can be used to get the result of the update

    • executeUpdateWithStart

      <R> R executeUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs)
      Synchronously update a workflow execution by invoking its update handler, and start the workflow according to the option's WorkflowIdConflictPolicy. It returns the update result.
      Type Parameters:
      R - type of the update workflow result
      Parameters:
      updateOptions - options that will be used to configure and start a new update request
      updateArgs - update method arguments
      startArgs - workflow start arguments
      Returns:
      update result

    • signalWithStart

      io.temporal.api.common.v1.WorkflowExecution signalWithStart(String signalName, Object[] signalArgs, Object[] startArgs)
      Sends a signal to a workflow, starting the workflow if it is not already running.
      Parameters:
      signalName - name of the signal handler. Usually it is a method name.
      signalArgs - signal method arguments
      startArgs - workflow start arguments
      Returns:
      workflow execution

    • getWorkflowType

      Optional<String> getWorkflowType()
      Returns:
      workflow type name if it was provided when the stub was created.

    • getExecution

      @Nullable io.temporal.api.common.v1.WorkflowExecution getExecution()
      Returns:
      current workflow execution. Returns null if the workflow has not been started yet.

    • getResult

      <R> R getResult(Class<R> resultClass)
      Returns workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.
      Type Parameters:
      R - type of the workflow return value
      Parameters:
      resultClass - class of the workflow return value
      Returns:
      workflow return value
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowException - if workflow failed with an exception
      WorkflowFailedException - if workflow failed. Throwable.getCause() will be TimeoutFailure, TerminatedFailure, CanceledFailure if the workflow execution timed out, was cancelled or terminated. Or the original TemporalFailure from the workflow that caused the failure otherwise.
      WorkflowServiceException - for all other failures including networking and service availability issues.

    • getResult

      <R> R getResult(Class<R> resultClass, Type resultType)
      Returns workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.
      Type Parameters:
      R - type of the workflow return value
      Parameters:
      resultClass - class of the workflow return value
      resultType - type of the workflow return value. Differs from resultClass for generic types.
      Returns:
      workflow return value
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowException - if workflow failed with an exception
      WorkflowFailedException - if workflow failed. Throwable.getCause() will be TimeoutFailure, TerminatedFailure, CanceledFailure if the workflow execution timed out, was cancelled or terminated. Or the original TemporalFailure from the workflow that caused the failure otherwise.
      WorkflowServiceException - for all other failures including networking and service availability issues

    • getResult

      <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass) throws TimeoutException
      Returns workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.
      Type Parameters:
      R - type of the workflow return value
      Parameters:
      timeout - maximum time to wait
      unit - unit of timeout
      resultClass - class of the workflow return value
      Returns:
      workflow return value
      Throws:
      TimeoutException - if workflow is not completed after the timeout time
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowException - if workflow failed with an exception
      WorkflowFailedException - if workflow failed. Throwable.getCause() will be TimeoutFailure, TerminatedFailure, CanceledFailure if the workflow execution timed out, was cancelled or terminated. Or the original TemporalFailure from the workflow that caused the failure otherwise.
      WorkflowServiceException - for all other failures including networking and service availability issues

    • getResult

      <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType) throws TimeoutException
      Returns workflow result potentially waiting for workflow to complete. Behind the scene this call is polling Temporal Server waiting for workflow completion.
      Type Parameters:
      R - type of the workflow return value
      Parameters:
      timeout - maximum time to wait
      unit - unit of timeout
      resultClass - class of the workflow return value
      resultType - type of the workflow return value. Differs from resultClass for generic
      Returns:
      workflow return value
      Throws:
      TimeoutException - if workflow is not completed after the timeout time
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowException - if workflow failed with an exception
      WorkflowFailedException - if workflow failed. Throwable.getCause() will be TimeoutFailure, TerminatedFailure, CanceledFailure if the workflow execution timed out, was cancelled or terminated. Or the original TemporalFailure from the workflow that caused the failure otherwise.
      WorkflowServiceException - for all other failures including networking and service availability issues

    • getResultAsync

      <R> CompletableFuture<R> getResultAsync(Class<R> resultClass)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete. Behind the scenes this call performs long polls the Temporal Server waiting for workflow completion.

      See getResult(Class) as a sync version of this method for detailed information about exceptions that may be thrown from CompletableFuture.get() wrapped by ExecutionException.

      Type Parameters:
      R - type of the workflow return value
      Parameters:
      resultClass - class of the workflow return value
      Returns:
      future completed with workflow return value or an exception

    • getResultAsync

      <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, Type resultType)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.

      See getResult(Class, Type) as a sync version of this method for detailed information about exceptions that may be thrown from CompletableFuture.get() wrapped by ExecutionException.

      Type Parameters:
      R - type of the workflow return value
      Parameters:
      resultClass - class of the workflow return value
      resultType - type of the workflow return value. Differs from resultClass for generic types.
      Returns:
      future completed with workflow return value or an exception

    • getResultAsync

      <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.

      See getResult(long, TimeUnit, Class) as a sync version of this method for detailed information about exceptions that may be thrown from CompletableFuture.get() wrapped by ExecutionException.

      Type Parameters:
      R - type of the workflow return value
      Parameters:
      timeout - maximum time to wait and perform a background long poll
      unit - unit of timeout
      resultClass - class of the workflow return value
      Returns:
      future completed with workflow return value or an exception

    • getResultAsync

      <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete. Behind the scene this call performs long poll on Temporal service waiting for workflow completion notification.

      See getResult(long, TimeUnit, Class, Type) as a sync version of this method for detailed information about exceptions that may be thrown from CompletableFuture.get() wrapped by ExecutionException.

      Type Parameters:
      R - type of the workflow return value
      Parameters:
      timeout - maximum time to wait and perform a background long poll
      unit - unit of timeout
      resultClass - class of the workflow return value
      resultType - type of the workflow return value. Differs from resultClass for generic types.
      Returns:
      future completed with workflow return value or an exception

    • query

      <R> R query(String queryType, Class<R> resultClass, Object... args)
      Synchronously queries workflow by invoking its query handler. Usually a query handler is a method annotated with QueryMethod.
      Type Parameters:
      R - type of the query result
      Parameters:
      queryType - name of the query handler. Usually it is a method name.
      resultClass - class of the query result type
      args - optional query arguments
      Returns:
      query result
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowQueryException - if the query failed during it's execution by the workflow worker
      WorkflowQueryRejectedException - if query is rejected by the server
      WorkflowServiceException - for all other failures including networking and service availability issues
      See Also:

    • query

      <R> R query(String queryType, Class<R> resultClass, Type resultType, Object... args)
      Synchronously queries workflow by invoking its query handler. Usually a query handler is a method annotated with QueryMethod.
      Type Parameters:
      R - type of the query result
      Parameters:
      queryType - name of the query handler. Usually it is a method name.
      resultClass - class of the query result type
      resultType - type of the workflow return value. Differs from resultClass for generic types.
      args - optional query arguments
      Returns:
      query result
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowQueryException - if the query failed during it's execution by the workflow worker or was rejected on any stage
      WorkflowServiceException - for all other failures including networking and service availability issues
      See Also:

    • cancel

      void cancel()
      Request cancellation of a workflow execution.

      Cancellation cancels CancellationScope that wraps the main workflow method. Note that workflow can take long time to get canceled or even completely ignore the cancellation request.

      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or is already completed
      WorkflowServiceException - for all other failures including networking and service availability issues

    • cancel

      void cancel(@Nullable String reason)
      Request cancellation of a workflow execution with a reason.

      Cancellation cancels CancellationScope that wraps the main workflow method. Note that workflow can take long time to get canceled or even completely ignore the cancellation request.

      Parameters:
      reason - optional reason for the cancellation request
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or is already completed
      WorkflowServiceException - for all other failures including networking and service availability issues

    • terminate

      void terminate(@Nullable String reason, Object... details)
      Terminates a workflow execution.

      Termination is a hard stop of a workflow execution which doesn't give workflow code any chance to perform cleanup.

      Parameters:
      reason - optional reason for the termination request
      details - additional details about the termination reason
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist or is already completed
      WorkflowServiceException - for all other failures including networking and service availability issues

    • describe

      WorkflowExecutionDescription describe()
      Get the current description of this workflow.
      Returns:
      the current description of this workflow
      Throws:
      WorkflowNotFoundException - if the workflow execution doesn't exist
      WorkflowServiceException - for all other failures including networking and service availability issues

    • getOptions

      Optional<WorkflowOptions> getOptions()
      Returns:
      workflow options if they were provided when the stub was created.

    • newInstance

      WorkflowStub newInstance(WorkflowOptions options)
      Creates a new stub that can be used to start a new run of the same workflow type with the same options.
      Parameters:
      options - new options to use for the stub