diff --git a/spring-batch-docs/asciidoc/step.adoc b/spring-batch-docs/asciidoc/step.adoc index c3dd74ecf7..29279b1678 100644 --- a/spring-batch-docs/asciidoc/step.adoc +++ b/spring-batch-docs/asciidoc/step.adoc @@ -2510,3 +2510,27 @@ or partitioned steps. Spring Batch does not control the threads spawned in these use cases, so it is not possible to set them up correctly to use such beans. Hence, it is not recommended to use job-scoped beans in multi-threaded or partitioned steps. ==== + +[[scoping-item-streams]] +==== Scoping `ItemStream` components + +When using the Java configuration style to define job or step scoped `ItemStream` beans, +the return type of the bean definition method should be at least `ItemStream`. This is required +so that Spring Batch correctly creates a proxy that implements this interface, and therefore +honors its contract by calling `open`, `update` and `close` methods as expected. + +It is recommended to make the bean definition method of such beans return the most specific +known implementation, as shown in the following example: + +.Define a step-scoped bean with the most specific return type +[source, java] +---- +@Bean +@StepScope +public FlatFileItemReader flatFileItemReader(@Value("#{jobParameters['input.file.name']}") String name) { + return new FlatFileItemReaderBuilder() + .resource(new FileSystemResource(name)) + // set other properties of the item reader + .build(); +} +----