Skip to main content

Run a Worker - Java SDK

View Markdown

This page covers long-lived Workers that you host and run as persistent processes. For Workers that run on serverless compute like AWS Lambda, see Serverless Workers.

Create and run a Worker​

Create a WorkerFactory from a Workflow Client, then call newWorker() with the Task Queue to poll. Register the Workflow and Activity types the Worker can execute, then call start() on the factory.

features/snippets/worker/worker.java

WorkerFactory factory = WorkerFactory.newInstance(client);

Worker worker = factory.newWorker("my-task-queue");
worker.registerWorkflowImplementationTypes(GreetingWorkflowImpl.class);
worker.registerActivitiesImplementations(new GreetingActivitiesImpl());

factory.start();

start() starts every Worker the factory created, so one factory can run several Workers in a single process. The call returns immediately and the Workers poll on background threads, so the process has to stay alive.

Register Workflows and Activities​

All Workers polling the same Task Queue must register the same Workflow Types and Activity Types. A Task Queue does not route by type, so any Worker polling it can receive any Task on that queue. A Worker that receives a Task for a type it did not register fails that Task.

Register Workflows by class with registerWorkflowImplementationTypes(). The Worker creates a new instance for each Workflow Execution, so a Workflow Type can be registered only once per Worker. Registering two implementations of the same type throws at registration time.

Register Activities by instance with registerActivitiesImplementations(). One instance serves every Workflow Execution that calls it, so the implementation must be thread-safe. Pass dependencies such as database clients through the constructor.

worker.registerWorkflowImplementationTypes(GreetingWorkflowImpl.class, OrderWorkflowImpl.class);
worker.registerActivitiesImplementations(new GreetingActivitiesImpl(databaseClient));

A Worker can register one implementation of DynamicWorkflow and one of DynamicActivity alongside any number of type-specific implementations. The dynamic implementation handles Workflow and Activity Types that no registered type matches.

Connect to Temporal Cloud​

To run a Worker against Temporal Cloud, configure the Client connection with your Namespace address and authentication credentials. See Connect to Temporal Cloud for setup instructions.

Configure Worker options​

Pass WorkerOptions to newWorker() to set concurrency limits, poller counts, and rate limits for a single Worker. Pass WorkerFactoryOptions to newInstance() for settings shared by every Worker in the process, such as the Workflow cache size. The defaults work for most cases.

To tune these values against real load, see Worker performance and the Worker tuning reference.

Run a versioned Worker​

Set a Worker Deployment Version and enable versioning in WorkerOptions, then set a versioning behavior on each Workflow.

features/snippets/worker/worker.java

WorkerOptions options =
    WorkerOptions.newBuilder()
        .setDeploymentOptions(
            WorkerDeploymentOptions.newBuilder()
                .setVersion(new WorkerDeploymentVersion("my-app", "1.0"))
                .setUseVersioning(true)
                .build())
        .build();

Worker worker = factory.newWorker("my-task-queue", options);
worker.registerWorkflowImplementationTypes(VersionedGreetingWorkflowImpl.class);
worker.registerActivitiesImplementations(new GreetingActivitiesImpl());

Annotate the Workflow method with @WorkflowVersioningBehavior(VersioningBehavior.PINNED) or AUTO_UPGRADE, or set a default for the whole Worker with setDefaultVersioningBehavior(). The annotation belongs on the implementation, not the interface.

A versioning behavior applies only to a Worker that has versioning enabled. If a Workflow declares one and its Worker does not enable versioning, the server rejects the Workflow Task and the Task retries instead of failing outright.

See Worker Versioning for the available versioning behaviors and how new versions roll out.

Shut down a Worker​

Call shutdown() on the factory to stop polling for new Tasks, then awaitTermination() to give in-flight Tasks time to finish.

features/snippets/worker/worker.java

factory.shutdown();
factory.awaitTermination(30, TimeUnit.SECONDS);

Both calls apply to every Worker the factory created. See Worker shutdown for what happens to in-flight Workflow Tasks and Activities.