Update documentation to remind how JobParameters should be specified

[mminella]

Per the Spring Boot documentation for passing command line args, the convention is to use two dashes before the name of a property: --foo=bar.

When those values are passed to Spring Batch, only the first dash is removed. This leaves the value being passed to the job as a job parameter as -foo=bar. The issue here is that the dash at the front of foo actually has a material impact on it's meaning within Spring Batch. The preceding dash indicates that the job parameter should not be considered identifying (meaning it doesn't contribute to the determination if this is the same JobInstance or not).

The only way to get this to work correctly is to leave off the dashes completely which is counter intuitive if you're reading the Spring Boot documentation. Can we get a blurb added in the batch section to indicate that the way to pass identifying job parameters to a job is without the dashes? I can provide a sample app that demonstrates the issue if that is useful.

[snicoll]

I can provide a sample app that demonstrates the issue if that is useful.

Yes please. This app works for me and I'd be curious to understand what pieces is removing "only a dash"

@SpringBootApplication
public class DemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

	@Bean
	public ApplicationRunner applicationRunner() {
		return args -> {
			args.getOptionNames().forEach(n -> System.out.println(String.format(
					"Param %s -> %s", n, args.getOptionValues(n))));
		};
	}
}

java -jar demo-0.0.1-SNAPSHOT.jar --foo=bar --blup=blip gives

Param foo -> [bar]
Param blup -> [blip]

[mminella]

Do keep in mind that jobs are run via a CommandLineRunner and not an ApplicationRunner and per the code (SpringApplication), they receive command line args differently. Below is the code:

package com.example.demo;

import java.util.ArrayList;
import java.util.List;

import org.springframework.batch.core.Job;
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.StepContribution;
import org.springframework.batch.core.configuration.annotation.EnableBatchProcessing;
import org.springframework.batch.core.configuration.annotation.JobBuilderFactory;
import org.springframework.batch.core.configuration.annotation.StepBuilderFactory;
import org.springframework.batch.core.scope.context.ChunkContext;
import org.springframework.batch.core.step.tasklet.Tasklet;
import org.springframework.batch.repeat.RepeatStatus;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@EnableBatchProcessing
@SpringBootApplication
public class DemoApplication {

	@Autowired
	private JobBuilderFactory jobBuilderFactory;

	@Autowired
	private StepBuilderFactory stepBuilderFactory;

	public static void main(String[] args) {
		List<String> fauxArgs = new ArrayList<>(1);
		fauxArgs.add("--foo=bar");
		fauxArgs.add("-baz=quix");
		fauxArgs.add("spring=batch");

		SpringApplication.run(DemoApplication.class, fauxArgs.toArray(new String[2]));
	}

	@Bean
	public Job job() {
		return this.jobBuilderFactory.get("wonky")
				.start(this.stepBuilderFactory.get("stepq")
				.tasklet(new Tasklet() {
					@Override
					public RepeatStatus execute(StepContribution contribution, ChunkContext chunkContext) throws Exception {
						JobParameters jobParameters = chunkContext.getStepContext().getStepExecution().getJobExecution().getJobParameters();
						System.out.println(">> foo = " + jobParameters.getString("foo"));
						System.out.println(">> -foo = " + jobParameters.getString("-foo"));
						System.out.println(">> is -foo identifying = " + jobParameters.getParameters().get("-foo").isIdentifying());
						System.out.println(">> baz = " + jobParameters.getString("baz"));
						System.out.println(">> is baz identifying = " + jobParameters.getParameters().get("baz").isIdentifying());
						System.out.println(">> -baz = " + jobParameters.getString("-baz"));
						System.out.println(">> spring = " + jobParameters.getString("spring"));
						System.out.println(">> is spring identifying = " + jobParameters.getParameters().get("spring").isIdentifying());
						return RepeatStatus.FINISHED;
					}
				}).build()
				).build();
	}
}

And here is the output:

2017-10-18 14:12:42.768  INFO 4948 --- [           main] o.s.batch.core.job.SimpleStepHandler     : Executing step: [stepq]
>> foo = null
>> -foo = bar
>> is -foo identifying = false
>> baz = quix
>> is baz identifying = false
>> -baz = null
>> spring = batch
>> is spring identifying = true

[snicoll]

That documentation you referenced is to pass properties as command line arguments, it's not a general recommendation as how any "parameter" to a process should be provided. In the case of Spring Batch, there is no reason to pass them with -- at all. The presence of -- is actually there to mention that this particular parameter is "special" and must be added to the command line property source.

Having said that, a documentation update would not hurt for sure.

[nishantraut]

Hi @philwebb Can you point me to the adoc file and section that needs to be updated. Thanks