Interface WorkerPlugin

All Known Implementing Classes:
SimplePlugin
@Experimental public interface WorkerPlugin
Plugin interface for customizing Temporal worker configuration and lifecycle.

Plugins that also implement WorkflowClientPlugin are automatically propagated from the client to workers created from that client.

Example implementation: 


 public class MetricsPlugin extends SimplePlugin {
     private final MetricsRegistry registry;

     public MetricsPlugin(MetricsRegistry registry) {
         super("my-org.metrics");
         this.registry = registry;
     }

     @Override
     public void configureWorkerFactory(WorkerFactoryOptions.Builder builder) {
         builder.setWorkerInterceptors(new MetricsWorkerInterceptor(registry));
     }

     @Override
     public void startWorkerFactory(WorkerFactory factory, Consumer<WorkerFactory> next) {
         registry.recordWorkerStart();
         try {
             next.accept(factory);
         } finally {
             registry.recordWorkerStop();
         }
     }
 }
See Also:

  • Method Details

    • getName

      @Nonnull String getName()
      Returns a unique name for this plugin. Used for logging and duplicate detection. Recommended format: "organization.plugin-name" (e.g., "io.temporal.tracing")
      Returns:
      fully qualified plugin name

    • configureWorkerFactory

      void configureWorkerFactory(@Nonnull WorkerFactoryOptions.Builder builder)
      Allows the plugin to modify worker factory options before the factory is created. Called during configuration phase in forward (registration) order.
      Parameters:
      builder - the options builder to modify

    • configureWorker

      void configureWorker(@Nonnull String taskQueue, @Nonnull WorkerOptions.Builder builder)
      Allows the plugin to modify worker options before a worker is created. Called during configuration phase in forward (registration) order.
      Parameters:
      taskQueue - the task queue name for the worker being created
      builder - the options builder to modify

    • initializeWorker

      void initializeWorker(@Nonnull String taskQueue, @Nonnull Worker worker)
      Called after a worker is created, allowing plugins to register workflows, activities, Nexus services, and other components on the worker.

      This method is called in forward (registration) order immediately after the worker is created in WorkerFactory.newWorker(java.lang.String). This is the appropriate place for registrations because it is called before the worker starts polling.

      Example: 

      
 @Override
 public void initializeWorker(String taskQueue, Worker worker) {
     worker.registerWorkflowImplementationTypes(MyWorkflow.class);
     worker.registerActivitiesImplementations(new MyActivityImpl());
 }
      Parameters:
      taskQueue - the task queue name for the worker
      worker - the newly created worker

    • startWorker

      void startWorker(@Nonnull String taskQueue, @Nonnull Worker worker, @Nonnull BiConsumer<String,Worker> next)
      Allows the plugin to wrap individual worker startup. Called during execution phase in reverse order (first plugin wraps all others) when WorkerFactory.start() is invoked.

      This method is called for each worker when the factory starts. Use this for per-worker resource initialization, logging, or metrics. Note that workflow/activity registration should be done in initializeWorker(java.lang.String, io.temporal.worker.Worker) instead, as this method is called after registrations are finalized.

      Example: 

      
 @Override
 public void startWorker(String taskQueue, Worker worker, BiConsumer<String, Worker> next) {
     logger.info("Starting worker for task queue: {}", taskQueue);
     perWorkerResources.put(taskQueue, new ResourcePool());
     next.accept(taskQueue, worker);
 }
      Parameters:
      taskQueue - the task queue name for the worker
      worker - the worker being started
      next - callback that starts the next in chain (eventually starts the actual worker)

    • shutdownWorker

      void shutdownWorker(@Nonnull String taskQueue, @Nonnull Worker worker, @Nonnull BiConsumer<String,Worker> next)
      Allows the plugin to wrap individual worker shutdown. Called during shutdown phase in reverse order (first plugin wraps all others) when WorkerFactory.shutdown() or WorkerFactory.shutdownNow() is invoked.

      This method is called for each worker when the factory shuts down. Use this for per-worker resource cleanup that was initialized in startWorker(java.lang.String, io.temporal.worker.Worker, java.util.function.BiConsumer<java.lang.String, io.temporal.worker.Worker>) or initializeWorker(java.lang.String, io.temporal.worker.Worker).

      Warning: Exceptions thrown from this method will propagate up and may halt the shutdown process. Plugin authors should handle exceptions appropriately and ensure next is called exactly once. If cleanup code may throw, consider wrapping it in a try-catch to ensure graceful degradation.

      Example: 

      
 @Override
 public void shutdownWorker(String taskQueue, Worker worker, BiConsumer<String, Worker> next) {
     logger.info("Shutting down worker for task queue: {}", taskQueue);
     next.accept(taskQueue, worker);
     ResourcePool pool = perWorkerResources.remove(taskQueue);
     if (pool != null) {
         pool.close();
     }
 }
      Parameters:
      taskQueue - the task queue name for the worker
      worker - the worker being shut down
      next - callback that shuts down the next in chain (eventually shuts down the actual worker)

    • startWorkerFactory

      void startWorkerFactory(@Nonnull WorkerFactory factory, @Nonnull Consumer<WorkerFactory> next)
      Allows the plugin to wrap worker factory startup. Called during execution phase in reverse order (first plugin wraps all others).

      This method is called when WorkerFactory.start() is invoked. The plugin can perform setup before starting and cleanup logic.

      Example: 

      
 @Override
 public void startWorkerFactory(WorkerFactory factory, Consumer<WorkerFactory> next) {
     logger.info("Starting workers...");
     next.accept(factory);
     logger.info("Workers started");
 }
      Parameters:
      factory - the worker factory being started
      next - callback that starts the next in chain (eventually starts actual workers)

    • shutdownWorkerFactory

      void shutdownWorkerFactory(@Nonnull WorkerFactory factory, @Nonnull Consumer<WorkerFactory> next)
      Allows the plugin to wrap worker factory shutdown. Called during shutdown phase in reverse order (first plugin wraps all others).

      This method is called when WorkerFactory.shutdown() or WorkerFactory.shutdownNow() is invoked. The plugin can perform actions before and after the actual shutdown occurs.

      Warning: Exceptions thrown from this method will propagate up and may halt the shutdown process. Plugin authors should handle exceptions appropriately and ensure next is called exactly once. If cleanup code may throw, consider wrapping it in a try-catch to ensure graceful degradation.

      Example: 

      
 @Override
 public void shutdownWorkerFactory(WorkerFactory factory, Consumer<WorkerFactory> next) {
     logger.info("Shutting down workers...");
     next.accept(factory);
     logger.info("Workers shut down");
 }
      Parameters:
      factory - the worker factory being shut down
      next - callback that shuts down the next in chain (eventually shuts down actual workers)

    • replayWorkflowExecution

      void replayWorkflowExecution(@Nonnull Worker worker, @Nonnull WorkflowExecutionHistory history, @Nonnull WorkerPlugin.ReplayCallback next) throws Exception
      Allows the plugin to wrap workflow execution replay. Called in reverse order (first plugin wraps all others) when replaying a workflow history.

      This method allows plugins to perform setup/teardown around replay, add logging, metrics, or other observability for replay operations.

      Example: 

      
 @Override
 public void replayWorkflowExecution(
     Worker worker, WorkflowExecutionHistory history, ReplayCallback next) throws Exception {
     logger.info("Replaying workflow: {}", history.getWorkflowExecution().getWorkflowId());
     long start = System.currentTimeMillis();
     try {
         next.replay(worker, history);
         logger.info("Replay succeeded in {}ms", System.currentTimeMillis() - start);
     } catch (Exception e) {
         logger.error("Replay failed after {}ms", System.currentTimeMillis() - start, e);
         throw e;
     }
 }
      Parameters:
      worker - the worker performing the replay
      history - the workflow execution history being replayed
      next - callback that performs the next in chain (eventually performs the actual replay)
      Throws:
      Exception - if replay fails