Package io.temporal.client

Interface WorkflowStub

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void cancel()
      Request cancellation of a workflow execution.
      void cancel​(java.lang.String reason)
      Request cancellation of a workflow execution with a reason.
      WorkflowExecutionDescription describe()
      Get the current description of this workflow.
      <R> R executeUpdateWithStart​(UpdateOptions<R> updateOptions, java.lang.Object[] updateArgs, java.lang.Object[] startArgs)
      Synchronously update a workflow execution by invoking its update handler, and start the workflow according to the option's WorkflowIdConflictPolicy.
      static <T> WorkflowStub fromTyped​(T typed)
      Extracts untyped WorkflowStub from a typed workflow stub created through WorkflowClient.newWorkflowStub(Class, WorkflowOptions).
      io.temporal.api.common.v1.WorkflowExecution getExecution()  
      java.util.Optional<WorkflowOptions> getOptions()  
      <R> R getResult​(long timeout, java.util.concurrent.TimeUnit unit, java.lang.Class<R> resultClass)
      Returns workflow result potentially waiting for workflow to complete.
      <R> R getResult​(long timeout, java.util.concurrent.TimeUnit unit, java.lang.Class<R> resultClass, java.lang.reflect.Type resultType)
      Returns workflow result potentially waiting for workflow to complete.
      <R> R getResult​(java.lang.Class<R> resultClass)
      Returns workflow result potentially waiting for workflow to complete.
      <R> R getResult​(java.lang.Class<R> resultClass, java.lang.reflect.Type resultType)
      Returns workflow result potentially waiting for workflow to complete.
      <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(long timeout, java.util.concurrent.TimeUnit unit, java.lang.Class<R> resultClass)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete.
      <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(long timeout, java.util.concurrent.TimeUnit unit, java.lang.Class<R> resultClass, java.lang.reflect.Type resultType)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete.
      <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(java.lang.Class<R> resultClass)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete.
      <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(java.lang.Class<R> resultClass, java.lang.reflect.Type resultType)
      Returns a CompletableFuture with the workflow result potentially waiting for workflow to complete.
      <R> WorkflowUpdateHandle<R> getUpdateHandle​(java.lang.String updateId, java.lang.Class<R> resultClass)
      Get an update handle to a previously started update request.
      <R> WorkflowUpdateHandle<R> getUpdateHandle​(java.lang.String updateId, java.lang.Class<R> resultClass, java.lang.reflect.Type resultType)
      Get an update handle to a previously started update request.
      java.util.Optional<java.lang.String> getWorkflowType()  
      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.
      <R> R query​(java.lang.String queryType, java.lang.Class<R> resultClass, java.lang.Object... args)
      Synchronously queries workflow by invoking its query handler.
      <R> R query​(java.lang.String queryType, java.lang.Class<R> resultClass, java.lang.reflect.Type resultType, java.lang.Object... args)
      Synchronously queries workflow by invoking its query handler.
      void signal​(java.lang.String signalName, java.lang.Object... args)
      Synchronously signals a workflow by invoking its signal handler.
      io.temporal.api.common.v1.WorkflowExecution signalWithStart​(java.lang.String signalName, java.lang.Object[] signalArgs, java.lang.Object[] startArgs)
      Sends a signal to a workflow, starting the workflow if it is not already running.
      io.temporal.api.common.v1.WorkflowExecution start​(java.lang.Object... args)  
      <R> WorkflowUpdateHandle<R> startUpdate​(UpdateOptions<R> options, java.lang.Object... args)
      Asynchronously update a workflow execution by invoking its update handler and returning a handle to the update request.
      <R> WorkflowUpdateHandle<R> startUpdate​(java.lang.String updateName, WorkflowUpdateStage waitForStage, java.lang.Class<R> resultClass, java.lang.Object... args)
      Asynchronously update a workflow execution by invoking its update handler and returning a handle to the update request.
      <R> WorkflowUpdateHandle<R> startUpdateWithStart​(UpdateOptions<R> updateOptions, java.lang.Object[] updateArgs, java.lang.Object[] startArgs)
      Asynchronously update a workflow execution by invoking its update handler, and start the workflow according to the option's WorkflowIdConflictPolicy.
      void terminate​(java.lang.String reason, java.lang.Object... details)
      Terminates a workflow execution.
      <R> R update​(java.lang.String updateName, java.lang.Class<R> resultClass, java.lang.Object... args)
      Synchronously update a workflow execution by invoking its update handler.

    • Method Detail

      • 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​(java.lang.String signalName,
            java.lang.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​(java.lang.String updateName,
             java.lang.Class<R> resultClass,
             java.lang.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​(java.lang.String updateName,
                                        WorkflowUpdateStage waitForStage,
                                        java.lang.Class<R> resultClass,
                                        java.lang.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,
                                        java.lang.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​(java.lang.String updateId,
                                            java.lang.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​(java.lang.String updateId,
                                            java.lang.Class<R> resultClass,
                                            java.lang.reflect.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​(java.lang.Object... args)

      • startUpdateWithStart

        <R> WorkflowUpdateHandle<R> startUpdateWithStart​(UpdateOptions<R> updateOptions,
                                                 java.lang.Object[] updateArgs,
                                                 java.lang.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,
                             java.lang.Object[] updateArgs,
                             java.lang.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​(java.lang.String signalName,
                                                            java.lang.Object[] signalArgs,
                                                            java.lang.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

        java.util.Optional<java.lang.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​(java.lang.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​(java.lang.Class<R> resultClass,
                java.lang.reflect.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,
                java.util.concurrent.TimeUnit unit,
                java.lang.Class<R> resultClass)
         throws java.util.concurrent.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:
        java.util.concurrent.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,
                java.util.concurrent.TimeUnit unit,
                java.lang.Class<R> resultClass,
                java.lang.reflect.Type resultType)
         throws java.util.concurrent.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:
        java.util.concurrent.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> java.util.concurrent.CompletableFuture<R> getResultAsync​(java.lang.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.
        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
        See Also:
        as a sync version of this method for detailed information about exceptions that may be thrown from wrapped by

      • getResultAsync

        <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(java.lang.Class<R> resultClass,
                                                             java.lang.reflect.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.
        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
        See Also:
        as a sync version of this method for detailed information about exceptions that may be thrown from wrapped by

      • getResultAsync

        <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(long timeout,
                                                             java.util.concurrent.TimeUnit unit,
                                                             java.lang.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.
        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
        See Also:
        as a sync version of this method for detailed information about exceptions that may be thrown from wrapped by

      • getResultAsync

        <R> java.util.concurrent.CompletableFuture<R> getResultAsync​(long timeout,
                                                             java.util.concurrent.TimeUnit unit,
                                                             java.lang.Class<R> resultClass,
                                                             java.lang.reflect.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.
        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
        See Also:
        as a sync version of this method for detailed information about exceptions that may be thrown from wrapped by

      • query

        <R> R query​(java.lang.String queryType,
            java.lang.Class<R> resultClass,
            java.lang.reflect.Type resultType,
            java.lang.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:
        WorkflowClientOptions.Builder.setQueryRejectCondition(QueryRejectCondition)

      • 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
            java.lang.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
               java.lang.String reason,
               java.lang.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

      • getOptions

        java.util.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