Package io.temporal.worker

Interface WorkerPlugin

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

    Plugins that also implement io.temporal.client.ClientPlugin are automatically propagated from the client to workers created from that client.

    Example implementation: 

    {@code
 public class MetricsPlugin extends SimplePlugin {
     private final MetricsRegistry registry;

     public MetricsPlugin(MetricsRegistry registry) {
         super("my-org.metrics");
         this.registry = registry;
     }
    See Also:
    io.temporal.client.ClientPlugin, SimplePlugin

    • Method Detail

      • getName

        @Nonnull
java.lang.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
                     java.lang.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
                      java.lang.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: 

        {@code
        Parameters:
        taskQueue - the task queue name for the worker
        worker - the newly created worker

      • startWorker

        void startWorker​(@Nonnull
                 java.lang.String taskQueue,
                 @Nonnull
                 Worker worker,
                 @Nonnull
                 java.util.function.BiConsumer<java.lang.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: 

        {@code
        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)

      • startWorkerFactory

        void startWorkerFactory​(@Nonnull
                        WorkerFactory factory,
                        @Nonnull
                        java.util.function.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: 

        {@code
        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
                           java.util.function.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: 

        {@code
        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 java.lang.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: 

        {@code
        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:
        java.lang.Exception - if replay fails