Class SimplePlugin

java.lang.Object
io.temporal.common.SimplePlugin
All Implemented Interfaces:
ScheduleClientPlugin, WorkflowClientPlugin, io.temporal.serviceclient.WorkflowServiceStubsPlugin, WorkerPlugin
@Experimental public abstract class SimplePlugin extends Object implements io.temporal.serviceclient.WorkflowServiceStubsPlugin, WorkflowClientPlugin, ScheduleClientPlugin, WorkerPlugin
A plugin that implements WorkflowServiceStubsPlugin, WorkflowClientPlugin, ScheduleClientPlugin, and WorkerPlugin. This class can be used in two ways:
  1. Builder pattern: Use newBuilder(String) to declaratively configure a plugin with callbacks
  2. Subclassing: Extend this class and override specific methods for custom behavior

Builder Pattern Example


 SimplePlugin myPlugin = SimplePlugin.newBuilder("my-plugin")
     .addWorkerInterceptors(new TracingInterceptor())
     .addClientInterceptors(new LoggingInterceptor())
     .customizeDataConverter(existing -> new CodecDataConverter(existing, myCodec))
     .build();

Subclassing Example


 public class TracingPlugin extends SimplePlugin {
     private final Tracer tracer;

     public TracingPlugin(Tracer tracer) {
         super("io.temporal.tracing");
         this.tracer = tracer;
     }

     @Override
     public void configureWorkflowClient(WorkflowClientOptions.Builder builder) {
         builder.setInterceptors(new TracingClientInterceptor(tracer));
     }
 }

Hybrid Example (Builder + Override)


 public class HybridPlugin extends SimplePlugin {
     public HybridPlugin() {
         super(SimplePlugin.newBuilder("hybrid")
             .addClientInterceptors(new LoggingInterceptor()));
     }

     @Override
     public void initializeWorker(String taskQueue, Worker worker) {
         worker.registerWorkflowImplementationTypes(MyWorkflow.class);
     }
 }
See Also:

  • Constructor Details

    • SimplePlugin

      protected SimplePlugin(@Nonnull String name)
      Creates a new plugin with the specified name. Use this constructor when subclassing to override specific methods.
      Parameters:
      name - a unique name for this plugin, used for logging and duplicate detection. Recommended format: "organization.plugin-name" (e.g., "io.temporal.tracing")
      Throws:
      NullPointerException - if name is null

    • SimplePlugin

      protected SimplePlugin(@Nonnull SimplePlugin.Builder builder)
      Creates a new plugin from a builder. Use this constructor when subclassing to combine builder configuration with method overrides.
      Parameters:
      builder - the builder with configuration
      Throws:
      NullPointerException - if builder is null

  • Method Details

    • newBuilder

      public static SimplePlugin.Builder newBuilder(@Nonnull String name)
      Creates a new builder with the specified plugin name.
      Parameters:
      name - a unique name for the plugin, used for logging and duplicate detection. Recommended format: "organization.plugin-name" (e.g., "my-org.tracing")
      Returns:
      a new builder instance

    • getName

      @Nonnull public String getName()
      Description copied from interface: WorkflowClientPlugin
      Returns a unique name for this plugin. Used for logging and duplicate detection. Recommended format: "organization.plugin-name" (e.g., "io.temporal.tracing")
      Specified by:
      getName in interface ScheduleClientPlugin
      Specified by:
      getName in interface WorkerPlugin
      Specified by:
      getName in interface WorkflowClientPlugin
      Specified by:
      getName in interface io.temporal.serviceclient.WorkflowServiceStubsPlugin
      Returns:
      fully qualified plugin name

    • configureServiceStubs

      public void configureServiceStubs(@Nonnull io.temporal.serviceclient.WorkflowServiceStubsOptions.Builder builder)
      Specified by:
      configureServiceStubs in interface io.temporal.serviceclient.WorkflowServiceStubsPlugin

    • configureWorkflowClient

      public void configureWorkflowClient(@Nonnull WorkflowClientOptions.Builder builder)
      Description copied from interface: WorkflowClientPlugin
      Allows the plugin to modify workflow client options before the client is created. Called during configuration phase in forward (registration) order.
      Specified by:
      configureWorkflowClient in interface WorkflowClientPlugin
      Parameters:
      builder - the options builder to modify

    • configureScheduleClient

      public void configureScheduleClient(@Nonnull ScheduleClientOptions.Builder builder)
      Description copied from interface: ScheduleClientPlugin
      Allows the plugin to modify schedule client options before the client is created. Called during configuration phase in forward (registration) order.
      Specified by:
      configureScheduleClient in interface ScheduleClientPlugin
      Parameters:
      builder - the options builder to modify

    • configureWorkerFactory

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

    • configureWorker

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

    • initializeWorker

      public void initializeWorker(@Nonnull String taskQueue, @Nonnull Worker worker)
      Description copied from interface: WorkerPlugin
      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());
 }
      Specified by:
      initializeWorker in interface WorkerPlugin
      Parameters:
      taskQueue - the task queue name for the worker
      worker - the newly created worker

    • startWorker

      public void startWorker(@Nonnull String taskQueue, @Nonnull Worker worker, @Nonnull BiConsumer<String,Worker> next)
      Description copied from interface: WorkerPlugin
      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 WorkerPlugin.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);
 }
      Specified by:
      startWorker in interface WorkerPlugin
      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

      public void shutdownWorker(@Nonnull String taskQueue, @Nonnull Worker worker, @Nonnull BiConsumer<String,Worker> next)
      Description copied from interface: WorkerPlugin
      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 WorkerPlugin.startWorker(java.lang.String, io.temporal.worker.Worker, java.util.function.BiConsumer<java.lang.String, io.temporal.worker.Worker>) or WorkerPlugin.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();
     }
 }
      Specified by:
      shutdownWorker in interface WorkerPlugin
      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)

    • connectServiceClient

      public io.temporal.serviceclient.WorkflowServiceStubs connectServiceClient(io.temporal.serviceclient.WorkflowServiceStubsOptions options, Supplier<io.temporal.serviceclient.WorkflowServiceStubs> next)
      Specified by:
      connectServiceClient in interface io.temporal.serviceclient.WorkflowServiceStubsPlugin

    • startWorkerFactory

      public void startWorkerFactory(WorkerFactory factory, Consumer<WorkerFactory> next)
      Description copied from interface: WorkerPlugin
      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");
 }
      Specified by:
      startWorkerFactory in interface WorkerPlugin
      Parameters:
      factory - the worker factory being started
      next - callback that starts the next in chain (eventually starts actual workers)

    • shutdownWorkerFactory

      public void shutdownWorkerFactory(WorkerFactory factory, Consumer<WorkerFactory> next)
      Description copied from interface: WorkerPlugin
      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");
 }
      Specified by:
      shutdownWorkerFactory in interface WorkerPlugin
      Parameters:
      factory - the worker factory being shut down
      next - callback that shuts down the next in chain (eventually shuts down actual workers)

    • replayWorkflowExecution

      public void replayWorkflowExecution(@Nonnull Worker worker, @Nonnull WorkflowExecutionHistory history, @Nonnull WorkerPlugin.ReplayCallback next) throws Exception
      Description copied from interface: WorkerPlugin
      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;
     }
 }
      Specified by:
      replayWorkflowExecution in interface WorkerPlugin
      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

    • toString

      public String toString()
      Overrides:
      toString in class Object