Release 0.2.0

README.md

@@ -36,7 +36,7 @@ Appropriately adjust the installation directory based on your coding agent.
 - [x] Python ✅
 - [x] TypeScript ✅
 - [x] Go ✅
-- [ ] Java 🚧 ([PR](https://github.com/temporalio/skill-temporal-developer/pull/42))
+- [x] Java ✅
 - [ ] .NET 🚧 ([PR](https://github.com/temporalio/skill-temporal-developer/pull/39))
 - [ ] Ruby 🚧 ([PR](https://github.com/temporalio/skill-temporal-developer/pull/41))
 - [ ] PHP 🚧 ([PR](https://github.com/temporalio/skill-temporal-developer/pull/40))

SKILL.md

@@ -1,42 +1,29 @@
 ---
 name: temporal-developer
-description: This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "Temporal TypeScript", "Temporal Go", "Temporal Golang", "workflow replay", "activity timeout", "signal workflow", "query workflow", "worker not starting", "activity keeps retrying", "Temporal heartbeat", "continue-as-new", "child workflow", "saga pattern", "workflow versioning", "durable execution", "reliable distributed systems", or mentions Temporal SDK development.
-version: 0.1.0
+description: This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "Temporal TypeScript", "Temporal Go", "Temporal Golang", "Temporal Java", "workflow replay", "activity timeout", "signal workflow", "query workflow", "worker not starting", "activity keeps retrying", "Temporal heartbeat", "continue-as-new", "child workflow", "saga pattern", "workflow versioning", "durable execution", "reliable distributed systems", or mentions Temporal SDK development.
+version: 0.2.0
 ---
 
 # Skill: temporal-developer
 
 ## Overview
 
-Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, and Go.
+Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, Go, and Java.
 
 ## Core Architecture
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     Temporal Cluster                            │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐  │
-│  │  Event History  │  │   Task Queues   │  │   Visibility   │  │
-│  │  (Durable Log)  │  │  (Work Router)  │  │   (Search)     │  │
-│  └─────────────────┘  └─────────────────┘  └────────────────┘  │
-└─────────────────────────────────────────────────────────────────┘
-                              ▲
-                              │ Poll / Complete
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                         Worker                                   │
-│  ┌─────────────────────────┐  ┌──────────────────────────────┐  │
-│  │   Workflow Definitions  │  │   Activity Implementations   │  │
-│  │   (Deterministic)       │  │   (Non-deterministic OK)     │  │
-│  └─────────────────────────┘  └──────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────┘
-```
+The **Temporal Cluster** is the central orchestration backend. It maintains three key subsystems: the **Event History** (a durable log of all workflow state), **Task Queues** (which route work to the right workers), and a **Visibility** store (for searching and listing workflows). There are three ways to run a Cluster:
+
+- **Temporal CLI dev server** — a local, single-process server started with `temporal server start-dev`. Suitable for development and testing only, not production.
+- **Self-hosted** — you deploy and manage the Temporal server and its dependencies (e.g., database) in your own infrastructure for production use.
+- **Temporal Cloud** — a fully managed production service operated by Temporal. No cluster infrastructure to manage.
+
+**Workers** are long-running processes that you run and manage. They poll Task Queues for work and execute your code. You might run a single Worker process on one machine during development, or run many Worker processes across a large fleet of machines in production. Each Worker hosts two types of code:
+
+- **Workflow Definitions** — durable, deterministic functions that orchestrate work. These must not have side effects.
+- **Activity Implementations** — non-deterministic operations (API calls, file I/O, etc.) that can fail and be retried.
 
-**Components:**
-- **Workflows** - Durable, deterministic functions that orchestrate activities
-- **Activities** - Non-deterministic operations (API calls, I/O) that can fail and retry
-- **Workers** - Long-running processes that poll task queues and execute code
-- **Task Queues** - Named queues connecting clients to workers
+Workers communicate with the Cluster via a poll/complete loop: they poll a Task Queue for tasks, execute the corresponding Workflow or Activity code, and report results back.
 
 ## History Replay: Why Determinism Matters
 
@@ -92,6 +79,7 @@ Once you've downloaded the file, extract the downloaded archive and add the temp
 1. First, read the getting started guide for the language you are working in:
     - Python -> read `references/python/python.md`
     - TypeScript -> read `references/typescript/typescript.md`
+    - Java -> read `references/java/java.md`
     - Go -> read `references/go/go.md`
 2. Second, read appropriate `core` and language-specific references for the task at hand.
 

references/core/determinism.md

@@ -76,10 +76,11 @@ In Temporal, activities are the primary mechanism for making non-deterministic c
 For a few simple cases, like timestamps, random values, UUIDs, etc. the Temporal SDK in your language may provide durable variants that are simple to use. See `references/{your_language}/determinism.md` for the language you are working in for more info.
 
 ## SDK Protection Mechanisms
-Each Temporal SDK language provides a protection mechanism to make it easier to catch non-determinism errors earlier in development:
+Each Temporal SDK language provides a different level of protection against non-determinism:
 
 - Python: The Python SDK runs workflows in a sandbox that intercepts and aborts non-deterministic calls early at runtime. 
 - TypeScript: The TypeScript SDK runs workflows in an isolated V8 sandbox, intercepting many common sources of non-determinism and replacing them automatically with deterministic variants.
+- Java: The Java SDK has no sandbox. Determinism is enforced by developer conventions — the SDK provides `Workflow.*` APIs as safe alternatives (e.g., `Workflow.sleep()` instead of `Thread.sleep()`), and non-determinism is only detected at replay time via `NonDeterministicException`. A static analysis tool (`temporal-workflowcheck`, beta) can catch violations at build time. Cooperative threading under a global lock eliminates the need for synchronization.
 - Go: The Go SDK has no runtime sandbox. Therefore, non-determinism bugs will never be immediately appararent, and are usually only observable during replay. The optional `workflowcheck` static analysis tool can be used to check for many sources of non-determinism at compile time.
 
 Regardless of which SDK you are using, it is your responsibility to ensure that workflow code does not contain sources of non-determinism. Use SDK-specific tools as well as replay tests for doing so.

references/core/error-reference.md

@@ -1,6 +1,6 @@
 # Common Error Types Reference
 
-| Error Type | Error identifier (if any) | Where to Find | What Happened | Recovery | Link to additional info (if any)
+| Error Type | Error identifier (if any) | Where to Find | What Happened | Recovery | Link to additional info (if any) |
 |------------|---------------|---------------|---------------|----------|----------|
 | **Non-determinism** | TMPRL1100 | `WorkflowTaskFailed` in history | Replay doesn't match history | Analyze error first. **If accidental**: fix code to match history → restart worker. **If intentional v2 change**: terminate → start fresh workflow. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1100.md |
 | **Deadlock** | TMPRL1101 | `WorkflowTaskFailed` in history, worker logs | Workflow blocked too long (deadlock detected) | Remove blocking operations from workflow code (no I/O, no sleep, no threading locks). Use Temporal primitives instead. | https://github.com/temporalio/rules/blob/main/rules/TMPRL1101.md |

references/core/patterns.md

@@ -253,9 +253,9 @@ To ensure that polling_activity is restarted in a timely manner, we make sure th
 
 **Implementation**:
 
-Define an Activty which fails (raises an exception) exactly when polling is not completed.
+Define an Activity which fails (raises an exception) exactly when polling is not completed.
 
-The polling loop is accomplised via activity retries, by setting the following Retry options:
+The polling loop is accomplished via activity retries, by setting the following Retry options:
 - backoff_coefficient: to 1
 - initial_interval: to the polling interval (e.g. 60 seconds)
 

references/core/troubleshooting.md

@@ -192,7 +192,7 @@ Timeout error?
 ├─▶ Which timeout?
 │   │
 │   ├─▶ Workflow timeout
-│   │   └─▶ Increase timeout or optimize workflow. Better yet, consider removing the workflow timeout, as it is generally discourged unless *necessary* for your use case.
+│   │   └─▶ Increase timeout or optimize workflow. Better yet, consider removing the workflow timeout, as it is generally discouraged unless *necessary* for your use case.
 │   │
 │   ├─▶ ScheduleToCloseTimeout
 │   │   └─▶ Activity taking too long overall (including retries)

references/go/determinism-protection.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Go SDK has no runtime sandbox. Determinism is enforced by **developer convention** and **optional static analysis**. Unlike the Python and TypeScript SDKs, the Go SDK will not intercept or replace non-deterministic calls at runtime. The Go SDK does perform a limited runtime command-ordering check, but catching non-deterministic code before deployment requires the `workflowcheck` tool and testing, in particular replay tests (see `references/go/testing`).
+The Go SDK has no runtime sandbox (only Python and TypeScript have sandboxing). Determinism is enforced by **developer convention** and **optional static analysis**. The Go SDK will not intercept or replace non-deterministic calls at runtime. The Go SDK does perform a limited runtime command-ordering check, but catching non-deterministic code before deployment requires the `workflowcheck` tool and testing, in particular replay tests (see `references/go/testing.md`).
 
 ## workflowcheck Static Analysis
 

references/go/go.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Temporal Go SDK (`go.temporal.io/sdk`) provides a strongly-typed, idiomatic Go approach to building durable workflows. Workflows are regular exported Go functions. The Go SDK does not have an automatic sandbox -- determinism is the developer's responsibility, aided by the `workflowcheck` static analysis tool.
+The Temporal Go SDK (`go.temporal.io/sdk`) provides a strongly-typed, idiomatic Go approach to building durable workflows. Workflows are regular exported Go functions.
 
 ## Quick Start
 
@@ -239,4 +239,4 @@ See `references/go/testing.md` for info on writing tests.
 - **`references/go/advanced-features.md`** - Schedules, worker tuning, and more
 - **`references/go/data-handling.md`** - Data converters, payload codecs, encryption
 - **`references/go/versioning.md`** - Patching API (`workflow.GetVersion`), Worker Versioning
-- **`references/python/determinism-protection.md`** - Information on **`workflowcheck`** tool to help statically check for determinism issues.
+- **`references/go/determinism-protection.md`** - Information on **`workflowcheck`** tool to help statically check for determinism issues.

references/java/advanced-features.md

@@ -0,0 +1,167 @@
+# Java SDK Advanced Features
+
+## Schedules
+
+Create recurring workflow executions.
+
+```java
+import io.temporal.client.schedules.*;
+
+ScheduleClient scheduleClient = ScheduleClient.newInstance(service);
+
+// Create a schedule
+String scheduleId = "daily-report";
+ScheduleHandle handle = scheduleClient.createSchedule(
+    scheduleId,
+    Schedule.newBuilder()
+        .setAction(
+            ScheduleActionStartWorkflow.newBuilder()
+                .setWorkflowType(DailyReportWorkflow.class)
+                .setOptions(
+                    WorkflowOptions.newBuilder()
+                        .setWorkflowId("daily-report")
+                        .setTaskQueue("reports")
+                        .build()
+                )
+                .build()
+        )
+        .setSpec(
+            ScheduleSpec.newBuilder()
+                .setIntervals(
+                    List.of(new ScheduleIntervalSpec(Duration.ofDays(1)))
+                )
+                .build()
+        )
+        .build(),
+    ScheduleOptions.newBuilder().build()
+);
+
+// Manage schedules
+ScheduleHandle scheduleHandle = scheduleClient.getHandle(scheduleId);
+scheduleHandle.pause("Maintenance window");
+scheduleHandle.unpause();
+scheduleHandle.trigger();  // Run immediately
+scheduleHandle.delete();
+```
+
+## Async Activity Completion
+
+For activities that complete asynchronously (e.g., human tasks, external callbacks).
+If you configure a heartbeat timeout on this activity, the external completer is responsible for sending heartbeats via the async handle.
+
+**Note:** If the external system can reliably Signal back with the result and doesn't need to Heartbeat or receive Cancellation, consider using **signals** instead.
+
+```java
+public class ApprovalActivitiesImpl implements ApprovalActivities {
+    @Override
+    public String requestApproval(String requestId) {
+        ActivityExecutionContext ctx = Activity.getExecutionContext();
+
+        // Get task token for async completion
+        byte[] taskToken = ctx.getTaskToken();
+
+        // Store task token for later completion (e.g., in database)
+        storeTaskToken(requestId, taskToken);
+
+        // Mark this activity as waiting for external completion
+        ctx.doNotCompleteOnReturn();
+
+        return null; // Return value is ignored
+    }
+}
+
+// Later, complete the activity from another process
+public void completeApproval(String requestId, boolean approved) {
+    WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
+    WorkflowClient client = WorkflowClient.newInstance(service);
+
+    ActivityCompletionClient completionClient = client.newActivityCompletionClient();
+
+    byte[] taskToken = getTaskToken(requestId);
+
+    if (approved) {
+        completionClient.complete(taskToken, "approved");
+    } else {
+        completionClient.completeExceptionally(
+            taskToken,
+            new RuntimeException("Rejected")
+        );
+    }
+}
+```
+
+## Worker Tuning
+
+Configure worker performance settings.
+
+```java
+WorkerOptions workerOptions = WorkerOptions.newBuilder()
+    // Max concurrent workflow task executions (default: 200)
+    .setMaxConcurrentWorkflowTaskExecutionSize(200)
+    // Max concurrent activity executions (default: 200)
+    .setMaxConcurrentActivityExecutionSize(200)
+    // Max concurrent local activity executions (default: 200)
+    .setMaxConcurrentLocalActivityExecutionSize(200)
+    // Max workflow task pollers (default: 5)
+    .setMaxConcurrentWorkflowTaskPollers(5)
+    // Max activity task pollers (default: 5)
+    .setMaxConcurrentActivityTaskPollers(5)
+    .build();
+
+WorkerFactory factory = WorkerFactory.newInstance(client);
+Worker worker = factory.newWorker("my-queue", workerOptions);
+worker.registerWorkflowImplementationTypes(MyWorkflowImpl.class);
+worker.registerActivitiesImplementations(new MyActivitiesImpl());
+factory.start();
+```
+
+## Workflow Failure Exception Types
+
+Control which exceptions cause workflow failures vs workflow task failures.
+
+By default, only `ApplicationFailure` (and its subclasses) fail the workflow execution. All other exceptions fail the **workflow task**, causing the task to retry indefinitely until the code is fixed or the workflow is terminated.
+
+### Per-Workflow Configuration
+
+Use `WorkflowImplementationOptions` to specify which exception types should fail the workflow:
+
+```java
+Worker worker = factory.newWorker("my-queue");
+worker.registerWorkflowImplementationTypes(
+    WorkflowImplementationOptions.newBuilder()
+        .setFailWorkflowExceptionTypes(
+            IllegalArgumentException.class,
+            CustomBusinessException.class
+        )
+        .build(),
+    MyWorkflowImpl.class
+);
+```
+
+With this configuration, `IllegalArgumentException` and `CustomBusinessException` thrown from the workflow will fail the workflow execution instead of just the workflow task.
+
+### Worker-Level Configuration
+
+Apply to all workflows registered on the worker:
+
+```java
+WorkerFactoryOptions factoryOptions = WorkerFactoryOptions.newBuilder()
+    .setWorkflowHostLocalTaskQueueScheduleToStartTimeout(Duration.ofSeconds(10))
+    .build();
+WorkerFactory factory = WorkerFactory.newInstance(client, factoryOptions);
+
+Worker worker = factory.newWorker("my-queue");
+// Register each workflow type with its own failure exception types
+worker.registerWorkflowImplementationTypes(
+    WorkflowImplementationOptions.newBuilder()
+        .setFailWorkflowExceptionTypes(
+            IllegalArgumentException.class,
+            CustomBusinessException.class
+        )
+        .build(),
+    MyWorkflowImpl.class,
+    AnotherWorkflowImpl.class
+);
+```
+
+- **Tip for testing:** Set `setFailWorkflowExceptionTypes(Throwable.class)` so any unhandled exception fails the workflow immediately rather than retrying the workflow task forever. This surfaces bugs faster.