Session concurrency limitation scope
The concurrent session limitation is per Worker Process, not per host. Ensure there is only one Worker Process running on the host if you plan to use this feature.
Temporal · Develop · all subjects
workers/basics
378 notes in this subject, read out of this brain and free to use. This is page 2 of 7.
SessionOptions structure for creating Sessions
SessionOptions contains two fields: CreationTimeout (the maximum time to wait for the Session to be created) and ExecutionTimeout (the maximum time the Session can execute). Both should be specified as time.Duration values when calling CreateSession.
MaxConcurrentSessionExecutionSize worker option
The MaxConcurrentSessionExecutionSize field in worker.Options limits the maximum number of concurrent Sessions running on a Worker. By default, this field is set to a very large value. If a Worker hits this limitation, it will not accept new CreateSession() requests until an existing session completes. If a session cannot be created within CreationTimeout, CreateSession() returns an error.
Enable Worker Sessions in Go SDK
To enable Worker Sessions in Go SDK, set the EnableSessionWorker field to true in the worker.Options structure when creating a worker. This enables task routing to ensure Activity Tasks are executed by the same Worker without manually specifying Task Queue names.
Worker Sessions example in Go SDK
Example of creating and using a Worker Session in a workflow: Define SessionOptions with CreationTimeout and ExecutionTimeout. Call workflow.CreateSession(ctx, sessionOptions) to create a session context. Defer workflow.CompleteSession(sessionCtx) to ensure cleanup. Execute activities using the session context by passing sessionCtx to workflow.ExecuteActivity() calls. All activities executed with the session context will run on the same Worker.
Sessions Go SDK feature availability
Worker Sessions are currently available only in the Go SDK.
Example: Register Activity with Worker for Standalone execution
ClientConfigProfile profile = ClientConfigProfile.load(); WorkflowServiceStubs service = WorkflowServiceStubs.newServiceStubs(profile.toWorkflowServiceStubsOptions()); WorkflowClient client = WorkflowClient.newInstance(service, profile.toWorkflowClientOptions()); WorkerFactory factory = WorkerFactory.newInstance(client); Worker worker = factory.newWorker(TASK_QUEUE); worker.registerActivitiesImplementations(new GreetingActivitiesImpl()); factory.start(); System.out.println("Worker running on task queue: " + TASK_QUEUE);
Worker setup for Standalone Activities
Running a Worker for Standalone Activities is the same as running a Worker for Workflow Activities — you create a WorkerFactory, register the Activity implementation, and call factory.start(). The Worker doesn't need to know whether the Activity will be invoked from a Workflow or as a Standalone Activity.
Java SDK Client documentation structure
The Java SDK Client documentation is organized into two main sections: Temporal Client and Namespaces. The Temporal Client section explains how to implement the Temporal Client with the Java SDK.
Namespace registration prerequisite and client setup
You must register a Namespace with the Temporal Service before setting it in the Temporal Client. Once registered, set the Namespace using WorkflowClientOptions within a Workflow Client to run your Workflow Executions within that Namespace.
DeleteNamespace example in Java
The following example deletes a Namespace: import io.temporal.api.workflowservice.v1.*; DeleteNamespaceResponse res = OperatorServiceStubs.newServiceStubs(OperatorServiceStubsOptions.newBuilder() .setChannel(service.getRawChannel()) .validateAndBuildWithDefaults()) .blockingStub() .deleteNamespace(DeleteNamespaceRequest.newBuilder().setNamespace("your-namespace-name").build());
ListNamespace API for getting all Namespaces
Use the ListNamespace API to return information and configuration details for all registered Namespaces on your Temporal Service. The API lists 1-100 namespaces (1 page) in the active Temporal Service. To list all Namespaces, set the page size or loop until NextPageToken is nil.
ListNamespace example in Java
The following example lists all registered Namespaces: import io.temporal.api.workflowservice.v1.*; ListNamespacesRequest listNamespaces = ListNamespacesRequest.newBuilder().build(); ListNamespacesResponse listNamespacesResponse = namespaceservice.blockingStub().listNamespaces(listNamespaces);
DescribeNamespace example in Java
The following example gets details for a specific Namespace: import io.temporal.api.workflowservice.v1.*; DescribeNamespaceRequest descNamespace = DescribeNamespaceRequest.newBuilder() .setNamespace("your-namespace-name") .build(); DescribeNamespaceResponse describeNamespaceResponse = namespaceservice.blockingStub().describeNamespace(descNamespace); System.out.println("Namespace Description: " + describeNamespaceResponse);
DeprecateNamespace API and behavior
Use the DeprecateNamespace API to update the state of a registered Namespace to DEPRECATED. Once a Namespace is deprecated, you cannot start new Workflow Executions on it. All existing and running Workflow Executions on a deprecated Namespace will continue to run.
UpdateNamespace API for modifying Namespace configuration
Use the UpdateNamespace API to update information and configuration for a registered Namespace. You can update the description via UpdateNamespaceInfo and update the retention period via NamespaceConfig using setWorkflowExecutionRetentionTtl.
UpdateNamespace example in Java
The following example updates a Namespace description and retention period to 30 hours: import io.temporal.api.workflowservice.v1.*; UpdateNamespaceRequest updateNamespaceRequest = UpdateNamespaceRequest.newBuilder() .setNamespace("your-namespace-name") .setUpdateInfo(UpdateNamespaceInfo.newBuilder() .setDescription("your updated namespace description") .build()) .setConfig(NamespaceConfig.newBuilder() .setWorkflowExecutionRetentionTtl(Durations.fromHours(30)) .build()) .build(); UpdateNamespaceResponse updateNamespaceResponse = namespaceservice.blockingStub().updateNamespace(updateNamespaceRequest);
DescribeNamespace API for getting Namespace details
Use the DescribeNamespace API to return information and configuration details for a registered Namespace. Provide the Namespace name to specify which Namespace you want details for.
DeprecateNamespace example in Java
The following example deprecates a Namespace: import io.temporal.api.workflowservice.v1.*; DeprecateNamespaceRequest deprecateNamespace = DeprecateNamespaceRequest.newBuilder() .setNamespace("your-namespace-name") .build(); DeprecateNamespaceResponse response = namespaceservice.blockingStub().deprecateNamespace(deprecateNamespace);
RegisterNamespace API with retention period
Use the RegisterNamespace API to register a Namespace and set the Retention Period for the Workflow Execution Event History. The Retention Period setting using WorkflowExecutionRetentionPeriod is mandatory. The minimum value you can set for this period is 1 day. Namespace registration using this API takes up to 10 seconds to complete; ensure that you wait for this registration to complete before starting the Workflow Execution against the Namespace.
RegisterNamespace example in Java
The following example registers a Namespace with a 3-day retention period: import com.google.protobuf.util.Durations; import io.temporal.api.workflowservice.v1.RegisterNamespaceRequest; public static void createNamespace(String name) { RegisterNamespaceRequest req = RegisterNamespaceRequest.newBuilder() .setNamespace("your-custom-namespace") .setWorkflowExecutionRetentionPeriod(Durations.fromDays(3)) .build(); service.blockingStub().registerNamespace(req); }
DeleteNamespace API and consequences
Use the DeleteNamespace API to delete a Namespace. Deleting a Namespace deletes all running and completed Workflow Executions on the Namespace and removes them from the persistence store and the visibility store.
Java SDK main documentation structure
The Java SDK developer guide covers Workflows, Activities, Workers, Temporal Client, Temporal Nexus, Platform features, Best practices, and Integrations. Core topics include Workflow basics, Activity basics, Worker processes, and Temporal Client operations. The guide provides links to quickstart guides, API documentation, code samples, and community resources.
Spring Boot integration Gradle dependency
To use Temporal Spring Boot integration with Gradle, add the implementation dependency: implementation ("io.temporal:temporal-spring-boot-starter:1.31.0").
Connect to local Temporal Service with Spring Boot
To connect to a local Temporal Service in Spring Boot, specify spring.temporal.connection.target: local in application.yml. This allows autowiring a WorkflowClient in your Spring application. You can also specify a custom host:port for remote connections.
Spring Boot WorkerOptionsCustomizer interface
To customize WorkerOptions for specific Task Queue or Worker names in Spring Boot, use io.temporal.spring.boot.WorkerOptionsCustomizer instead of TemporalOptionsCustomizer<WorkerOptions.Builder>.
Connect to custom Namespace with Spring Boot
To connect to a custom Namespace in Spring Boot, specify the spring.temporal.namespace property in application.yml with the namespace name.
Connect to Temporal Cloud with API key in Spring Boot
To connect to Temporal Cloud using an API key, configure spring.temporal.connection.target with the target URL, spring.temporal.connection.apiKey with your API key, and spring.temporal.namespace with your namespace name in application.yml.
Explicit Worker configuration in Spring Boot
To explicitly configure Workers in Spring Boot, use the spring.temporal.workers configuration with a list of workers. Each worker requires a task-queue name and can optionally have a name (defaults to task-queue name), a list of workflow-classes, and a list of activity-beans.
Connect to Temporal Cloud with mTLS in Spring Boot
To connect to Temporal Cloud using mTLS in Spring Boot, configure spring.temporal.connection.mtls.target with the target URL, spring.temporal.connection.mtls.key-file with the path to your key file, and spring.temporal.connection.mtls.cert-chain-file with the path to your certificate chain file. If using PKCS12 format (.pkcs12, .pfx, or .p12), the cert-chain-file is not needed as the certificate chain is bundled in the key file.
Spring Boot TemporalOptionsCustomizer interface
To programmatically customize options created by Spring Boot integration, create beans implementing io.temporal.spring.boot.TemporalOptionsCustomizer<OptionsBuilderType> interface. Supported OptionsBuilderType values are: WorkflowServiceStubsOptions.Builder, WorkflowClientOptions.Builder, WorkerFactoryOptions.Builder, WorkerOptions.Builder, WorkflowImplementationOptions.Builder, and TestEnvironmentOptions.Builder.
Spring Boot WorkflowImplementationOptionsCustomizer interface
To customize WorkflowImplementationOptions for specific Workflow Types in Spring Boot, use io.temporal.spring.boot.WorkflowImplementationOptionsCustomizer instead of TemporalOptionsCustomizer<WorkflowImplementationOptions.Builder>.
Worker auto-discovery in Spring Boot
To enable auto-discovery of Workers, Workflows, Activities, and Nexus Services in Spring Boot, configure spring.temporal.workers-auto-discovery.packages with a list of packages to scan. Auto-discovery will find: Workflow classes annotated with @io.temporal.spring.boot.WorkflowImpl, Activity beans whose implementations are annotated with @io.temporal.spring.boot.ActivityImpl, Nexus Service beans whose implementations are annotated with @io.temporal.spring.boot.NexusServiceImpl, and will automatically create Workers for discovered task queues.
Spring Boot Activity annotation with worker assignment
To assign Activities to a specific Worker in Spring Boot auto-discovery, annotate your Activity implementation class with @Component and @ActivityImpl(workers = "workerName"). The Activity class must be discoverable as a Spring bean.
Spring Boot interceptor registration
To register interceptors in Spring Boot, create beans that implement WorkflowClientInterceptor, ScheduleClientInterceptor, or WorkerInterceptor interfaces. Interceptors are registered in the order specified by the @Order annotation.
Spring Boot integration Maven dependency
To use Temporal Spring Boot integration, add the dependency io.temporal:temporal-spring-boot-starter version 1.31.0 to your Maven project. The integration supports Spring Boot 2.x, 3.x, and 4.x.
Java SDK platform documentation structure
The Java SDK platform documentation covers two main topics: Observability and Enriching the UI. These sections provide guidance on implementing platform features with the Java SDK.
Worker creation and registration in Java
Create a Worker using WorkerFactory.newInstance(client).newWorker("task-queue-name"). Register workflow implementations with worker.registerWorkflowImplementationTypes() and activities with worker.registerActivitiesImplementations().
WorkflowClient instantiation
Create a WorkflowClient using WorkflowClient.newInstance(WorkflowServiceStubs) to interact with the Temporal Service.
WorkflowServiceStubs for local development
Use WorkflowServiceStubs.newLocalServiceStubs() to create service stubs that connect to a local Temporal Service running on localhost:7233.
Start worker factory
Call factory.start() after registering workflow and activity implementations to begin polling for tasks.
Set task queue in workflow options
Specify the task queue for a workflow execution using WorkflowOptions.newBuilder().setTaskQueue("task-queue-name").build().
Change Temporal Web UI port
Use the --ui-port option when starting the development server: 'temporal server start-dev --ui-port 8080' to run the Web UI on a different port.
Java SDK installation requirements
To develop with the Temporal Java SDK, you need Java JDK installed (from Oracle or OpenJDK), and either Maven or Gradle for building.
Temporal SDK Maven dependency
Add the temporal-sdk dependency to Maven pom.xml with groupId io.temporal, artifactId temporal-sdk, and version 1.33.0.
Temporal SDK Gradle dependency
Add temporal-sdk:1.33.0 to Gradle build.gradle dependencies as implementation 'io.temporal:temporal-sdk:1.33.0'.
Java SDK workers documentation section
The Java SDK documentation covers Workers with a link to the 'Run Worker processes' page for detailed information on how to run worker processes.
Assign Build ID to Java Worker with setUseBuildIdForVersioning
To enable Worker Versioning in Java, use WorkerOptions with setBuildId(buildId) and setUseBuildIdForVersioning(true). Example: WorkerOptions.newBuilder().setBuildId(buildId).setUseBuildIdForVersioning(true).build(). The Build ID can be passed from an environment variable.
Create a Worker from WorkerFactory
Create a WorkerFactory from a Temporal Client using WorkerFactory.newInstance(client), then call newWorker() with the Task Queue name to specify which queue the Worker polls. Register Workflow and Activity types using registerWorkflowImplementationTypes() and registerActivitiesImplementations(), then call factory.start() to begin polling.
Example: Create and run a Worker in Java
WorkerFactory factory = WorkerFactory.newInstance(client); Worker worker = factory.newWorker("my-task-queue"); worker.registerWorkflowImplementationTypes(GreetingWorkflowImpl.class); worker.registerActivitiesImplementations(new GreetingActivitiesImpl()); factory.start();
WorkerFactory.start() starts all Workers
Calling start() on a WorkerFactory starts every Worker the factory created. One factory can run several Workers in a single process. The call returns immediately and Workers poll on background threads, so the process must stay alive.
Example: Register multiple Workflow and Activity types
worker.registerWorkflowImplementationTypes(GreetingWorkflowImpl.class, OrderWorkflowImpl.class); worker.registerActivitiesImplementations(new GreetingActivitiesImpl(databaseClient));
Register Workflows by class with registerWorkflowImplementationTypes()
Register Workflows using 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 an exception at registration time.
Register Activities by instance with registerActivitiesImplementations()
Register Activities using 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.
Configure Worker options with WorkerOptions
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.
DynamicWorkflow and DynamicActivity handle unregistered types
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.
Graceful Worker shutdown with factory.shutdown() and awaitTermination()
Call shutdown() on the factory to stop polling for new Tasks, then awaitTermination() with a timeout to give in-flight Tasks time to finish. Both calls apply to every Worker the factory created.
Example: Graceful Worker shutdown
factory.shutdown(); factory.awaitTermination(30, TimeUnit.SECONDS);
AWS Lambda support for Java Serverless Workers
The temporal-aws-lambda contrib module allows running a Worker as a Lambda function in Java. It covers setup, configuration, Lambda-tuned defaults, observability, and the invocation lifecycle.
Serverless Worker on AWS Lambda using temporal-aws-lambda module
The temporal-aws-lambda contrib module allows you to run a Temporal Serverless Worker on AWS Lambda. Deploy your Worker code as a Lambda function, and Temporal Cloud invokes it when Tasks arrive. Each invocation starts a Worker, polls for Tasks, then gracefully shuts down before a configurable invocation deadline. Workflows and Activities are registered the same way as with a standard Worker.