skip to content

In a production design, when is JobStep-based nested-job composition appropriate, and what identity/restart pitfalls must you guard against?

level: principalimportance: should knowfreq 30%

answer

  1. JobStep = orchestrate independent child jobs
  2. Unique identifying param or JobInstanceAlreadyCompleteException
  3. Two restart boundaries (parent + child)
  4. No shared transaction / not atomic across parent+child
  5. Synchronous launcher; consider external orchestration instead

basics

~20 s

Use JobStep to orchestrate independently-runnable child jobs from a parent. Guard against duplicate identifying parameters (JobInstanceAlreadyCompleteException), reason about two separate restart boundaries, ensure the extractor forwards a unique run id, and confirm the launcher/isolation model fits.

solid answer

~50 s

JobStep nesting is appropriate when you must orchestrate a **child job that is legitimately its own unit** — independently runnable, separately parameterized, with its own restart boundary and metadata — from a parent "master" job. It shines for reusing existing standalone jobs and for building modular master jobs. The pitfalls to design around: (1) **Identity** — each child run creates a real `JobInstance`; if the `JobParametersExtractor` yields identical identifying parameters, re-runs throw `JobInstanceAlreadyCompleteException`/`JobRestartException`, so forward a unique identifying key (e.g. a `runId`/timestamp). (2) **Restart reasoning spans two instances** — restarting the parent restarts the JobStep, which resumes/re-launches the child per the child's own metadata; you must reason about both. (3) **Isolation** — the child runs in its own executions/transactions; the parent step is not a single transaction over the child. (4) **Launcher semantics** — use a synchronous launcher so the step blocks on the child. If you only need step reuse, prefer FlowStep; if you need true decoupling, an external scheduler/messaging may beat in-batch nesting.

code

java · 21 lines
java
// Forward a UNIQUE runId so the child instance can run on every parent run,
// avoiding JobInstanceAlreadyCompleteException.
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.StepExecution;
import org.springframework.batch.core.step.job.JobParametersExtractor;
import org.springframework.batch.core.JobParametersBuilder;

public class RunIdParametersExtractor implements JobParametersExtractor {

    @Override
    public JobParameters getJobParameters(org.springframework.batch.core.Job job,
                                          StepExecution stepExecution) {
        Object inputFile = stepExecution.getJobExecution()
                .getExecutionContext().get("inputFile");
        return new JobParametersBuilder()
                .addString("inputFile", String.valueOf(inputFile))
                // identifying + unique -> new child JobInstance each run
                .addLong("runId", System.currentTimeMillis(), true)
                .toJobParameters();
    }
}

go deeper

for a junior

Likely only aware JobStep nests a job; trade-offs out of scope.

for a middle

Knows the separate-execution fact and that parameters come from an extractor, but may miss the restart/identity pitfalls.

for a senior

Articulates the duplicate-parameter and status-propagation pitfalls and picks FlowStep vs JobStep correctly.

for a principal

Weighs identity/restart/isolation costs, designs the extractor for correct restart, and knows when external orchestration beats in-batch nesting.

## When nested-job composition earns its keep `JobStep` lets a parent `Job` run a child `Job` as one step. In production it is the right tool when the child is genuinely its **own unit of work**: - An **existing standalone job** (e.g. `reconciliationJob`) that ops can also run alone, but which should also run as phase 2 of a nightly `masterJob`. - A **modular master job** assembled from independently owned/tested child jobs, each with its own parameters and restart semantics. - Cases where you want the child to have a **separate restart boundary** so a failed child can be restarted/inspected as its own execution. If you only need to reuse a *sequence of steps* within one execution, `FlowStep` is simpler and cheaper — do not reach for JobStep just for modularity. ## Pitfall 1 — Job identity and duplicate parameters Every child launch creates a real `JobInstance`, identified by its **identifying `JobParameters`**. Spring Batch forbids re-running an already-`COMPLETED` instance: a duplicate set throws **`JobInstanceAlreadyCompleteException`**; an incomplete/failed one may throw `JobRestartException` depending on state. The child's parameters come from a **`JobParametersExtractor`** (commonly `DefaultJobParametersExtractor` with configured `keys`). Design the extractor to forward a **unique identifying parameter** (e.g. a `runId`, execution timestamp, or business date) when the child should be runnable repeatedly. Conversely, if idempotent re-run detection is desired, deliberately keep the identifying key stable. ## Pitfall 2 — Two restart boundaries Restart no longer reasons about one execution. Restarting the **parent** restarts the JobStep; the JobStep then resumes or re-launches the **child** according to the child's own restart metadata and parameters. You must think about *both* instances: which parent execution is restarting, and what child instance/parameters the extractor produces on that restart. A subtle bug is an extractor that generates a *new* runId on restart, causing the child to start fresh instead of resuming. ## Pitfall 3 — Isolation / transactions The child runs in its **own executions and transactions**; the JobStep is **not** a single transaction wrapping the child. Do not assume atomic rollback across parent and child. Side effects committed by the child persist even if a later parent step fails. Design compensations accordingly. ## Pitfall 4 — Launcher semantics and threading Supply a `JobLauncher` explicitly via `.launcher(...)`. A **synchronous** launcher (the JobStep blocks until the child finishes) is almost always what you want inside a step; an asynchronous launcher would return before the child completes, breaking the step's status derivation. Watch for thread/`JobRepository` contention when nesting many jobs. ## Pitfall 5 — Status propagation and branching The JobStep's `StepExecution` status derives from the child `JobExecution`. Decide how the parent should react: default is that a failed child fails the JobStep and the parent job; use transitions (`.on(...).to(...)`) if you want to branch or continue on specific child outcomes. ## Alternatives to weigh - **FlowStep** — for pure intra-job step reuse (no separate identity/params). - **Split/parallel** — for concurrency (a different concern). - **External orchestration** (scheduler like a workflow engine, or event/message-driven triggering) — when child jobs should be fully decoupled, independently scaled, or triggered across services rather than nested in one JVM job. In-batch JobStep couples lifecycle and JVM; sometimes decoupling is the better architecture. ## Summary judgment JobStep is powerful for modular master jobs but doubles the identity/restart/metadata surface. Use it when the child truly deserves its own identity; otherwise prefer FlowStep, and consider external orchestration when decoupling outweighs the convenience of nesting.

  • Why can a bug in the JobParametersExtractor break restart of a nested child job?
    If the extractor mints a new unique runId on the parent restart, the child gets a brand-new JobInstance and starts fresh instead of resuming its prior failed instance. Restart correctness depends on the extractor producing stable identifying parameters when resumption is intended.
  • Is a parent JobStep a transactional boundary over the child job?
    No. The child runs in its own executions/transactions and commits independently. A later parent failure does not roll back the child's committed work, so you need explicit compensation if atomicity is required.
  • When would you avoid JobStep and use external orchestration instead?
    When child jobs should be fully decoupled — independently deployed, scaled, or triggered across services/JVMs. Nesting couples lifecycle into one job/JVM; a workflow engine or event-driven trigger gives cleaner isolation and operational control.

saying these in an interview costs you the question

  • Assuming parent and child share a transaction / atomic rollback
  • Ignoring JobInstanceAlreadyCompleteException from duplicate identifying params
  • Using an async launcher inside a JobStep and expecting correct status
  • Treating JobStep as free modularity when FlowStep would suffice
  • Not realizing restart spans two separate instances

context

resolving links…