temporalio__skill-temporal-developer/references/java/determinism-protection.md

Java Determinism Protection

Overview

The Java SDK has no sandbox (only Python and TypeScript have sandboxing). Java relies on developer conventions and runtime replay detection to enforce determinism. A static analysis tool (temporal-workflowcheck) is available in beta.

Forbidden Operations

// BAD: Non-deterministic operations in workflow code
Thread.sleep(1000);
UUID id = UUID.randomUUID();
double val = Math.random();
long now = System.currentTimeMillis();
new Thread(() -> doWork()).start();
CompletableFuture.supplyAsync(() -> compute());

// GOOD: Deterministic Workflow.* alternatives
Workflow.sleep(Duration.ofSeconds(1));
String id = Workflow.randomUUID().toString();
int val = Workflow.newRandom().nextInt();
long now = Workflow.currentTimeMillis();
Promise<Void> promise = Async.procedure(() -> doWork());
CompletablePromise<String> promise = Workflow.newPromise();

Static Analysis with temporal-workflowcheck

Warning: This tool is in beta.

temporal-workflowcheck scans compiled bytecode to detect non-deterministic operations in workflow code. It catches threading, I/O, randomization, system time access, and non-final static field access — including transitive violations through call chains.

Setup (Gradle)

Add the dependency as a compile-only check:

dependencies {
    implementation 'io.temporal:temporal-sdk:1.+'
    compileOnly 'io.temporal:temporal-workflowcheck:1.+'
}

See the Gradle sample for full task configuration.

Setup (Maven)

See the Maven sample for POM configuration.

Running Manually

Download the -all.jar from Maven Central (io.temporal:temporal-workflowcheck) and run:

java -jar temporal-workflowcheck-<version>-all.jar check <classpath-entries>

Suppressing False Positives

Use the @WorkflowCheck.SuppressWarnings annotation on methods:

@WorkflowCheck.SuppressWarnings(invalidMembers = "currentTimeMillis")
public long getCurrentMillis() {
    return System.currentTimeMillis();
}

Or use a .properties configuration file with --config <path> for third-party library false positives.

Convention-Based Enforcement

Java workflow code runs in a cooperative threading model where only one workflow thread executes at a time under a global lock. The SDK does not intercept or block non-deterministic calls. Instead, non-determinism is detected at replay time: if replayed code produces results that differ from the recorded history, the SDK throws a NonDeterministicException.

Use both temporal-workflowcheck (static, pre-deploy) and WorkflowReplayer (replay testing) to catch non-determinism before production.

Best Practices

1. Run temporal-workflowcheck in CI to catch non-deterministic code statically
2. Always use Workflow.* APIs instead of standard Java equivalents for time, randomness, UUIDs, sleeping, and threading
3. Test all workflow code changes with WorkflowReplayer against recorded histories
4. Keep workflows focused on orchestration logic; move all I/O and side effects into activities
5. Avoid mutable static state shared across workflow instances