Namespaces - Temporal Java SDK feature guide

This page shows how to do the following:

You can create, update, deprecate or delete your Namespaces using either the Temporal CLI or SDK APIs.

Use Namespaces to isolate your Workflow Executions according to your needs. For example, you can use Namespaces to match the development lifecycle by having separate dev and prod Namespaces. You could also use them to ensure Workflow Executions between different teams never communicate - such as ensuring that the teamA Namespace never impacts the teamB Namespace.

On Temporal Cloud, use the Temporal Cloud UI to create and manage a Namespace from the UI, or tcld commands to manage Namespaces from the command-line interface.

On self-hosted Temporal Service, you can register and manage your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

You must register a Namespace with the Temporal Service before setting it in the Temporal Client.

Register a Namespace

How to register a Namespace using the Java SDK.

Registering a Namespace creates a Namespace on the Temporal Service or Temporal Cloud.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to create Namespaces.

On self-hosted Temporal Service, you can register your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

Use the RegisterNamespace API to register a Namespace and set the Retention Period for the Workflow Execution Event History for the Namespace.

//...
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)) // keeps the Workflow Execution
            //Event History for up to 3 days in the Persistence store. Not setting this value will throw an error.
            .build();
    service.blockingStub().registerNamespace(req);
}
//...

The Retention Period setting using WorkflowExecutionRetentionPeriod is mandatory. The minimum value you can set for this period is 1 day.

Once registered, set Namespace using WorkflowClientOptions within a Workflow Client to run your Workflow Executions within that Namespace. See how to set Namespace in a Client in Java for details.

Note that 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.

To update your Namespace use the UpdateNamespace API with the NamespaceClient.

Manage Namespaces

How to manage Namespaces using the Java SDK.

You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to manage Namespaces.

On self-hosted Temporal Service, you can manage your registered Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud.

Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.

You must register a Namespace with the Temporal Service before setting it in the Temporal Client.

On Temporal Cloud, use the Temporal Cloud UI or tcld commands to manage Namespaces.

Update information and configuration for a registered Namespace on your Temporal Service:

With the Temporal CLI: temporal operator namespace update Example
Use the UpdateNamespace API to update configuration on a Namespace. Example

import io.temporal.api.workflowservice.v1.*;
//...
UpdateNamespaceRequest updateNamespaceRequest = UpdateNamespaceRequest.newBuilder()
            .setNamespace("your-namespace-name") //the namespace that you want to update
            .setUpdateInfo(UpdateNamespaceInfo.newBuilder() //has options to update namespace info
                    .setDescription("your updated namespace description") //updates description in the namespace info.
                    .build())
            .setConfig(NamespaceConfig.newBuilder() //has options to update namespace configuration
                    .setWorkflowExecutionRetentionTtl(Durations.fromHours(30)) //updates the retention period for the namespace "your-namespace--name" to 30 hrs.
                    .build())
            .build();
    UpdateNamespaceResponse updateNamespaceResponse = namespaceservice.blockingStub().updateNamespace(updateNamespaceRequest);
//...

Get details for a registered Namespace on your Temporal Service:

With the Temporal CLI: temporal operator namespace describe
Use the DescribeNamespace API to return information and configuration details for a registered Namespace. Example

import io.temporal.api.workflowservice.v1.*;
//...
DescribeNamespaceRequest descNamespace = DescribeNamespaceRequest.newBuilder()
            .setNamespace("your-namespace-name") //specify the namespace you want details for
            .build();
    DescribeNamespaceResponse describeNamespaceResponse = namespaceservice.blockingStub().describeNamespace(descNamespace);
    System.out.println("Namespace Description: " + describeNamespaceResponse);
//...

Get details for all registered Namespaces on your Temporal Service:

With the Temporal CLI: temporal operator namespace list
Use the ListNamespace API to return information and configuration details for all registered Namespaces on your Temporal Service. Example

import io.temporal.api.workflowservice.v1.*;
//...
ListNamespacesRequest listNamespaces = ListNamespacesRequest.newBuilder().build();
    ListNamespacesResponse listNamespacesResponse = namespaceservice.blockingStub().listNamespaces(listNamespaces); //lists 1-100 namespaces (1 page) in the active Temporal Service. To list all, set the page size or loop until NextPageToken is nil.
//...

Deprecate a Namespace: The DeprecateNamespace API updates 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. Example:

import io.temporal.api.workflowservice.v1.*;
//...
DeprecateNamespaceRequest deprecateNamespace = DeprecateNamespaceRequest.newBuilder()
            .setNamespace("your-namespace-name") //specify the namespace that you want to deprecate
            .build();
    DeprecateNamespaceResponse response = namespaceservice.blockingStub().deprecateNamespace(deprecateNamespace);
//...

Delete a Namespace: The DeleteNamespace API deletes 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.

Example:

//...
DeleteNamespaceResponse res =
OperatorServiceStubs.newServiceStubs(OperatorServiceStubsOptions.newBuilder()
        .setChannel(service.getRawChannel())
        .validateAndBuildWithDefaults())
    .blockingStub()
    .deleteNamespace(DeleteNamespaceRequest.newBuilder().setNamespace("your-namespace-name").build());
//...

Register a Namespace​

Manage Namespaces​

Register a Namespace

Manage Namespaces