What do the terminal transitions `end()`, `fail()`, and `stop()` do at the end of an `on(...)` transition, and how do they differ for restart?

## Terminal vs. non-terminal transitions A transition begins with `on(pattern)`. It then either **continues** the flow with `.to(step)` / `.stopAndRestart(step)` or **terminates** the flow with one of three terminal instructions: ### `end()` — successful completion Sets the job's BatchStatus to **COMPLETED**. The flow stops here and the job is a success. `end()` with no argument uses exit code "COMPLETED"; `end("MY_CODE")` sets a custom exit code on the job. Because the job is COMPLETED, restarting it with the *same identifying job parameters* is rejected (a completed job instance can't rerun) — this is the normal "done" outcome. ### `fail()` — force failure Sets BatchStatus to **FAILED**. Use it when a branch represents an error you want to surface as a failed job even though no exception was thrown (e.g., a validation step exits "INVALID" and you route `on("INVALID").fail()`). A FAILED job **is restartable**: rerunning the same job instance resumes and re-runs the parts that didn't complete. ### `stop()` — pause / halt Sets BatchStatus to **STOPPED**. The job halts cleanly (not an error). It is restartable. Two important forms: - `stop()` — plain stop; on restart the flow resumes normally. - `stopAndRestart(restartStep)` (builder method) / conceptually `stop().and(...)` — records that a subsequent restart should resume at `restartStep` rather than the default point. This models "pause here for a manual step or approval, then resume at a known place." ## Where they attach ```java job.start(validate) .on("INVALID").fail() // whole job FAILED .from(validate).on("NEEDS_REVIEW").stopAndRestart(review) // pause, resume at review .from(validate).on("*").to(process) // continue .from(process).on("*").end() // COMPLETED .build(); ``` ## `end()` overload nuance Inside a flow, `.end()` appears in two roles: 1. **`.on(x).end()`** — a *terminal transition* completing the job. 2. **`.end()` right after `.to(...)`/`.from(...)` chaining** — the `FlowBuilder`/`JobBuilder` call that *closes the flow definition* and returns something buildable. They are different methods with different receivers; context tells them apart. This overloading trips people up. ## Restart summary table | Terminal | BatchStatus | Restartable? | On restart | |---|---|---|---| | `end()` | COMPLETED | No (same params) | n/a | | `fail()` | FAILED | Yes | re-runs uncompleted parts | | `stop()` | STOPPED | Yes | resumes; `stopAndRestart` picks the resume step | ## When to use which - **`end()`**: a branch is a legitimate successful ending (e.g., "no data, nothing to do — done"). - **`fail()`**: a branch means the job genuinely failed and should be retried later. - **`stop()` / `stopAndRestart`**: you need a human or external trigger before continuing; pause without marking failure. ## Gotchas - Don't confuse `stop()` the transition with `JobOperator.stop(executionId)` (a runtime, out-of-band stop). The transition is declarative flow design. - `fail()` produces FAILED without an exception in logs, which can confuse ops — document why. - A job whose only completing branch is `fail()` will never be COMPLETED; make sure a success path exists.