sdk-java: add explicit client exceptions (#222)

Author: longquanzheng

.github/workflows/examples-java-ci.yml

@@ -40,63 +40,32 @@ jobs:
         working-directory: examples/java
     steps:
       - uses: actions/checkout@v7
-      - name: Start Dex environment
-        working-directory: sdk-java
-        env:
-          DEX_SERVER_IMAGE: superdurable/dex-server:latest
-        run: |
-          docker pull "$DEX_SERVER_IMAGE"
-          docker compose -f script/docker-compose.yml up -d
-      - name: Wait for Dex server
-        working-directory: ${{ github.workspace }}
-        run: |
-          set -euo pipefail
-          echo "Waiting for Elasticsearch..."
-          for i in $(seq 1 60); do
-            if docker exec temporal-elasticsearch-dex curl -fsS http://localhost:9200/_cluster/health >/dev/null 2>&1; then
-              echo "Elasticsearch ready (attempt $i)"
-              break
-            fi
-            if [ "$i" -eq 60 ]; then
-              echo "Timed out waiting for Elasticsearch"
-              docker logs temporal-elasticsearch-dex 2>&1 | tail -80 || true
-              exit 1
-            fi
-            sleep 5
-          done
-          echo "Waiting for search attributes..."
-          for i in $(seq 1 120); do
-            if docker logs temporal-admin-tools-dex 2>&1 | grep -q "All search attributes are registered"; then
-              echo "Search attributes ready (attempt $i)"
-              break
-            fi
-            if [ "$i" -eq 120 ]; then
-              echo "Timed out waiting for search attributes"
-              docker logs temporal-admin-tools-dex 2>&1 | tail -80 || true
-              docker logs temporal-dex 2>&1 | tail -80 || true
-              exit 1
-            fi
-            sleep 2
-          done
-          echo "Waiting for Dex healthcheck..."
-          for i in $(seq 1 90); do
-            if curl -fsS http://127.0.0.1:8801/info/healthcheck >/dev/null 2>&1; then
-              echo "Dex server healthy (attempt $i)"
-              exit 0
-            fi
-            sleep 5
-          done
-          echo "Timed out waiting for Dex server"
-          docker logs dex-server 2>&1 | tail -80 || true
-          exit 1
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: cli/go.mod
+          cache-dependency-path: |
+            cli/go.sum
+            server/go.sum
+            web/go.sum
+      - name: Install Temporal CLI runtime for dexcli dev
+        uses: temporalio/setup-temporal@v0
       - uses: actions/setup-java@v5
         with:
           distribution: zulu
           java-version: "17"
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v6
-      - name: Integration tests
-        run: ./gradlew test --tests 'io.superdurable.dex.integ.*' --info
-      - name: Dump docker logs
+      - name: Integration tests with dexcli dev
+        run: ./run-integration-tests.sh
+      - name: Upload service logs
         if: always()
-        run: bash "$GITHUB_WORKSPACE/.github/scripts/dump-docker-logs.sh"
+        uses: actions/upload-artifact@v7
+        with:
+          name: java-examples-integration-services
+          path: /tmp/test-java-examples-integration-services.log
+          if-no-files-found: ignore

examples/go/README.md

@@ -26,7 +26,7 @@ temporal --address 127.0.0.1:7233 operator search-attribute create \
 temporal --address 127.0.0.1:7233 operator search-attribute create \
   --name CustomKeywordField --type Keyword
 temporal --address 127.0.0.1:7233 operator search-attribute create \
-  --name CustomStringField --type Text
+  --name CustomTextField --type Text
 ```
 
 The defaults connect to Dex at `localhost:8801`. These environment variables override the local addresses:

examples/java/README.md

@@ -17,7 +17,7 @@ temporal --address 127.0.0.1:7233 operator search-attribute create \
 temporal --address 127.0.0.1:7233 operator search-attribute create \
   --name CustomKeywordField --type Keyword
 temporal --address 127.0.0.1:7233 operator search-attribute create \
-  --name CustomStringField --type Text
+  --name CustomTextField --type Text
 
 ./gradlew bootRun
 ```
@@ -26,6 +26,17 @@ Use JDK 17. Defaults connect to Dex at `localhost:8801`. Override with
 `DEX_FLOW_SERVICE_ADDRESS`, `DEX_WORKER_BIND_ADDRESS`, `DEX_WORKER_TARGET`,
 `DEX_BLOB_CACHE_DIR`.
 
+Run the integration suite against an isolated `dexcli dev` environment:
+
+```bash
+./run-integration-tests.sh
+```
+
+Examples catch concrete types from `io.superdurable.dex.exceptions`.
+`FlowNotFoundException` is for read operations with no matching execution;
+`FlowNotActiveException` is for RPC or mutation operations after a Flow closes.
+`ErrorSubStatus` remains diagnostic metadata and is not used for control flow.
+
 ## Product examples
 
 - [Money transfer](./src/main/java/io/superdurable/dex/workflow/money/transfer)

examples/java/run-integration-tests.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+
+# Copyright (c) 2022-2026 Super Durable, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+repo_root=$(cd "$script_dir/../.." && pwd)
+dex_port="${DEX_JAVA_EXAMPLES_DEX_PORT:-19803}"
+web_port="${DEX_JAVA_EXAMPLES_WEB_PORT:-19903}"
+temporal_port="${DEX_JAVA_EXAMPLES_TEMPORAL_PORT:-19235}"
+temporal_ui_port="${DEX_JAVA_EXAMPLES_TEMPORAL_UI_PORT:-19335}"
+dex_address="127.0.0.1:${dex_port}"
+temporal_address="127.0.0.1:${temporal_port}"
+log_file="/tmp/test-java-examples-integration-services.log"
+test_dir=$(mktemp -d)
+binary_dir=$(mktemp -d)
+dexcli_pid=""
+: >"$log_file"
+
+cleanup() {
+  status=$?
+  if [[ -n "$dexcli_pid" ]] && kill -0 "$dexcli_pid" 2>/dev/null; then
+    kill -TERM "$dexcli_pid"
+    wait "$dexcli_pid" || true
+  fi
+  if [[ "$status" -ne 0 ]]; then
+    cat "$log_file" >&2
+  fi
+  rm -r "$test_dir" "$binary_dir"
+}
+trap cleanup EXIT
+
+if [[ ! -f "$repo_root/web/assets/dist/index.html" ]]; then
+  (
+    cd "$repo_root/web"
+    npm ci
+    npm run build
+  )
+fi
+
+(
+  cd "$repo_root/cli"
+  GOWORK=off go build -trimpath -o "$binary_dir/dexcli" ./cmd/dexcli
+)
+
+"$binary_dir/dexcli" dev \
+  -bind-address 127.0.0.1 \
+  -dex-port "$dex_port" \
+  -web-port "$web_port" \
+  -temporal-port "$temporal_port" \
+  -temporal-ui-port "$temporal_ui_port" \
+  -temporal-db-filename "$test_dir/temporal.db" \
+  >>"$log_file" 2>&1 &
+dexcli_pid=$!
+
+temporal_ready=false
+for _ in {1..240}; do
+  if temporal --address "$temporal_address" operator search-attribute list >/dev/null 2>&1; then
+    temporal_ready=true
+    break
+  fi
+  if ! kill -0 "$dexcli_pid" 2>/dev/null; then
+    echo "dexcli exited before Temporal became ready" >&2
+    exit 1
+  fi
+  sleep 0.25
+done
+if ! $temporal_ready; then
+  echo "Temporal did not become ready" >&2
+  exit 1
+fi
+
+temporal --address "$temporal_address" operator search-attribute create --name CustomKeywordField --type Keyword
+temporal --address "$temporal_address" operator search-attribute create --name CustomTextField --type Text
+
+dex_ready=false
+for _ in {1..240}; do
+  if grep -q "Dex development environment is ready" "$log_file"; then
+    dex_ready=true
+    break
+  fi
+  if ! kill -0 "$dexcli_pid" 2>/dev/null; then
+    echo "dexcli exited before Dex became ready" >&2
+    exit 1
+  fi
+  sleep 0.25
+done
+if ! $dex_ready; then
+  echo "Dex did not become ready" >&2
+  exit 1
+fi
+
+cd "$script_dir"
+DEX_FLOW_SERVICE_ADDRESS="$dex_address" \
+  ./gradlew --include-build "$repo_root/sdk-java" \
+    test --tests 'io.superdurable.dex.integ.*' --info --no-daemon

examples/java/src/main/java/io/superdurable/dex/config/CronScheduleStarter.java

@@ -17,9 +17,8 @@
 package io.superdurable.dex.config;
 
 import io.superdurable.dex.Client;
-import io.superdurable.dex.DexException;
-import io.superdurable.dex.ErrorSubStatus;
 import io.superdurable.dex.StartFlowOptions;
+import io.superdurable.dex.exceptions.FlowAlreadyStartedException;
 import io.superdurable.dex.patterns.workflow.cron.CronScheduleFlow;
 import org.springframework.boot.context.event.ApplicationReadyEvent;
 import org.springframework.context.event.EventListener;
@@ -52,10 +51,7 @@ public void startCronSchedule() {
                             .timeout(Duration.ofHours(1))
                             .cronSchedule(CRON_EXPRESSION)
                             .build());
-        } catch (final DexException e) {
-            if (e.getSubStatus() != ErrorSubStatus.FLOW_ALREADY_STARTED) {
-                throw e;
-            }
+        } catch (final FlowAlreadyStartedException ignored) {
         }
     }
 }

examples/java/src/main/java/io/superdurable/dex/controller/ShortlistCandidatesController.java

@@ -17,8 +17,8 @@
 package io.superdurable.dex.controller;
 
 import io.superdurable.dex.Client;
-import io.superdurable.dex.DexException;
-import io.superdurable.dex.ErrorSubStatus;
+import io.superdurable.dex.exceptions.FlowAlreadyStartedException;
+import io.superdurable.dex.exceptions.FlowNotActiveException;
 import io.superdurable.dex.workflow.shortlistcandidates.EmployerOptInFlow;
 import io.superdurable.dex.workflow.shortlistcandidates.EmployerOptInInput;
 import io.superdurable.dex.workflow.shortlistcandidates.ShortlistFlow;
@@ -62,12 +62,9 @@ public ResponseEntity<String> optIn(@RequestBody final Map<String, String> reque
                     workflowId,
                     input,
                     ExampleFlows.startOptions());
-        } catch (final DexException e) {
-            if (e.getSubStatus() == ErrorSubStatus.FLOW_ALREADY_STARTED) {
-                return ResponseEntity.ok(
-                        String.format("Employer %s has already opted in", employerId));
-            }
-            throw e;
+        } catch (final FlowAlreadyStartedException alreadyStarted) {
+            return ResponseEntity.ok(
+                    String.format("Employer %s has already opted in", employerId));
         }
 
         return ResponseEntity.ok(String.format("Started workflowId: %s", workflowId));
@@ -81,12 +78,9 @@ public ResponseEntity<String> optOut(@RequestBody final Map<String, String> requ
                 client.newRpcStub(EmployerOptInFlow.class, workflowId);
         try {
             client.invokeRPC(stub::optOut);
-        } catch (final DexException e) {
-            if (e.getSubStatus() == ErrorSubStatus.FLOW_NOT_EXISTS) {
-                return ResponseEntity.ok(
-                        String.format("Employer %s is not in the opt-in status", employerId));
-            }
-            throw e;
+        } catch (final FlowNotActiveException inactive) {
+            return ResponseEntity.ok(
+                    String.format("Employer %s is not in the opt-in status", employerId));
         }
         return ResponseEntity.ok(String.format("Employer %s has opted out", employerId));
     }
@@ -118,12 +112,9 @@ public ResponseEntity<String> shortlist(@RequestBody final Map<String, String> r
                     workflowId,
                     input,
                     ExampleFlows.startOptions());
-        } catch (final DexException e) {
-            if (e.getSubStatus() == ErrorSubStatus.FLOW_ALREADY_STARTED) {
-                return ResponseEntity.ok(
-                        String.format("Already running workflowId: %s", workflowId));
-            }
-            throw e;
+        } catch (final FlowAlreadyStartedException alreadyStarted) {
+            return ResponseEntity.ok(
+                    String.format("Already running workflowId: %s", workflowId));
         }
 
         return ResponseEntity.ok(String.format("Started workflowId: %s", workflowId));
@@ -138,13 +129,10 @@ public ResponseEntity<String> revokeShortlist(
 
         try {
             client.publish(workflowId, shortlistFlow.revokeShortlist, (Void) null);
-        } catch (final DexException e) {
-            if (e.getSubStatus() == ErrorSubStatus.FLOW_NOT_EXISTS) {
-                return ResponseEntity.ok(String.format(
-                        "No running workflow to revoke for %s",
-                        employerId + "-" + candidateId));
-            }
-            throw e;
+        } catch (final FlowNotActiveException inactive) {
+            return ResponseEntity.ok(String.format(
+                    "No running workflow to revoke for %s",
+                    employerId + "-" + candidateId));
         }
 
         return ResponseEntity.ok(String.format(
@@ -160,11 +148,8 @@ public ResponseEntity<Long> getEmailSentTimestamp(
         final ShortlistFlow stub = client.newRpcStub(ShortlistFlow.class, workflowId);
         try {
             return ResponseEntity.ok(client.invokeRPC(stub::getEmailSentTimestamp));
-        } catch (final DexException e) {
-            if (e.getSubStatus() == ErrorSubStatus.FLOW_NOT_EXISTS) {
-                return ResponseEntity.notFound().build();
-            }
-            throw e;
+        } catch (final FlowNotActiveException inactive) {
+            return ResponseEntity.notFound().build();
         }
     }
 }

examples/java/src/main/java/io/superdurable/dex/controller/SignupWorkflowController.java

@@ -17,8 +17,7 @@
 package io.superdurable.dex.controller;
 
 import io.superdurable.dex.Client;
-import io.superdurable.dex.DexException;
-import io.superdurable.dex.ErrorSubStatus;
+import io.superdurable.dex.exceptions.FlowAlreadyStartedException;
 import io.superdurable.dex.workflow.signup.SignupForm;
 import io.superdurable.dex.workflow.signup.UserSignupFlow;
 import org.springframework.http.ResponseEntity;
@@ -47,11 +46,8 @@ public ResponseEntity<String> submit(
         final SignupForm form = new SignupForm(username, email, "Test", "Test");
         try {
             client.startFlow(flow, username, form, ExampleFlows.startOptions());
-        } catch (final DexException exception) {
-            if (exception.getSubStatus() == ErrorSubStatus.FLOW_ALREADY_STARTED) {
-                return ResponseEntity.ok("username already started registry");
-            }
-            throw exception;
+        } catch (final FlowAlreadyStartedException alreadyStarted) {
+            return ResponseEntity.ok("username already started registry");
         }
         return ResponseEntity.ok("success");
     }