From d1893cf547944a03cd37e2acd524998eb8c429c5 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Mon, 2 Dec 2019 12:59:42 -0600 Subject: [PATCH 1/2] More detail for Batch within Boot At Michael Minella's suggestion and with his input, I extended the Batch section of the How-to page to include more detail. --- .../src/main/asciidoc/howto.adoc | 81 +++++++++++++++---- 1 file changed, 66 insertions(+), 15 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index f238f021c063..e6122f8aa9fe 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -2098,9 +2098,17 @@ The preceding example overrides the default factory, and it should be applied to [[howto-batch-applications]] == Batch Applications -This section answers questions that arise from using Spring Batch with Spring Boot. +A number of questions often arise when people use Spring Batch from within a Spring Boot application. This section addresses the following concerns: -NOTE: By default, batch applications require a `DataSource` to store job details. +* <> +* <> +* <> +* <> + +[[howto-spring-batch-specifying-a-data-source]] +=== Specifying a Batch Data Source + +By default, batch applications require a `DataSource` to store job details. Batch autowires a single `DataSource` in your context and uses that for processing. To have Batch use a `DataSource` other than the application’s main `DataSource`, declare a `DataSource` bean, annotating its `@Bean` method with `@BatchDataSource`. If you do so and want two data sources, remember to create another one and mark it as `@Primary`. @@ -2109,26 +2117,69 @@ See {spring-batch-api}/core/configuration/annotation/EnableBatchProcessing.html[ For more about Spring Batch, see the {spring-batch}[Spring Batch project page]. - - -[[howto-execute-spring-batch-jobs-on-startup]] -=== Execute Spring Batch Jobs on Startup +[[howto-run-spring-batch-jobs-on-startup]] +=== Running Spring Batch Jobs on Startup Spring Batch auto-configuration is enabled by adding `@EnableBatchProcessing` (from Spring Batch) somewhere in your context. By default, it executes *all* `Jobs` in the application context on startup (see {spring-boot-autoconfigure-module-code}/batch/JobLauncherCommandLineRunner.java[JobLauncherCommandLineRunner] for details). You can narrow down to a specific job or jobs by specifying `spring.batch.job.names` (which takes a comma-separated list of job name patterns). -[TIP] -.Specifying job parameters on the command line -==== -Unlike command line option arguments that <> (i.e. by starting with `--`, such as `--my-property=value`), job parameters have to be specified on the command line without dashes (e.g. `jobParam=value`). -==== - -If the application context includes a `JobRegistry`, the jobs in `spring.batch.job.names` are looked up in the registry instead of being autowired from the context. -This is a common pattern with more complex systems, where multiple jobs are defined in child contexts and registered centrally. - See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[BatchAutoConfiguration] and https://github.com/spring-projects/spring-batch/blob/master/spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/EnableBatchProcessing.java[@EnableBatchProcessing] for more details. +[[howto-spring-batch-running-command-line]] +=== Running from the Command Line + +Running Spring Batch with Spring Boot from the command line differs from running Spring +Batch by itself from the command line. Spring Boot uses a class called +`JobLaunchingCommandLineRunner`. Spring Batch uses a class called `CommandLineJobRunner`. +They work a bit differently. However, for the most part, the differences do not cause +trouble. However, they parse command line arguments differently, which can cause trouble, +as described in the next section. +// TODO What are the other differences between the two? + +==== Passing Command-line Arguments + +If you run Spring Batch with Spring Boot, Spring Boot strips the first `-` character (a +hyphen) from each command line argument. For example, `--exampleArgument` becomes +`-exampleArgument`. Whether a command-line option has one hyphen or two often makes no +difference in Spring Boot. However, in Spring Batch, putting a single `-` character +before the `jobParameters` parameter indicates that Spring Batch should not use the +`jobParameters` value as the identifier for the `Job`. Best practice is to use the +`jobParameters` value as the identifier for the `Job`, so this issue may cause problems. +To avoid the issue, you should generally use no `-` characters for the command-line +options that you pass to Spring Boot on behalf of Spring Batch, as shown in the following +example: + +[source] +jobParameters="someParameter" + +However, if you mean to not use the `jobParameters` value as the identifier for the +`Job`, use two hyphens, as shown in the following example: + +[source] +--jobParameters="someParameter" + +In the second example, Spring Boot passes the parameter to Spring Batch as +`-jobParameters="someParameter"`, and "someParameter" does not become the name of the +`Job`. +// TODO In that case, what is the name of the job? + +[[howto-spring-batch-storing-job-repository]] +=== Storing the Job Repository + +Spring Batch requires a memory store for the `Job` repository. If you use Spring Boot, +you must use an actual database. Note that it can be an in-memory database. Using Spring +Batch without Spring Boot does not require a database. If you use Spring Batch without +Spring Boot, you may provide a database (including an in-memory database), but it is not +required. If you do not provide a database, Spring Batch uses a `Map` object as the `Job` +repository. + +See also +https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring +a Job Repository] +// TODO Is it best practice to use a database (rather than the default Map object) for +// the Job Repository, even when Spring Boot isn't present? + [[howto-actuator]] From 4290a6765b5d40e24e5282ca0297abf5e3528a57 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Thu, 12 Dec 2019 11:59:04 -0600 Subject: [PATCH 2/2] Accounted for feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stéphane Nicoll and Mahmoud Ben Hassine had comments on my changes. I have accounted for their input. Thanks, Stéphane and Mahmoud. --- .../src/main/asciidoc/howto.adoc | 71 +++++++------------ 1 file changed, 26 insertions(+), 45 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index e6122f8aa9fe..2821c4f75749 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -2098,12 +2098,8 @@ The preceding example overrides the default factory, and it should be applied to [[howto-batch-applications]] == Batch Applications -A number of questions often arise when people use Spring Batch from within a Spring Boot application. This section addresses the following concerns: - -* <> -* <> -* <> -* <> +A number of questions often arise when people use Spring Batch from within a Spring Boot application. +This section addresses those questions. [[howto-spring-batch-specifying-a-data-source]] === Specifying a Batch Data Source @@ -2117,11 +2113,11 @@ See {spring-batch-api}/core/configuration/annotation/EnableBatchProcessing.html[ For more about Spring Batch, see the {spring-batch}[Spring Batch project page]. -[[howto-run-spring-batch-jobs-on-startup]] +[[howto-running-spring-batch-jobs-on-startup]] === Running Spring Batch Jobs on Startup Spring Batch auto-configuration is enabled by adding `@EnableBatchProcessing` (from Spring Batch) somewhere in your context. -By default, it executes *all* `Jobs` in the application context on startup (see {spring-boot-autoconfigure-module-code}/batch/JobLauncherCommandLineRunner.java[JobLauncherCommandLineRunner] for details). +By default, it executes *all* `Jobs` in the application context on startup (see {spring-boot-autoconfigure-module-code}/batch/JobLauncherCommandLineRunner.java[`JobLauncherCommandLineRunner`] for details). You can narrow down to a specific job or jobs by specifying `spring.batch.job.names` (which takes a comma-separated list of job name patterns). See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[BatchAutoConfiguration] and https://github.com/spring-projects/spring-batch/blob/master/spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/EnableBatchProcessing.java[@EnableBatchProcessing] for more details. @@ -2129,56 +2125,41 @@ See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[Ba [[howto-spring-batch-running-command-line]] === Running from the Command Line -Running Spring Batch with Spring Boot from the command line differs from running Spring -Batch by itself from the command line. Spring Boot uses a class called -`JobLaunchingCommandLineRunner`. Spring Batch uses a class called `CommandLineJobRunner`. -They work a bit differently. However, for the most part, the differences do not cause -trouble. However, they parse command line arguments differently, which can cause trouble, -as described in the next section. -// TODO What are the other differences between the two? +Running Spring Batch with Spring Boot from the command line differs from running Spring Batch by itself from the command line. +Spring Boot uses a class called `JobLaunchingCommandLineRunner`. +Spring Batch uses a class called `CommandLineJobRunner`. +They work a bit differently. However, for the most part, the differences do not cause trouble. +However, they parse command line arguments differently, which can cause trouble, as described in the next section. ==== Passing Command-line Arguments -If you run Spring Batch with Spring Boot, Spring Boot strips the first `-` character (a -hyphen) from each command line argument. For example, `--exampleArgument` becomes -`-exampleArgument`. Whether a command-line option has one hyphen or two often makes no -difference in Spring Boot. However, in Spring Batch, putting a single `-` character -before the `jobParameters` parameter indicates that Spring Batch should not use the -`jobParameters` value as the identifier for the `Job`. Best practice is to use the -`jobParameters` value as the identifier for the `Job`, so this issue may cause problems. -To avoid the issue, you should generally use no `-` characters for the command-line -options that you pass to Spring Boot on behalf of Spring Batch, as shown in the following -example: +Spring Boot uses `--` (two hyphens) to signal application arguments. +Spring Batch uses a single hyphen as a special marker on the `jobParameters` argument. +This section explains how to reconcile that difference when you use the `jobParameters` argument for Spring Batch within a Spring Boot application. + +If you run Spring Batch with Spring Boot, Spring Boot strips the first `-` character from each command line argument. +For example, `--exampleArgument` becomes `-exampleArgument`. +Whether a command-line option has one hyphen or two often makes no difference in Spring Boot. +However, in Spring Batch, putting a single `-` character before the `jobParameters` parameter indicates that Spring Batch should not use the `jobParameters` value as the identifier for the `Job`. +Best practice is to use the `jobParameters` value as the identifier for the `Job`, so this issue may cause problems. +To avoid the issue, you should generally use no `-` characters for the command-line options that you pass to Spring Boot on behalf of Spring Batch, as shown in the following example: [source] -jobParameters="someParameter" +someParameter="someValue" -However, if you mean to not use the `jobParameters` value as the identifier for the -`Job`, use two hyphens, as shown in the following example: +However, if you mean to not use the `someValue` value as the identifier for the `Job`, use two hyphens, as shown in the following example: [source] ---jobParameters="someParameter" +--jobParameters="someValue" -In the second example, Spring Boot passes the parameter to Spring Batch as -`-jobParameters="someParameter"`, and "someParameter" does not become the name of the -`Job`. -// TODO In that case, what is the name of the job? +In the second example, Spring Boot passes the parameter to Spring Batch as `-jobParameters="someValue"`, and `someValue` is used as a non-identifying job parameter. [[howto-spring-batch-storing-job-repository]] === Storing the Job Repository -Spring Batch requires a memory store for the `Job` repository. If you use Spring Boot, -you must use an actual database. Note that it can be an in-memory database. Using Spring -Batch without Spring Boot does not require a database. If you use Spring Batch without -Spring Boot, you may provide a database (including an in-memory database), but it is not -required. If you do not provide a database, Spring Batch uses a `Map` object as the `Job` -repository. - -See also -https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring -a Job Repository] -// TODO Is it best practice to use a database (rather than the default Map object) for -// the Job Repository, even when Spring Boot isn't present? +Spring Batch requires a memory store for the `Job` repository. +If you use Spring Boot, you must use an actual database. Note that it can be an in-memory database. +See https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring a Job Repository].