Introduce addListener method in StepBuilder and JobBuilder for better clarity

[fmbenhassine]

Discussed in #5194

^{Originally posted by jon890 December 31, 2025}
First of all, I would like to express my sincere gratitude for your hard work in maintaining and evolving the Spring Batch framework.

Motivation

As a backend engineer heavily using Spring Batch with Java, I've observed that the current .listener() method in StepBuilder and JobBuilder can sometimes be ambiguous.

In the Spring ecosystem and general Java conventions, a method named after a property (without a prefix) often implies setting a single value, potentially overwriting previous ones. However, in Spring Batch, calling .listener() multiple times actually appends the listeners to an internal list rather than replacing them.

The Problem

The current naming doesn't explicitly communicate its "additive" behavior:

• Developers might mistakenly think that subsequent calls to .listener() will override previous ones.
• For those coming from other frameworks or standard Java Bean conventions, addListener is a more intuitive name for cumulative behavior.

Proposed Change

I suggest adding addListener() as an alias or a preferred method for adding listeners in the Fluent DSL.

// Current
public StepBuilder listener(StepExecutionListener listener) { ... }

// Proposed
public StepBuilder addListener(StepExecutionListener listener) {
    return listener(listener); // Delegate to the existing method
}

Benefits

• Improved Readability: addListener makes it clear that the listener is being added to a collection.
• API Consistency: It aligns with many other modern Java libraries where add* is used for collection-based properties and set* or the property name itself is used for single values.
• Self-Documenting Code : It reduces the need for developers to check the internal implementation or Javadoc to confirm if the method is additive.

Backward Compatibility

To maintain backward compatibility, the existing .listener() method should remain. We could potentially mark it as the secondary option or keep both to support different coding styles (Fluent vs. Explicit).

[nikitanagar08]

I would like to work on this issue to introduce addListener method in StepBuilder and JobBuilder. Let me read the discussion and requirements first.