From 6bd9b2ebc651dfd2094db9bf9e3d1de3ca06c202 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Mon, 2 Dec 2019 12:59:42 -0600 Subject: [PATCH 1/2] Improve Spring Batch coverage in reference documentation See gh-19211 --- .../src/main/asciidoc/howto.adoc | 62 ++++++++++++++----- 1 file changed, 47 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 f419c2b167f..3d23fece9cd 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 @@ -2104,9 +2104,13 @@ 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 those questions. -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`. @@ -2115,25 +2119,53 @@ 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-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). -[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`). -==== +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. -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. +[[howto-spring-batch-running-command-line]] +=== Running from the Command Line -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. +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 + +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] +someParameter="someValue" + +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="someValue" + +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. +See https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring a Job Repository]. From 5f987a67f85c1418d81fabfbebbfb7509efd5260 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 23 Dec 2019 10:03:34 +0100 Subject: [PATCH 2/2] Polish "Improve Spring Batch coverage in reference documentation" See gh-19211 --- spring-boot-project/spring-boot-docs/pom.xml | 1 + .../src/main/asciidoc/attributes.adoc | 3 +- .../src/main/asciidoc/howto.adoc | 53 +++++++++++-------- 3 files changed, 33 insertions(+), 24 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/pom.xml b/spring-boot-project/spring-boot-docs/pom.xml index e70588ecea3..28b57a911b3 100644 --- a/spring-boot-project/spring-boot-docs/pom.xml +++ b/spring-boot-project/spring-boot-docs/pom.xml @@ -1525,6 +1525,7 @@ ${jooq.version} ${revision} ${spring-amqp.version} + ${spring-batch.version} ${flattenedpom.version.org.springframework.data.spring-data-couchbase} ${flattenedpom.version.org.springframework.data.spring-data-commons} ${flattenedpom.version.org.springframework.data.spring-data-jpa} diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/attributes.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/attributes.adoc index 3d5152a9692..52eca2c1fa1 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/attributes.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/attributes.adoc @@ -53,7 +53,8 @@ :spring-amqp-api: https://docs.spring.io/spring-amqp/docs/{spring-amqp-version}/api/org/springframework/amqp :spring-batch: https://spring.io/projects/spring-batch -:spring-batch-api: https://docs.spring.io/spring-batch/apidocs/org/springframework/batch +:spring-batch-api: https://docs.spring.io/spring-batch/docs/{spring-batch-version}/api/org/springframework/batch +:spring-batch-docs: https://docs.spring.io/spring-batch/docs/{spring-batch-version}/reference/html/ :spring-data: https://spring.io/projects/spring-data :spring-data-cassandra: https://spring.io/projects/spring-data-cassandra :spring-data-commons-api: https://docs.spring.io/spring-data/commons/docs/{spring-data-commons-version}/api/org/springframework/data 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 3d23fece9cd..0ec10491b81 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 @@ -2107,38 +2107,40 @@ The preceding example overrides the default factory, and it should be applied to 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 - 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`. +Spring Batch expects a single `DataSource` by default. +To have it 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 mark the other one `@Primary`. To take greater control, implement `BatchConfigurer`. See {spring-batch-api}/core/configuration/annotation/EnableBatchProcessing.html[The Javadoc of `@EnableBatchProcessing`] for more details. -For more about Spring Batch, see the {spring-batch}[Spring Batch project page]. +For more info about Spring Batch, see the {spring-batch}[Spring Batch project page]. + + -[[howto-running-spring-batch-jobs-on-startup]] +[[howto-spring-batch-running-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. +Spring Batch auto-configuration is enabled by adding `@EnableBatchProcessing` to one of your `@Configuration` classes. 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. +See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[BatchAutoConfiguration] and {spring-batch-api}/core/configuration/annotation/EnableBatchProcessing.html[@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. +The most important difference is that they parse command line arguments differently, which can cause trouble, as described in the next section. + -==== Passing Command-line Arguments +==== Passing Command-line Arguments 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. @@ -2150,22 +2152,27 @@ However, in Spring Batch, putting a single `-` character before the `jobParamete 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] -someParameter="someValue" +[source,properties,indent=0] +---- + someParameter=someValue +---- -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: +However, if you mean to not use `someValue` value as the identifier for the `Job`, use two hyphens, as shown in the following example: -[source] ---jobParameters="someValue" +[source,properties,indent=0] +---- + --jobParameters=someValue +---- 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. -See https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring a Job Repository]. +Spring Batch requires a data 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 {spring-batch-docs}job.html#configuringJobRepository[Configuring a Job Repository].