spring-projects / spring-projects/spring-batch
Documentation request: introduce the Flow class before split()
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 3k
- Forks
- 2.5k
- Avg merge
- 6d 53m
- Merged PRs (30d)
- 3
Description
Expected Behavior
After reading the Split Flows section, I understand the separation of the Flow class from split behavior. I also understand which steps run in parallel in the given example.
Current Behavior
After reading the Split Flow section, I thought the Flow class was needed for parallelism; I didn't realize the Flow class was being implicitly used the entire time.
I also don't know what the example (included below) parallelizes. Is it flow1, flow2, step1, step2, step3, and/or step4? What impact does add have? How does it relate to next? This feels like the first part of the entire documentation that is introducing code that isn't explained anywhere.
I'm starting to wonder if https://docs.spring.io/spring-batch/reference/step/controlling-flow.html#external-flows was intended to appear earlier on the page. Maybe that's a documentation bug?
Context
Every scenario described so far has involved a
Jobthat executes its steps one at a
time in a linear fashion. In addition to this typical style, Spring Batch also allows
for a job to be configured with parallel flows.Java-based configuration lets you configure splits through the provided builders. As the
following example shows, thesplitelement contains one or moreflowelements, where
entire separate flows can be defined. Asplitelement can also contain any of the
previously discussed transition elements, such as thenextattribute or thenext,
end, orfailelements.@Bean public Flow flow1(Step step1, Step step2) { return new FlowBuilder<SimpleFlow>("flow1") .start(step1) .next(step2) .build(); } @Bean public Flow flow2(Step step3) { return new FlowBuilder<SimpleFlow>("flow2") .start(step3) .build(); } @Bean public Job job(JobRepository jobRepository, Flow flow1, Flow flow2, Step step4) { return new JobBuilder("job", jobRepository) .start(flow1) .split(new SimpleAsyncTaskExecutor()) .add(flow2) .next(step4) .end() .build(); }
I don't know what is going to happen in this example:
- Is flow1 going to run until it completes then multiple flow2's will run in parallel?
- If this is what happens, what if flow2 had multiple steps in it? Would those multiple steps run sequentially or in parallel?
- Will flow1 and flow2 both run in parallel?
- etc.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Split Flows and external-flows sections in docs.spring.io/spring-batch/reference/step/controlling-flow.html, including the Java configuration example. Explain the Flow class before the split() section, then clarify what flow1, flow2, step4, add, and next represent and when they execute. Done means a reader can follow the example and understand which flows and steps run in parallel.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100