Introduction

In Spring Batch, beforeStep not firing is a common surprise when introducing AsyncItemProcessor. The root issue is lifecycle ownership: listeners are invoked on components registered directly with the step, while AsyncItemProcessor wraps execution and can obscure where callbacks occur. Developers often implement StepExecutionListener on their delegate processor and expect it to run automatically, but the delegate may never be registered as a listener bean for that step. The result is missing step context, null state, or initialization logic that never executes. This guide explains the listener lifecycle and shows safe wiring patterns for async processing.

Core Sections

1. Understand where listeners are invoked

beforeStep and afterStep are step lifecycle callbacks. They run when the step starts/ends, not per item. If your processor is wrapped by AsyncItemProcessor, lifecycle callbacks still depend on step registration.

If the delegate implements StepExecutionListener, ensure it is explicitly attached:

1@Bean
2public Step importStep(JobRepository jobRepository,
3                       PlatformTransactionManager tx,
4                       ItemReader<Input> reader,
5                       ItemWriter<Output> writer,
6                       StepExecutionListener processorListener) {
7    return new StepBuilder("importStep", jobRepository)
8            .<Input, Future<Output>>chunk(100, tx)
9            .reader(reader)
10            .processor(asyncProcessor())
11            .writer(asyncWriter(writer))
12            .listener(processorListener)
13            .build();
14}

2. Prefer a dedicated listener bean

Instead of embedding lifecycle logic inside the delegate processor, create a dedicated listener. This avoids confusion between item processing and step lifecycle.

1@Component
2public class ImportStepListener implements StepExecutionListener {
3    @Override
4    public void beforeStep(StepExecution stepExecution) {
5        stepExecution.getExecutionContext().putString("batchStart", "ready");
6    }
7}

Register this listener directly on the step. Keep async delegate focused only on item transformation.

3. Configure AsyncItemProcessor correctly

A minimal async processor setup:

1@Bean
2public AsyncItemProcessor<Input, Output> asyncProcessor(ItemProcessor<Input, Output> delegate,
3                                                         TaskExecutor taskExecutor) {
4    AsyncItemProcessor<Input, Output> p = new AsyncItemProcessor<>();
5    p.setDelegate(delegate);
6    p.setTaskExecutor(taskExecutor);
7    return p;
8}

Remember: delegate code runs on worker threads. Step lifecycle callbacks run on step orchestration flow, so shared mutable state requires thread-safe design.

4. Logging and diagnosis

Add logs to beforeStep, delegate process, and writer to verify execution order and thread names.

log.info("beforeStep thread={}", Thread.currentThread().getName());

If beforeStep never logs, the listener was not registered on that step. If it logs but state is missing in delegate, you likely have thread visibility or scoping issues.

5. Context propagation strategy

Do not rely on thread-local state for data needed by async workers. Put immutable step data in ExecutionContext, copy required values into item payloads, or use scoped beans carefully.

Validation and production readiness

A reliable implementation should include more than a working snippet. Add a small reproducible dataset or input fixture that exercises expected behavior and edge cases, then codify it in automated tests. Include at least one “happy path,” one malformed input case, and one boundary condition so regressions are caught early. Instrument key steps with structured logs or metrics to make failures diagnosable in runtime environments, not just local development. If performance is relevant, keep a lightweight benchmark that can be rerun after refactors to ensure behavior stays within budget.

Operationally, document assumptions near the code: required library versions, environment variables, timezone/locale expectations, and failure handling strategy. For team workflows, add one integration test that mirrors real usage rather than only unit-level checks. This reduces drift between example code and production behavior. Treat these checks as part of feature completion, because most long-term issues are caused by unvalidated assumptions rather than syntax errors.

Common Pitfalls

• Implementing StepExecutionListener on a delegate and assuming automatic step registration.
• Mixing step lifecycle logic into async item processing classes.
• Using thread-local variables that do not propagate to worker threads.
• Expecting beforeStep to run once per item instead of once per step.
• Forgetting to validate configuration by logging listener invocation paths.

Summary

When beforeStep is not called with AsyncItemProcessor, the problem is usually registration and lifecycle boundaries, not async execution itself. Register listeners explicitly on the step, separate lifecycle code from delegate processing, and design context sharing for multi-threaded execution. With this setup, async batch jobs remain predictable and easier to debug.