diff --git a/spring-cloud-task-core/src/main/java/org/springframework/cloud/task/configuration/TaskConfigurer.java b/spring-cloud-task-core/src/main/java/org/springframework/cloud/task/configuration/TaskConfigurer.java index b04299c2..58493897 100644 --- a/spring-cloud-task-core/src/main/java/org/springframework/cloud/task/configuration/TaskConfigurer.java +++ b/spring-cloud-task-core/src/main/java/org/springframework/cloud/task/configuration/TaskConfigurer.java @@ -29,13 +29,24 @@ import org.springframework.transaction.PlatformTransactionManager; public interface TaskConfigurer { /** - * Create a Task Repository for the Task. + * Create a {@link TaskRepository} for the Task. * * @return A TaskRepository */ TaskRepository getTaskRepository(); + /** + * Create a {@link PlatformTransactionManager} for use with the + * TaskRepository. + * + * @return A PlatformTransactionManager + */ PlatformTransactionManager getTransactionManager(); + /** + * Create a {@link TaskExplorer} for the task. + * + * @return a TaskExplorer + */ TaskExplorer getTaskExplorer(); } diff --git a/spring-cloud-task-docs/src/main/asciidoc/batch.adoc b/spring-cloud-task-docs/src/main/asciidoc/batch.adoc index 728f810f..8fa5b837 100644 --- a/spring-cloud-task-docs/src/main/asciidoc/batch.adoc +++ b/spring-cloud-task-docs/src/main/asciidoc/batch.adoc @@ -21,7 +21,7 @@ back to the other. This functionality is accomplished by using the `TaskBatchExecutionListener`. By default, this listener is auto configured in any context that has both a Spring Batch Job configured -(via having a bean of type Job defined in the context) and the spring-cloud-task-batch jar +(via having a bean of type `Job` defined in the context) and the spring-cloud-task-batch jar is available within the classpath. The listener will be injected into all jobs. [[batch-association-override]] @@ -100,3 +100,10 @@ public DeployerStepExecutionHandler stepExecutionHandler(JobExplorer jobExplorer return handler; } ``` + +[[batch-informational-messages]] +== Batch Informational Messages + +Spring Cloud Task provides the ability for batch jobs to emit informational messages. This +is covered in detail in the section +<>. diff --git a/spring-cloud-task-docs/src/main/asciidoc/features.adoc b/spring-cloud-task-docs/src/main/asciidoc/features.adoc index f3b170fb..a2e0dceb 100644 --- a/spring-cloud-task-docs/src/main/asciidoc/features.adoc +++ b/spring-cloud-task-docs/src/main/asciidoc/features.adoc @@ -17,7 +17,7 @@ platforms do have some method to execute a process that isn't restarted when it results of that execution are typically not maintained in a consumable way. Spring Cloud Task brings the ability to execute short lived processes in an environment and record the results. This allows for a microservices architecture around short lived processes as - well as longer running services. + well as longer running services via the integration of tasks by messages. While this functionality is useful in a cloud environment, the same issues can arise in a traditional deployment model as well. When executing Spring Boot applications via a @@ -32,10 +32,12 @@ The lifecycle consists of a single task execution. This is a physical execution Spring Boot application configured to be a task (annotated with the `@EnableTask` annotation). -At the beginning of a task, an entry in the `TaskRepository` is created recording the -start event. This event is triggered via `SmartLifecycle#start` being triggered by -Spring Framework. This indicates to the system that all beans are ready for use and is -before the execution of any of the `*Runner`s provided by Spring Boot. +At the beginning of a task (before any `CommandLineRunner` or `ApplicationRunner` +implementations have been executed, an entry in the `TaskRepository` is created recording +the start event. This event is triggered via `SmartLifecycle#start` being triggered by +Spring Framework. This indicates to the system that all beans are ready for use and is +before the execution of any of the `CommandLineRunner` or `ApplicationRunner` +implementations provided by Spring Boot. NOTE: The recording of a task will only occur upon the successful bootstrapping of an `ApplicationContext`. If the context fails to bootstrap at all, the task's execution will @@ -46,8 +48,9 @@ Upon completion of all of the `*Runner#run` calls from Spring Boot or the failur updated in the repository with the results. NOTE: At the completion of a task (all `*Runner#run` methods are called and the task -repository has been updated) the `ApplicationContext` will be closed. This behavior can -be overriden by setting the property `spring.cloud.task.closecontext.enabled` to false. +repository has been updated) the `ApplicationContext` will be closed by default. This +behavior can be overriden by setting the property `spring.cloud.task.closecontext.enabled` +to false. [[features-task-execution-details]] === The TaskExecution @@ -81,7 +84,7 @@ of the task (as indicated via an `ApplicationFailedEvent`), the stack trace for exception will be stored here. |`parameters` -|A `List` of the string parameters as they were passed into the executable boot +|A `List` of the string command line arguments as they were passed into the executable boot application. |=== @@ -177,11 +180,11 @@ following options (in order of precedence): Allows a user to register listeners for specific events that occur during the task lifecycle. This is done by creating a class that implements the TaskExecutionListener -interface. The class that implements the TaskExecutionListener interface will be +interface. The class that implements the `TaskExecutionListener` interface will be notified for the following events: -. `onTaskStartup` - prior to the storing the TaskExecution into the TaskRepository -. `onTaskEnd` - prior to the updating of the TaskExecution entry in the TaskRepository +. `onTaskStartup` - prior to the storing the `TaskExecution` into the `TaskRepository` +. `onTaskEnd` - prior to the updating of the `TaskExecution` entry in the `TaskRepository` marking the final state of the task. . `onTaskFailed` - prior to the `onTaskEnd` method being invoked when an unhandled exception is thrown by the task. @@ -189,8 +192,8 @@ marking the final state of the task. Spring Cloud Task also allows a user add `TaskExecution` Listeners to methods within a bean by using the following method annotations: -. `@BeforeTask` - prior to the storing the TaskExecution into the TaskRepository -. `@AfterTask` - prior to the updating of the TaskExecution entry in the TaskRepository +. `@BeforeTask` - prior to the storing the `TaskExecution` into the `TaskRepository` +. `@AfterTask` - prior to the updating of the `TaskExecution` entry in the `TaskRepository` marking the final state of the task. . `@FailedTask` - prior to the `@AfterTask` method being invoked when an unhandled exception is thrown by the task. diff --git a/spring-cloud-task-docs/src/main/asciidoc/getting-started.adoc b/spring-cloud-task-docs/src/main/asciidoc/getting-started.adoc index 0d7ef0cd..98cdb77e 100644 --- a/spring-cloud-task-docs/src/main/asciidoc/getting-started.adoc +++ b/spring-cloud-task-docs/src/main/asciidoc/getting-started.adoc @@ -90,7 +90,7 @@ will be used to build your project. Open your favorite text editor and add the org.springframework.boot spring-boot-starter-parent - 1.3.2.RELEASE + 1.3.3.RELEASE @@ -190,6 +190,17 @@ While it may not look like much, quite a bit is going on. To read more about th Boot specifics, take a look at their reference documentation here: http://docs.spring.io/spring-boot/docs/current/reference/html/[http://docs.spring.io/spring-boot/docs/current/reference/html/] +We'll also need to create an `application.properties` in `src/main/resources`. We'll +configure two properties in it: the application name (which is translated to the task name) +and we'll set the logging for spring cloud task to `DEBUG` so that we can see what's going +on: + +[source] +---- +logging.level.org.springframework.cloud.task=DEBUG +spring.application.name=helloWorld +---- + [[getting-started-at-task]] ==== The @EnableTask annotation @@ -255,7 +266,7 @@ $ mvn clean spring-boot:run \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ - :: Spring Boot :: (v1.3.2.RELEASE) + :: Spring Boot :: (v1.3.3.RELEASE) 2016-01-25 11:08:10.183 INFO 12943 --- [ main] com.example.SampleTask : Starting SampleTask on Michaels-MacBook-Pro-2.local with PID 12943 (/Users/mminella/Documents/IntelliJWorkspace/spring-cloud-task-example/target/classes started by mminella in /Users/mminella/Documents/IntelliJWorkspace/spring-cloud-task-example) 2016-01-25 11:08:10.185 INFO 12943 --- [ main] com.example.SampleTask : No active profile set, falling back to default profiles: default diff --git a/spring-cloud-task-docs/src/main/asciidoc/preface.adoc b/spring-cloud-task-docs/src/main/asciidoc/preface.adoc index 7121f20b..2baced83 100644 --- a/spring-cloud-task-docs/src/main/asciidoc/preface.adoc +++ b/spring-cloud-task-docs/src/main/asciidoc/preface.adoc @@ -23,7 +23,7 @@ print or electronically. Having trouble with Spring Cloud Task, We'd like to help! * Ask a question - we monitor http://stackoverflow.com[stackoverflow.com] for questions - tagged with http://stackoverflow.com/tags/spring-cloud[`spring-cloud`]. + tagged with http://stackoverflow.com/tags/spring-cloud-task[`spring-cloud-task`]. * Report bugs with Spring Cloud Task at https://github.com/spring-cloud/spring-cloud-task/issues. NOTE: All of Spring Cloud Task is open source, including the documentation! If you find problems diff --git a/spring-cloud-task-docs/src/main/asciidoc/stream.adoc b/spring-cloud-task-docs/src/main/asciidoc/stream.adoc index 9acd0df9..70093c1d 100644 --- a/spring-cloud-task-docs/src/main/asciidoc/stream.adoc +++ b/spring-cloud-task-docs/src/main/asciidoc/stream.adoc @@ -99,10 +99,50 @@ public class TaskEventsApplication { } ``` -will emit events on the task-events channel. +will emit the `TaskExecution` as an event on the `task-events` channel (both at the start +and end of the task). NOTE: Configuration of the content type may be required via `--spring.cloud.stream.bindings.task-events.contentType=` if the processor or sink downstream does not have the spring-cloud-task-core jar on its classpath. -NOTE: A binder implementation is also required to be on the classpath. \ No newline at end of file +NOTE: A binder implementation is also required to be on the classpath. + +[[stream-integration-batch-events]] +== Spring Batch Events + +When executing a Spring Batch job via a task, Spring Cloud Task can be configured to emit +informational messages based on the Spring Batch listeners available in Spring Batch. +Specifically the following Spring Batch listeners are autoconfigured into each batch job and +emit messages on the associated Spring Cloud Stream channels when run via Spring Cloud +Task: + +* `JobExecutionListener` - `job-execution-events` +* `StepExecutionListener` - `step-execution-events` +* `ChunkListener` - `chunk-events` +* `ItemReadListener` - `item-read-events` +* `ItemProcessListener` - `item-process-events` +* `ItemWriteListener` - `item-write-events` +* `SkipListener` - `skip-events` + +The above listeners are autoconfigured into any `AbstractJob` when the appropriate +beans exist in the context (a `Job` and a `TaskLifecycleListener`). Configuration to +listen to these events is handled the same way binding to any other Spring +Cloud Stream channel is done. Our task (the one running the batch job) serves as a +`Source`, with the listening applications serving as either a `Processor` or `Sink`. + +An example could be to have an application listening to the `job-execution-events` channel +for the start and stop of a job. To configure the listening application, you'd configure +the input to be `job-execution-events` as follows + +``` +spring.cloud.stream.bindings.input.destination=job-execution-events +``` + +NOTE: A binder implementation is also required to be on the classpath. + +To disable the listener functionality, use the following configuration: + +``` +spring.cloud.task.batch.events.enabled=false +```