Launching, Parameters & Metadata

JobLauncher is the interface that starts a batch Job. You call jobLauncher.run(job, jobParameters). It returns a JobExecution describing that run (status, id, timestamps).

JobOperator is an operations-facing facade for controlling jobs — start, stop, restart, and abandon executions using simple types like job names and execution ids. JobLauncher just runs a Job you already have wired.

JobParameters are typed key/value inputs passed to a job at launch (Strings, Longs, Doubles, Dates). You build them with JobParametersBuilder and pass them to JobLauncher.run(job, params).

The JobRepository is the component that saves batch execution state to a database. It records which jobs and steps ran, their status, timestamps, and parameters, so a job can be tracked and restarted.

Restarting means re-running a job that previously FAILED or STOPPED. Spring Batch reuses the same JobInstance (same identifying parameters) and continues where it left off instead of starting from scratch. A COMPLETED job cannot normally be restarted.

@StepScope is a custom Spring scope where a new bean instance is created for each step run. You use it so a reader or writer can pick up values (like job parameters) that only exist when the job actually runs, not at startup.

Add a JobParametersIncrementer, such as RunIdIncrementer, so each launch gets a new identifying parameter (like run.id). That makes every launch a new JobInstance, so the completed-instance guard never triggers.

By default run() is blocking: TaskExecutorJobLauncher uses a SyncTaskExecutor, so it runs the job in the caller thread and returns only when it finishes. Give the launcher an async TaskExecutor to make run() return immediately.

Identifying parameters (the default) contribute to a JobInstance's identity — the same set means the same instance. Non-identifying parameters are ignored when computing identity, so you can change them without creating a new instance.

Spring Batch ships DDL scripts named schema-<database>.sql inside its jar. Spring Boot runs the right one automatically based on spring.batch.jdbc.initialize-schema. @EnableBatchProcessing wires up the batch infrastructure (JobRepository, etc.).

Each committed chunk saves progress (like the current read position) into the step's persisted ExecutionContext. On restart, the reader is re-opened and reads that saved state, so processing continues from just after the last successfully committed chunk instead of the beginning.

You inject runtime values with SpEL like @Value("#{jobParameters['x']}") on a bean annotated @StepScope or @JobScope. Spring resolves the expression when the step/job runs instead of at startup. Available roots include jobParameters, stepExecutionContext, and jobExecutionContext.

stop asks a running execution to halt gracefully — it sets the status to STOPPING and the job stops at the next safe point, ending STOPPED. abandon marks a non-running execution as ABANDONED so it's skipped on restart. stop is cooperative, not a kill.

Boot registers a JobLauncherApplicationRunner that, after the context starts, calls JobLauncher.run() on the Job beans it finds. It's on by default; set spring.batch.job.enabled=false to disable, or spring.batch.job.name to pick a specific job.

startNextInstance runs a new instance of a job automatically. It uses the job's JobParametersIncrementer to derive the next parameters from the previous run — for example bumping a run.id counter — so each call is a distinct JobInstance.

A JobParametersIncrementer generates the next set of JobParameters from the previous run, typically by bumping an identifying run.id. RunIdIncrementer is the built-in one. It lets you re-run the same job repeatedly without a JobInstanceAlreadyComplete error.

Setting a job's restartable property to false marks it as run-once-per-instance. If its execution fails and you relaunch with the same identifying parameters, Spring Batch refuses and throws JobRestartException instead of resuming.

On restart after a failure, Spring Batch re-reads and re-writes the chunk that was in flight when the job crashed, so a writer can see the same items twice. Making writes upserts (insert-or-update on a key) keeps re-runs safe.

run() throws four checked exceptions: JobExecutionAlreadyRunningException, JobRestartException, JobInstanceAlreadyCompleteException, and JobParametersInvalidException. They signal that the run couldn't even start because of the job's identity, state, or bad parameters.

getRunningExecutions(jobName) returns the ids of executions currently in flight for that job, so you can avoid launching overlapping runs. restart(executionId) re-runs a failed or stopped execution of the same instance, picking up per its restart semantics.

Same identifying parameters as a failed run means restart: Spring Batch finds the incomplete JobInstance and resumes it. Different identifying parameters (or an incremented run.id) means a brand-new JobInstance that starts from scratch.

One JobInstance (name + identifying params) has many JobExecutions (one per attempt). Each JobExecution has many StepExecutions. ExecutionContext rows store saved state per job and per step. On restart, Spring reuses the instance and reloads the ExecutionContext to resume.

When starting a job, the repository first checks whether an instance/execution already exists, then inserts one. It uses SERIALIZABLE isolation so two launchers can't both create the same JobInstance at once. You lower it only if your DB struggles with SERIALIZABLE.

startLimit caps how many times a step may be started across all executions of a JobInstance (default effectively unlimited); exceeding it fails with StartLimitExceededException. allowStartIfComplete=true forces a step that already COMPLETED to run again on every restart instead of being skipped.

Use @JobScope when a bean must live for the whole job (across steps); use @StepScope when it's per step or needs the step's ExecutionContext. Both can read jobParameters and jobExecutionContext, but only @StepScope can read stepExecutionContext.

Spring injects a scoped proxy, not the real bean. The singleton Step holds this proxy; on each method call the proxy looks up the real step-scoped instance bound to the currently running step and delegates to it. That deferral is what makes late binding possible.

Key the job by business date (identifying param). Same date + completed = rejected (no double-run); same date + failed = restart and resume. Make writers idempotent via upserts so replayed chunks never double-post. Reserve an incrementer only for deliberately advancing to a new date.

Don't use the default blocking launcher on an HTTP thread. Configure a TaskExecutorJobLauncher with a bounded ThreadPoolTaskExecutor so run() returns immediately with an execution id; the client polls a status endpoint that reads the JobRepository.

The 'scope not active' error means the step-scoped bean was touched when no StepExecution was bound to the thread — e.g. in @PostConstruct, from another thread, or before launching. Stale parameters usually mean the bean isn't actually @StepScope (a singleton captured the value once), or state leaked because the instance was shared.