Skip to content

docs: add Chunk Scanning documentation to fault-tolerant step section#5422

Open
won-seoop wants to merge 1 commit into
spring-projects:mainfrom
won-seoop:doc-3946-chunk-scanning
Open

docs: add Chunk Scanning documentation to fault-tolerant step section#5422
won-seoop wants to merge 1 commit into
spring-projects:mainfrom
won-seoop:doc-3946-chunk-scanning

Conversation

@won-seoop

Copy link
Copy Markdown
Contributor

Summary

Closes #3946

The existing fault-tolerant step documentation (configuring-skip and retry-logic) did not explain chunk scanning, which is the mechanism Spring Batch uses to identify which individual item caused a write failure. This caused confusion: users who set NeverRetryPolicy expected no re-processing to occur, but were surprised when Spring Batch still re-invoked their processor multiple times per chunk.

Changes

Added a new chunk-scanning.adoc page (linked in nav after retry-logic.adoc) covering:

  1. How chunk scanning works: on a write exception → rollback → re-process each item individually → skip or fail per-item based on skip policy
  2. Key insight: chunk scanning is triggered regardless of retry policy (even with NeverRetryPolicy)
  3. Impact on ItemProcessor: the processor is re-invoked for each scanned item; use processorNonTransactional() to avoid this (with Java and XML examples)
  4. Relationship to skip and retry: these three mechanisms are orthogonal — chunk scanning enables per-item skip; retry operates within the scan phase

Also added:

  • Nav entry in nav.adoc after retry-logic.adoc
  • A NOTE cross-reference at the bottom of configuring-skip.adoc pointing to the new page

Test plan

  • Docs build with Antora renders new page and nav entry correctly
  • Cross-reference link in configuring-skip.adoc resolves
  • Java/XML examples are syntactically correct

spring-projectsGH-3946: The configuring-skip and retry-logic sections did not document
chunk scanning, which is the mechanism Spring Batch uses to identify failing
items when a write exception occurs in a fault-tolerant step. This led to
users being surprised that items are re-processed even when NeverRetryPolicy
is configured.

Added a new chunk-scanning.adoc page covering:
- How chunk scanning works (rollback → one-by-one scan → skip/fail)
- Why it is triggered regardless of retry policy
- Impact on the ItemProcessor and how processorNonTransactional() helps
- Relationship between chunk scanning, skip, and retry

Also added:
- Entry in nav.adoc after retry-logic.adoc
- NOTE cross-reference in configuring-skip.adoc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve documentation with regard to chunk scanning

1 participant