diff --git a/spring-batch-docs/src/main/asciidoc/job.adoc b/spring-batch-docs/src/main/asciidoc/job.adoc index 9a0339a0b..e2ad5bd8e 100644 --- a/spring-batch-docs/src/main/asciidoc/job.adoc +++ b/spring-batch-docs/src/main/asciidoc/job.adoc @@ -48,7 +48,7 @@ public Job footballJob(JobRepository jobRepository) { [role="javaContent"] A `Job` (and, typically, any `Step` within it) requires a `JobRepository`. The -configuration of the `JobRepository` is handled through the <>. +configuration of the `JobRepository` is handled through the <>. [role="javaContent"] The preceding example illustrates a `Job` that consists of three `Step` instances. The job related @@ -444,13 +444,14 @@ annotation and two builders. The `@EnableBatchProcessing` annotation works similarly to the other `@Enable*` annotations in the Spring family. In this case, `@EnableBatchProcessing` provides a base configuration for -building batch jobs. Within this base configuration, an instance of `StepScope` and `Jobscope` are +building batch jobs. Within this base configuration, an instance of `StepScope` and `JobScope` are created, in addition to a number of beans being made available to be autowired: * `JobRepository`: a bean named `jobRepository` * `JobLauncher`: a bean named `jobLauncher` * `JobRegistry`: a bean named `jobRegistry` * `JobExplorer`: a bean named `jobExplorer` +* `JobOperator`: a bean named `jobOperator` The default implementation provides the beans mentioned in the preceding list and requires a `DataSource` and a `PlatformTransactionManager` to be provided as beans within the context. The data source and transaction @@ -1313,9 +1314,9 @@ The following example shows how to configure a `JobExplorer` in Java: [source, java, role="javaContent"] ---- ... -// This would reside in your BatchConfigurer implementation -@Override -public JobExplorer getJobExplorer() throws Exception { +// This would reside in your DefaultBatchConfiguration extension +@Bean +public JobExplorer jobExplorer() throws Exception { JobExplorerFactoryBean factoryBean = new JobExplorerFactoryBean(); factoryBean.setDataSource(this.dataSource); return factoryBean.getObject(); @@ -1348,9 +1349,9 @@ The following example shows how to set the table prefix for a `JobExplorer` in J [source, java, role="javaContent"] ---- ... -// This would reside in your BatchConfigurer implementation -@Override -public JobExplorer getJobExplorer() throws Exception { +// This would reside in your DefaultBatchConfiguration extension +@Bean +public JobExplorer jobExplorer() throws Exception { JobExplorerFactoryBean factoryBean = new JobExplorerFactoryBean(); factoryBean.setDataSource(this.dataSource); factoryBean.setTablePrefix("SYSTEM."); @@ -1389,7 +1390,7 @@ The following example shows how to configure your own `JobRegistry`: ---- ... // This is already provided via the @EnableBatchProcessing but can be customized via -// overriding the getter in the SimpleBatchConfiguration +// overriding the bean in the DefaultBatchConfiguration @Override @Bean public JobRegistry jobRegistry() throws Exception { @@ -1430,9 +1431,9 @@ defined in Java: [source, java, role="javaContent"] ---- @Bean -public JobRegistryBeanPostProcessor jobRegistryBeanPostProcessor() { +public JobRegistryBeanPostProcessor jobRegistryBeanPostProcessor(JobRegistry jobRegistry) { JobRegistryBeanPostProcessor postProcessor = new JobRegistryBeanPostProcessor(); - postProcessor.setJobRegistry(jobRegistry()); + postProcessor.setJobRegistry(jobRegistry); return postProcessor; } ---- @@ -1615,7 +1616,6 @@ The following example shows a typical bean definition for `SimpleJobOperator` in JobLauncher jobLauncher) { SimpleJobOperator jobOperator = new SimpleJobOperator(); - jobOperator.setJobExplorer(jobExplorer); jobOperator.setJobRepository(jobRepository); jobOperator.setJobRegistry(jobRegistry); @@ -1626,6 +1626,9 @@ The following example shows a typical bean definition for `SimpleJobOperator` in ---- ==== +As of version 5.0, the `@EnableBatchProcessing` annotation automatically registers a job operator bean +in the application context. + NOTE: If you set the table prefix on the job repository, do not forget to set it on the job explorer as well. [[JobParametersIncrementer]] diff --git a/spring-batch-docs/src/main/asciidoc/monitoring-and-metrics.adoc b/spring-batch-docs/src/main/asciidoc/monitoring-and-metrics.adoc index 13b2aff28..b1afa9b6e 100644 --- a/spring-batch-docs/src/main/asciidoc/monitoring-and-metrics.adoc +++ b/spring-batch-docs/src/main/asciidoc/monitoring-and-metrics.adoc @@ -22,6 +22,7 @@ under the `spring.batch` prefix. The following table explains all the metrics in |`spring.batch.job`|`TIMER`|Duration of job execution|`name`, `status` |`spring.batch.job.active`|`LONG_TASK_TIMER`|Currently active jobs|`name` |`spring.batch.step`|`TIMER`|Duration of step execution|`name`, `job.name`, `status` +|`spring.batch.step.active`|`LONG_TASK_TIMER`|Currently active step|`name` |`spring.batch.item.read`|`TIMER`|Duration of item reading|`job.name`, `step.name`, `status` |`spring.batch.item.process`|`TIMER`|Duration of item processing|`job.name`, `step.name`, `status` |`spring.batch.chunk.write`|`TIMER`|Duration of chunk writing|`job.name`, `step.name`, `status` @@ -84,3 +85,13 @@ Metrics.globalRegistry.config().meterFilter(MeterFilter.denyNameStartsWith("spri See Micrometer's link:$$http://micrometer.io/docs/concepts#_meter_filters$$[reference documentation] for more details. + +[[tracing]] +== Tracing + +As of version 5, Spring Batch provides tracing through Micrometer's `Observation` API. By default, tracing is enabled +when using `@EnableBatchProcessing`. Spring Batch will create a trace for each job execution and a span for each +step execution. + +If you do not use `EnableBatchProcessing`, you need to register a `BatchObservabilityBeanPostProcessor` in your +application context, which will automatically setup Micrometer's observability in your jobs and steps beans. diff --git a/spring-batch-docs/src/main/asciidoc/testing.adoc b/spring-batch-docs/src/main/asciidoc/testing.adoc index 8e0f2c074..b786dc56b 100644 --- a/spring-batch-docs/src/main/asciidoc/testing.adoc +++ b/spring-batch-docs/src/main/asciidoc/testing.adoc @@ -27,11 +27,9 @@ JUnit facilities * `@SpringBatchTest` injects Spring Batch test utilities (such as the `JobLauncherTestUtils` and `JobRepositoryTestUtils`) in the test context -NOTE: Note that `JobRepositoryTestUtils` requires a `DataSource` bean. Since -`@SpringBatchTest` registers a `JobRepositoryTestUtils` in the test -context, it is expected that the test context contains a single autowire candidate -for a `DataSource` (either a single bean definition or one that is -annotated with `org.springframework.context.annotation.Primary`). +NOTE: If the test context contains a single `Job` bean definition, this +bean will be autowired in `JobLauncherTestUtils`. Otherwise, the job +under test should be manually set on the `JobLauncherTestUtils`. [role="javaContent"] The following Java example shows the annotations in use: diff --git a/spring-batch-docs/src/main/asciidoc/whatsnew.adoc b/spring-batch-docs/src/main/asciidoc/whatsnew.adoc index 4be467b80..690501350 100644 --- a/spring-batch-docs/src/main/asciidoc/whatsnew.adoc +++ b/spring-batch-docs/src/main/asciidoc/whatsnew.adoc @@ -2,7 +2,7 @@ :toc: left :toclevels: 4 -This section shows the major highlights of Spring Batch 5 and is not an exhaustive list of changes. +This section shows the major highlights of Spring Batch 5. For more details, please refer to the link:$$https://github.com/spring-projects/spring-batch/wiki/Spring-Batch-5.0-Migration-Guide$$[migration guide]. @@ -262,6 +262,16 @@ customizing the transaction attributes. The same transaction support was added to the `JobOperator` through a new factory bean named `JobOperatorFactoryBean`. +==== Automatic registration of a JobOperator with EnableBatchProcessing + +As of version 4, the `EnableBatchProcessing` annotation provided all the basic infrastructure +beans that are required to launch Spring Batch jobs. However, it did not register a job +operator bean, which is the main entry point to stop, restart and abandon job executions. + +While these utilities are not used as often as launching jobs, adding a job operator automatically +in the application context can be useful to avoid a manual configuration of such a bean +by end users. + ==== Improved Java records support The support for Java records as items in a chunk-oriented step has initially been introduced in v4.3,