Class Worker

java.lang.Object
io.temporal.worker.Worker
public final class Worker extends Object
Hosts activity, nexus and workflow implementations. Uses long poll to receive workflow, activity and nexus tasks and processes them in a correspondent thread pool.

  • Method Details

    • registerWorkflowImplementationTypes

      public void registerWorkflowImplementationTypes(Class<?>... workflowImplementationClasses)
      Registers workflow implementation classes with a worker. Can be called multiple times to add more types. A workflow implementation class must implement at least one interface with a method annotated with WorkflowMethod. By default, the short name of the interface is used as a workflow type that this worker supports.

      Implementations that share a worker must implement different interfaces as a workflow type is identified by the workflow interface, not by the implementation.

      Use DynamicWorkflow implementation to implement many workflow types dynamically. It can be useful for implementing DSL based workflows. Only a single type that implements DynamicWorkflow can be registered per worker.

      Throws:
      TypeAlreadyRegisteredException - if one of the workflow types is already registered

    • registerWorkflowImplementationTypes

      public void registerWorkflowImplementationTypes(WorkflowImplementationOptions options, Class<?>... workflowImplementationClasses)
      Registers workflow implementation classes with a worker. Can be called multiple times to add more types. A workflow implementation class must implement at least one interface with a method annotated with WorkflowMethod. By default, the short name of the interface is used as a workflow type that this worker supports.

      Implementations that share a worker must implement different interfaces as a workflow type is identified by the workflow interface, not by the implementation.

      Use DynamicWorkflow implementation to implement many workflow types dynamically. It can be useful for implementing DSL based workflows. Only a single type that implements DynamicWorkflow can be registered per worker.

      Throws:
      TypeAlreadyRegisteredException - if one of the workflow types is already registered

    • addWorkflowImplementationFactory

      @Deprecated public <R> void addWorkflowImplementationFactory(WorkflowImplementationOptions options, Class<R> workflowInterface, Functions.Func<R> factory)
      Deprecated.
      use registerWorkflowImplementationFactory(Class, Func, WorkflowImplementationOptions) instead
      Configures a factory to use when an instance of a workflow implementation is created. !IMPORTANT to provide newly created instances, each time factory is applied.

      Unless mocking a workflow execution use registerWorkflowImplementationTypes(Class[]).

      Type Parameters:
      R - type of the workflow object to create
      Parameters:
      workflowInterface - Workflow interface that this factory implements
      factory - factory that when called creates a new instance of the workflow implementation object.
      Throws:
      TypeAlreadyRegisteredException - if one of the workflow types is already registered

    • addWorkflowImplementationFactory

      @Deprecated public <R> void addWorkflowImplementationFactory(Class<R> workflowInterface, Functions.Func<R> factory)
      Deprecated.
      Use registerWorkflowImplementationFactory(Class, Func, WorkflowImplementationOptions) with WorkflowImplementationOptions.newBuilder().setFailWorkflowExceptionTypes(Throwable.class).build() as a 3rd parameter to preserve the unexpected behavior of this method.
      Or use registerWorkflowImplementationFactory(Class, Func) with an expected behavior - Workflow Execution is failed only when a TemporalFailure subtype is thrown.
      This method may behave differently from your expectations! This method makes any Throwable thrown from a Workflow code to fail the Workflow Execution.

      By default, only throwing TemporalFailure or an exception of class explicitly specified on WorkflowImplementationOptions.Builder.setFailWorkflowExceptionTypes(java.lang.Class<? extends java.lang.Throwable>...) fails Workflow Execution. Other exceptions fail Workflow Task instead of the whole Workflow Execution. It is designed so that an exception which is not expected by the user, doesn't fail the Workflow Execution. Which allows the user to fix Workflow implementation and then continue the execution from the point it got stuck.

      This method is misaligned with other workflow implementation registration methods in this aspect.

    • registerWorkflowImplementationFactory

      public <R> void registerWorkflowImplementationFactory(Class<R> workflowInterface, Functions.Func<R> factory, WorkflowImplementationOptions options)
      Configures a factory to use when an instance of a workflow implementation is created.

      The only valid use for this method is unit testing and mocking.
      An example of mocking a child workflow: 

      
   worker.addWorkflowImplementationFactory(ChildWorkflow.class, () -> {
     ChildWorkflow child = mock(ChildWorkflow.class);
     when(child.workflow(anyString(), anyString())).thenReturn("result1");
     return child;
   });

      Unless mocking a workflow execution use registerWorkflowImplementationTypes(Class[]).

      Workflow instantiation and Dependency Injection

      This method may look convenient to integrate with dependency injection frameworks and inject into workflow instances. Please note that Dependency Injection into Workflow instances is strongly discouraged. Dependency Injection into Workflow Instances is a direct way to cause changes that are incompatible with the persisted histories and cause NonDeterministicException.

      To provide an external configuration to a workflow in a deterministic way, use a Local Activity that returns configuration to the workflow. Dependency Injection into Activity instances is allowed. This way, the configuration is persisted into the history and maintained same during replay.

      Type Parameters:
      R - type of the workflow object to create
      Parameters:
      workflowInterface - Workflow interface that this factory implements
      factory - should create a new instance of the workflow implementation object every time it's called
      options - custom workflow implementation options for a worker
      Throws:
      TypeAlreadyRegisteredException - if one of the workflow types is already registered

    • registerWorkflowImplementationFactory

      public <R> void registerWorkflowImplementationFactory(Class<R> workflowInterface, Functions.Func1<EncodedValues,R> factory, WorkflowImplementationOptions options)

    • registerWorkflowImplementationFactory

      public <R> void registerWorkflowImplementationFactory(Class<R> workflowInterface, Functions.Func<R> factory)
      Configures a factory to use when an instance of a workflow implementation is created.

      The only valid use for this method is unit testing and mocking.
      An example of mocking a child workflow: 

      
   worker.addWorkflowImplementationFactory(ChildWorkflow.class, () -> {
     ChildWorkflow child = mock(ChildWorkflow.class);
     when(child.workflow(anyString(), anyString())).thenReturn("result1");
     return child;
   });

      Unless mocking a workflow execution use registerWorkflowImplementationTypes(Class[]).

      Workflow instantiation and Dependency Injection

      This method may look convenient to integrate with dependency injection frameworks and inject into workflow instances. Please note that Dependency Injection into Workflow instances is strongly discouraged. Dependency Injection into Workflow Instances is a direct way to cause changes that are incompatible with the persisted histories and cause NonDeterministicException.

      To provide an external configuration to a workflow in a deterministic way, use a Local Activity that returns configuration to the workflow. Dependency Injection into Activity instances is allowed. This way, the configuration is persisted into the history and maintained same during replay.

      Type Parameters:
      R - type of the workflow object to create
      Parameters:
      workflowInterface - Workflow interface that this factory implements
      factory - should create a new instance of the workflow implementation object every time it's called
      Throws:
      TypeAlreadyRegisteredException - if one of the workflow types is already registered

    • registerActivitiesImplementations

      public void registerActivitiesImplementations(Object... activityImplementations)
      Register activity implementation objects with a worker. An implementation object can implement one or more activity types.

      An activity implementation object must implement at least one interface annotated with ActivityInterface. Each method of the annotated interface becomes an activity type.

      Implementations that share a worker must implement different interfaces as an activity type is identified by the activity interface, not by the implementation.

      Use an implementation of DynamicActivity to register an object that can implement activity types dynamically. A single registration of DynamicActivity implementation per worker is allowed.

      Throws:
      TypeAlreadyRegisteredException - if one of the activity types is already registered

    • registerNexusServiceImplementation

      @Experimental public void registerNexusServiceImplementation(Object... nexusServiceImplementations)
      Register Nexus service implementation objects with a worker.

      A Nexus service object must be annotated with ServiceImpl.

      Throws:
      TypeAlreadyRegisteredException - if one of the services is already registered

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • replayWorkflowExecution

      public void replayWorkflowExecution(WorkflowExecutionHistory history) throws Exception
      This is a utility method to replay a workflow execution using this particular instance of a worker. This method is useful for troubleshooting workflows by running them in a debugger. The workflow implementation type must be already registered with this worker for this method to work.

      There is no need to call start() to be able to call this method
      The worker doesn't have to be registered on the same task queue as the execution in the history.
      This method shouldn't be a part of normal production usage. It's intended for testing and debugging only.

      Parameters:
      history - workflow execution history to replay
      Throws:
      Exception - if replay failed for any reason

    • replayWorkflowExecution

      public void replayWorkflowExecution(WorkflowExecutionHistory history) throws Exception
      This is a utility method to replay a workflow execution using this particular instance of a worker. This method is useful for troubleshooting workflows by running them in a debugger. The workflow implementation type must be already registered with this worker for this method to work.

      There is no need to call start() to be able to call this method
      The worker doesn't have to be registered on the same task queue as the execution in the history.
      This method shouldn't be a part of normal production usage. It's intended for testing and debugging only.

      Parameters:
      history - workflow execution history to replay
      Throws:
      Exception - if replay failed for any reason

    • replayWorkflowExecution

      public void replayWorkflowExecution(String jsonSerializedHistory) throws Exception
      This is a utility method to replay a workflow execution using this particular instance of a worker. This method is useful to troubleshoot workflows by running them in a debugger. To work the workflow implementation type must be registered with this worker. There is no need to call start() to be able to call this method.
      Parameters:
      jsonSerializedHistory - workflow execution history in JSON format to replay
      Throws:
      Exception - if replay failed for any reason

    • getTaskQueue

      public String getTaskQueue()

    • suspendPolling

      public void suspendPolling()

    • resumePolling

      public void resumePolling()

    • isSuspended

      public boolean isSuspended()

    • getWorkerOptions

      public WorkerOptions getWorkerOptions()
      Returns:
      The options used to create this worker.

    • reserveWorkflowExecutor

      @Nullable public WorkflowTaskDispatchHandle reserveWorkflowExecutor()

    • getWorkflowType

      public static String getWorkflowType(Class<?> workflowInterfaceClass)
      Name of the workflow type the interface defines. It is either the interface short name or value of WorkflowMethod.name() parameter.
      Parameters:
      workflowInterfaceClass - interface annotated with @WorkflowInterface