From 342a1a35dcf2acd59a752a5541a9b497fde54bf3 Mon Sep 17 00:00:00 2001
From: Mahmoud Ben Hassine <mbenhassine@vmware.com>
Date: Thu, 24 Sep 2020 10:10:29 +0200
Subject: [PATCH] Document usage of non-identifying job parameters

Resolves #3633
---
 .../launch/support/CommandLineJobRunner.java  | 19 ++++++++++++++-
 spring-batch-docs/asciidoc/job.adoc           | 23 +++++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/launch/support/CommandLineJobRunner.java b/spring-batch-core/src/main/java/org/springframework/batch/core/launch/support/CommandLineJobRunner.java
index 3d3dbba5d..e7b77844c 100644
--- a/spring-batch-core/src/main/java/org/springframework/batch/core/launch/support/CommandLineJobRunner.java
+++ b/spring-batch-core/src/main/java/org/springframework/batch/core/launch/support/CommandLineJobRunner.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2019 the original author or authors.
+ * Copyright 2006-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -142,6 +142,23 @@ import org.springframework.util.StringUtils;
  * </p>
  *
  * <p>
+ * By default, the `CommandLineJobRunner` uses a {@link DefaultJobParametersConverter}
+ * which implicitly converts key/value pairs to identifying job parameters.
+ * However, it is possible to explicitly specify which job parameters are identifying
+ * and which are not by prefixing them with `+` or `-` respectively. In the following
+ * example, `schedule.date` is an identifying job parameter while `vendor.id` is not:
+ * </p>
+ * 
+ * <p>
+ * <code>
+ * java org.springframework.batch.core.launch.support.CommandLineJobRunner testJob.xml
+ * testJob +schedule.date=2008/01/24 -vendor.id=3902483920
+ * </code>
+ * </p>
+ *
+ * <p>This behaviour can be overridden by using a custom `JobParametersConverter`.</p>
+ *
+ * <p>
  * Once arguments have been successfully parsed, autowiring will be used to set
  * various dependencies. The {@link JobLauncher} for example, will be
  * loaded this way. If none is contained in the bean factory (it searches by
diff --git a/spring-batch-docs/asciidoc/job.adoc b/spring-batch-docs/asciidoc/job.adoc
index c3545eb7b..b4d2664ae 100644
--- a/spring-batch-docs/asciidoc/job.adoc
+++ b/spring-batch-docs/asciidoc/job.adoc
@@ -992,6 +992,29 @@ The following example shows a date passed as a job parameter to a job defined in
 <bash$ java CommandLineJobRunner io.spring.EndOfDayJobConfiguration endOfDay schedule.date(date)=2007/05/05
 ----
 
+[NOTE]
+====
+By default, the `CommandLineJobRunner` uses a `DefaultJobParametersConverter` which implicitly converts
+key/value pairs to identifying job parameters. However, it is possible to explicitly specify
+which job parameters are identifying and which are not by prefixing them with `+` or `-` respectively.
+
+In the following example, `schedule.date` is an identifying job parameter while `vendor.id` is not:
+
+[source, role="xmlContent"]
+----
+<bash$ java CommandLineJobRunner endOfDayJob.xml endOfDay \
+                                 +schedule.date(date)=2007/05/05 -vendor.id=123
+----
+
+[source, role="javaContent"]
+----
+<bash$ java CommandLineJobRunner io.spring.EndOfDayJobConfiguration endOfDay \
+                                 +schedule.date(date)=2007/05/05 -vendor.id=123
+----
+
+This behaviour can be overridden by using a custom `JobParametersConverter`.
+====
+
 ifdef::backend-html5[]
 [role="xmlContent"]
 In most cases, you would want to use a manifest to declare your main class in a jar, but,