spring-projects / spring-projects/spring-batch

Documentation request: introduce the Flow class before split()

Open Beginner friendly
#5,537 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

status: waiting-for-triage type: feature
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 Job that 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, the split element contains one or more flow elements, where
entire separate flows can be defined. A split element can also contain any of the
previously discussed transition elements, such as the next attribute or the next,
end, or fail elements.

@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:

  1. Is flow1 going to run until it completes then multiple flow2's will run in parallel?
    1. If this is what happens, what if flow2 had multiple steps in it? Would those multiple steps run sequentially or in parallel?
  2. Will flow1 and flow2 both run in parallel?
  3. etc.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.