SpringCloud/spring-cloud-task
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

WIP

Browse Source
This commit is contained in:
Marcin Grzejszczak
2021-02-10 14:59:53 +01:00
parent f5c27020ae
commit d12dc0236b
31 changed files with 326 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/src/main/asciidoc/.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
*.html
*.css

20
docs/src/main/asciidoc/Guardfile Normal file
View File

@@ -0,0 +1,20 @@
require 'asciidoctor'
require 'erb'
guard 'shell' do
watch(/.*\.adoc$/) {|m|
Asciidoctor.render_file('index.adoc', \
:in_place => true, \
:safe => Asciidoctor::SafeMode::UNSAFE, \
:attributes => {\
'source-highlighter' => 'prettify', \
'icons' => 'font', \
'linkcss' => 'true', \
'copycss' => 'true', \
'doctype' => 'book'})
}
end
guard 'livereload' do
watch(%r{^.+\.(css|js|html)$})
end

52
docs/src/main/asciidoc/README.adoc Normal file
View File

@@ -0,0 +1,52 @@
= Spring Cloud Task image:https://build.spring.io/plugins/servlet/wittified/build-status/SCT-STASK[Build Status, link=https://build.spring.io/browse/SCT-STASK]
Is a project centered around the idea of processing on demand. A user is able to develop
a “task” that can be deployed, executed and removed on demand, yet the result of the
process persists beyond the life of the task for future reporting.
== Requirements:
* Java 8 or Above
== Build Main Project:
[source,shell,indent=2]
----
$ ./mvnw clean install
----
== Example:
[source,java,indent=2]
----
@SpringBootApplication
@EnableTask
public class MyApp {
@Bean
public MyTaskApplication myTask() {
return new MyTaskApplication();
}
public static void main(String[] args) {
SpringApplication.run(MyApp.class);
}
public static class MyTaskApplication implements ApplicationRunner {
@Override
public void run(ApplicationArguments args) throws Exception {
System.out.println("Hello World");
}
}
}
----
== Code of Conduct
This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
== Building the Project
This project requires that you invoke the Javadoc engine from the Maven command line. You can do so by appending `javadoc:aggregate` to the rest of your Maven command.
For example, to build the entire project, you could use `./mvnw -Pfull javadoc:aggregate`.

47
docs/src/main/asciidoc/_attributes.adoc Normal file
View File

@@ -0,0 +1,47 @@
:doctype: book
:idprefix:
:idseparator: -
:toc: left
:toclevels: 4
:tabsize: 4
:numbered:
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private
:sc-ext: java
:project-full-name: Spring Cloud Task
// project-specific attributes
:spring-cloud-task-repo: snapshot
:github-tag: master
:spring-cloud-task-docs-version: current
:spring-cloud-task-docs: https://docs.spring.io/spring-cloud-task/docs/{spring-cloud-task-docs-version}/reference
:spring-cloud-task-docs-current: https://docs.spring.io/spring-cloud-task/docs/current-SNAPSHOT/reference/html/
:github-repo: spring-cloud/spring-cloud-task
:github-raw: https://raw.github.com/{github-repo}/{github-tag}
:github-code: https://github.com/{github-repo}/tree/{github-tag}
:github-wiki: https://github.com/{github-repo}/wiki
:github-master-code: https://github.com/{github-repo}/tree/master
:sc-ext: java
:sc-spring-boot: {github-code}/spring-boot/src/main/java/org/springframework/boot
:dc-ext: html
:dc-root: https://docs.spring.io/spring-cloud-task/docs/{spring-cloud-dataflow-docs-version}/api
:dc-spring-boot: {dc-root}/org/springframework/boot
:dependency-management-plugin: https://github.com/spring-gradle-plugins/dependency-management-plugin
:dependency-management-plugin-documentation: {dependency-management-plugin}/blob/master/README.md
:spring-boot-maven-plugin-site: https://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin
:spring-reference: https://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/htmlsingle
:spring-security-reference: https://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
:spring-javadoc: https://docs.spring.io/spring/docs/{spring-docs-version}/javadoc-api/org/springframework
:spring-amqp-javadoc: https://docs.spring.io/spring-amqp/docs/current/api/org/springframework/amqp
:spring-data-javadoc: https://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
:spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
:spring-data-mongo-javadoc: https://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
:spring-data-rest-javadoc: https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest
:gradle-userguide: https://www.gradle.org/docs/current/userguide
:propdeps-plugin: https://github.com/spring-projects/gradle-plugins/tree/master/propdeps-plugin
:ant-manual: https://ant.apache.org/manual
:attributes: allow-uri-read

35
docs/src/main/asciidoc/_configprops.adoc Normal file
View File

@@ -0,0 +1,35 @@
|===
|Name | Default | Description
|spring.cloud.task.batch.command-line-runner-order | `0` | The order for the {@code CommandLineRunner} used to run batch jobs when {@code spring.cloud.task.batch.fail-on-job-failure=true}. Defaults to 0 (same as the {@link org.springframework.boot.autoconfigure.batch.JobLauncherCommandLineRunner}).
|spring.cloud.task.batch.events.chunk-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.ChunkListener}.
|spring.cloud.task.batch.events.chunk.enabled | `true` | This property is used to determine if a task should listen for batch chunk events.
|spring.cloud.task.batch.events.enabled | `true` | This property is used to determine if a task should listen for batch events.
|spring.cloud.task.batch.events.item-process-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.ItemProcessListener}.
|spring.cloud.task.batch.events.item-process.enabled | `true` | This property is used to determine if a task should listen for batch item processed events.
|spring.cloud.task.batch.events.item-read-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.ItemReadListener}.
|spring.cloud.task.batch.events.item-read.enabled | `true` | This property is used to determine if a task should listen for batch item read events.
|spring.cloud.task.batch.events.item-write-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.ItemWriteListener}.
|spring.cloud.task.batch.events.item-write.enabled | `true` | This property is used to determine if a task should listen for batch item write events.
|spring.cloud.task.batch.events.job-execution-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.JobExecutionListener}.
|spring.cloud.task.batch.events.job-execution.enabled | `true` | This property is used to determine if a task should listen for batch job execution events.
|spring.cloud.task.batch.events.skip-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.SkipListener}.
|spring.cloud.task.batch.events.skip.enabled | `true` | This property is used to determine if a task should listen for batch skip events.
|spring.cloud.task.batch.events.step-execution-order | | Establishes the default {@link Ordered} precedence for {@link org.springframework.batch.core.StepExecutionListener}.
|spring.cloud.task.batch.events.step-execution.enabled | `true` | This property is used to determine if a task should listen for batch step execution events.
|spring.cloud.task.batch.fail-on-job-failure | `false` | This property is used to determine if a task app should return with a non zero exit code if a batch job fails.
|spring.cloud.task.batch.fail-on-job-failure-poll-interval | `5000` | Fixed delay in milliseconds that Spring Cloud Task will wait when checking if {@link org.springframework.batch.core.JobExecution}s have completed, when spring.cloud.task.batch.failOnJobFailure is set to true. Defaults to 5000.
|spring.cloud.task.batch.job-names | | Comma-separated list of job names to execute on startup (for instance, `job1,job2`). By default, all Jobs found in the context are executed. @deprecated use spring.batch.job.names instead of spring.cloud.task.batch.jobNames.
|spring.cloud.task.batch.listener.enabled | `true` | This property is used to determine if a task will be linked to the batch jobs that are run.
|spring.cloud.task.closecontext-enabled | `false` | When set to true the context is closed at the end of the task. Else the context remains open.
|spring.cloud.task.events.enabled | `true` | This property is used to determine if a task app should emit task events.
|spring.cloud.task.executionid | | An id that will be used by the task when updating the task execution.
|spring.cloud.task.external-execution-id | | An id that can be associated with a task.
|spring.cloud.task.initialize-enabled | | If set to true then tables are initialized. If set to false tables are not initialized. Defaults to null. The requirement for it to be defaulted to null is so that we can support the <code>spring.cloud.task.initialize.enable</code> until it is removed.
|spring.cloud.task.parent-execution-id | | The id of the parent task execution id that launched this task execution. Defaults to null if task execution had no parent.
|spring.cloud.task.single-instance-enabled | `false` | This property is used to determine if a task will execute if another task with the same app name is running.
|spring.cloud.task.single-instance-lock-check-interval | `500` | Declares the time (in millis) that a task execution will wait between checks. Default time is: 500 millis.
|spring.cloud.task.single-instance-lock-ttl | | Declares the maximum amount of time (in millis) that a task execution can hold a lock to prevent another task from executing with a specific task name when the single-instance-enabled is set to true. Default time is: Integer.MAX_VALUE.
|spring.cloud.task.table-prefix | `TASK_` | The prefix to append to the table names created by Spring Cloud Task.
|===

29
docs/src/main/asciidoc/_index.adoc Normal file
View File

@@ -0,0 +1,29 @@
= Spring Cloud Task Reference Guide
Michael Minella, Glenn Renfro, Jay Bryant
include::_attributes.adoc[]
// ======================================================================================
(C) 2009-2020 VMware, Inc. All rights reserved.
Copies of this document may be made for your own use and for distribution to
others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in
print or electronically.
include::preface.adoc[]
include::getting-started.adoc[]
include::features.adoc[]
include::batch.adoc[]
include::batch-starter.adoc[]
include::stream.adoc[]
include::appendix.adoc[]
// ======================================================================================

29
docs/src/main/asciidoc/_index_pdf.adoc Normal file
View File

@@ -0,0 +1,29 @@
= Spring Cloud Task Reference Guide
Michael Minella, Glenn Renfro, Jay Bryant
include::_attributes.adoc[]
// ======================================================================================
(C) 2009-2020 VMware, Inc. All rights reserved.
Copies of this document may be made for your own use and for distribution to
others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in
print or electronically.
include::preface.adoc[leveloffset=+1]
include::getting-started.adoc[leveloffset=+1]
include::features.adoc[leveloffset=+1]
include::batch.adoc[leveloffset=+1]
include::batch-starter.adoc[leveloffset=+1]
include::stream.adoc[leveloffset=+1]
include::appendix.adoc[leveloffset=+1]
// ======================================================================================

29
docs/src/main/asciidoc/_index_single.adoc Normal file
View File

@@ -0,0 +1,29 @@
= Spring Cloud Task Reference Guide
Michael Minella, Glenn Renfro, Jay Bryant
include::_attributes.adoc[]
// ======================================================================================
(C) 2009-2020 VMware, Inc. All rights reserved.
Copies of this document may be made for your own use and for distribution to
others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in
print or electronically.
include::preface.adoc[leveloffset=+1]
include::getting-started.adoc[leveloffset=+1]
include::features.adoc[leveloffset=+1]
include::batch.adoc[leveloffset=+1]
include::batch-starter.adoc[leveloffset=+1]
include::stream.adoc[leveloffset=+1]
include::appendix.adoc[leveloffset=+1]
// ======================================================================================

6
docs/src/main/asciidoc/appendix-building-the-documentation.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[appendix-building-the-documentation]]
== Building This Documentation
This project uses Maven to generate this documentation. To generate it for yourself,
run the following command: `$ ./mvnw clean package -P full`.

12
docs/src/main/asciidoc/appendix-cloud-foundry.adoc Normal file
View File

@@ -0,0 +1,12 @@
[[appendix-cloud-foundry]]
== Running a Task App on Cloud Foundry
The simplest way to launch a Spring Cloud Task application as a task on Cloud Foundry
is to use Spring Cloud Data Flow. Via Spring Cloud Data Flow you can register your task application,
create a definition for it and then launch it. You then can track the task execution(s)
via a RESTful API, the Spring Cloud Data Flow Shell, or the UI. To learn out to get started installing Data Flow
follow the instructions in the
https://docs.spring.io/spring-cloud-dataflow/docs/current/reference/htmlsingle/#getting-started[Getting Started]
section of the reference documentation. For info on how to register and launch tasks, see the https://docs.spring.io/spring-cloud-dataflow/docs/current/reference/htmlsingle/#_the_lifecycle_of_a_task[Lifecycle of a Task] documentation.

85
docs/src/main/asciidoc/appendix-task-repository-schema.adoc Normal file
View File

@@ -0,0 +1,85 @@
[[appendix-task-repository-schema]]
== Task Repository Schema
[[partintro]]
--
This appendix provides an ERD for the database schema used in the task repository.
--
image::task_schema.png[]
=== Table Information
--
.TASK_EXECUTION
Stores the task execution information.
[width="80%", cols="1,1,1,1,10", options="header"]
|=========================================================
|Column Name |Required |Type |Field Length |Notes
|TASK_EXECUTION_ID |TRUE |BIGINT | X |
Spring Cloud Task Framework at app startup establishes the next available id as obtained from the `TASK_SEQ`. Or if the record is created outside of task then the value must be populated at record creation time.
|START_TIME |FALSE | DATETIME | X | Spring Cloud Task Framework at app startup establishes the value.
|END_TIME |FALSE | DATETIME | X | Spring Cloud Task Framework at app exit establishes the value.
|TASK_NAME |FALSE | VARCHAR | 100 | Spring Cloud Task Framework at app startup will set this to "Application" unless user establish the name using the spring.cloud.task.name as discussed <<features-task-name,here>>
|EXIT_CODE |FALSE | INTEGER | X | Follows Spring Boot defaults unless overridden by the user as discussed https://docs.spring.io/spring-cloud-task/docs/current/reference/#features-lifecycle-exit-codes[here].
|EXIT_MESSAGE |FALSE | VARCHAR | 2500 | User Defined as discussed https://docs.spring.io/spring-cloud-task/docs/current/reference/#features-task-execution-listener-exit-messages[here].
|ERROR_MESSAGE |FALSE | VARCHAR | 2500 | Spring Cloud Task Framework at app exit establishes the value.
|LAST_UPDATED |TRUE | DATETIME | X | Spring Cloud Task Framework at app startup establishes the value. Or if the record is created outside of task then the value must be populated at record creation time.
|EXTERNAL_EXECUTION_ID |FALSE | VARCHAR | 250 | If the `spring.cloud.task.external-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found <<features-external_task_id,here>>
|PARENT_TASK_EXECUTION_ID |FALSE |BIGINT | X | If the `spring.cloud.task.parent-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found <<features-parent_task_id,here>>
|=========================================================
.TASK_EXECUTION_PARAMS
Stores the parameters used for a task execution
[width="80%", cols="1,1,1,1", options="header"]
|=========================================================
|Column Name |Required |Type |Field Length
|TASK_EXECUTION_ID |TRUE |BIGINT | X
|TASK_PARAM |FALSE | VARCHAR | 2500
|=========================================================
.TASK_TASK_BATCH
Used to link the task execution to the batch execution.
[width="80%", cols="1,1,1,1", options="header"]
|=========================================================
|Column Name |Required |Type |Field Length
|TASK_EXECUTION_ID |TRUE |BIGINT | X
|JOB_EXECUTION_ID |TRUE | BIGINT | X
|=========================================================
.TASK_LOCK
Used for the `single-instance-enabled` feature discussed <<features-single-instance-enabled,here>>.
[width="80%", cols="1,1,1,1,10", options="header"]
|=========================================================
|Column Name |Required |Type | Field Length |Notes
|LOCK_KEY |TRUE |CHAR | 36 | UUID for the this lock
|REGION |TRUE | VARCHAR | 100 | User can establish a group of locks using this field.
|CLIENT_ID |TRUE | CHAR | 36 | The task execution id that contains the name of the app to lock.
|CREATED_DATE |TRUE | DATETIME | X | The date that the entry was created
|=========================================================
NOTE: The DDL for setting up tables for each database type can be found https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-core/src/main/resources/org/springframework/cloud/task[here].
--

7
docs/src/main/asciidoc/appendix.adoc Normal file
View File

@@ -0,0 +1,7 @@
[[appendix]]
= Appendices
include::appendix-task-repository-schema.adoc[]
include::appendix-building-the-documentation.adoc[]
include::appendix-cloud-foundry.adoc[]

533
docs/src/main/asciidoc/batch-starter.adoc Normal file
View File

@@ -0,0 +1,533 @@
[[batch-job-starter]]
= Single Step Batch Job Starter
[[partintro]]
--
This section goes into how to develop a Spring Batch `Job` with a single `Step` by using the
starter included in Spring Cloud Task. This starter lets you use configuration
to define an `ItemReader`, an `ItemWriter`, or a full single-step Spring Batch `Job`.
For more about Spring Batch and its capabilities, see the
https://spring.io/projects/spring-batch[Spring Batch documentation].
--
To obtain the starter for Maven, add the following to your build:
====
[source,xml]
----
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-single-step-batch-job</artifactId>
<version>2.3.0</version>
</dependency>
----
====
To obtain the starter for Gradle, add the following to your build:
====
[source,groovy]
----
compile "org.springframework.cloud:spring-cloud-starter-single-step-batch-job:2.3.0"
----
====
[[job-definition]]
== Defining a Job
You can use the starter to define as little as an `ItemReader` or an `ItemWriter` or as much as a full `Job`.
In this section, we define which properties are required to be defined to configure a
`Job`.
[[job-definition-properties]]
=== Properties
To begin, the starter provides a set of properties that let you configure the basics of a Job with one Step:
.Job Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.jobName`
| `String`
| `null`
| The name of the job.
| `spring.batch.job.stepName`
| `String`
| `null`
| The name of the step.
| `spring.batch.job.chunkSize`
| `Integer`
| `null`
| The number of items to be processed per transaction.
|===
With the above properties configured, you have a job with a single, chunk-based step.
This chunk-based step reads, processes, and writes `Map<String, Object>` instances as the
items. However, the step does not yet do anything. You need to configure an `ItemReader`, an
optional `ItemProcessor`, and an `ItemWiter` to give it something to do. To configure one
of these, you can either use properties and configure one of the options that has provided
autoconfiguration or you can configure your own with the standard Spring configuration
mechanisms.
NOTE: If you configure your own, the input and output types must match the others in the step.
The `ItemReader` implementations and `ItemWriter` implementations in this starter all use
a `Map<String, Object>` as the input and the output item.
[[item-readers]]
== Autoconfiguration for ItemReader Implementations
This starter provides autoconfiguration for four different `ItemReader` implementations:
`AmqpItemReader`, `FlatFileItemReader`, `JdbcCursorItemReader`, and `KafkaItemReader`.
In this section, we outline how to configure each of these by using the provided
autoconfiguration.
[[amqpitemreader]]
=== AmqpItemReader
You can read from a queue or topic with AMQP by using the `AmqpItemReader`. The
autoconfiguration for this `ItemReader` implementation is dependent upon two sets of
configuration. The first is the configuration of an `AmqpTemplate`. You can either
configure this yourself or use the autoconfiguration provided by Spring Boot. See the
https://docs.spring.io/spring-boot/docs/2.4.x/reference/htmlsingle/#boot-features-amqp[Spring Boot AMQP documentation].
Once you have configured the `AmqpTemplate`, you can enable the batch capabilities to support it
by setting the following properties:
.`AmqpItemReader` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.amqpitemreader.enabled`
| `boolean`
| `false`
| If `true`, the autoconfiguration will execute.
| `spring.batch.job.amqpitemreader.jsonConverterEnabled`
| `boolean`
| `true`
| Indicates if the `Jackson2JsonMessageConverter` should be registered to parse messages.
|===
For more information, see the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/amqp/AmqpItemReader.html[`AmqpItemReader` documentation].
[[flatfileitemreader]]
=== FlatFileItemReader
`FlatFileItemReader` lets you read from flat files (such as CSVs
and other file formats). To read from a file, you can provide some components
yourself through normal Spring configuration (`LineTokenizer`, `RecordSeparatorPolicy`,
`FieldSetMapper`, `LineMapper`, or `SkippedLinesCallback`). You can also use the
following properties to configure the reader:
.`FlatFileItemReader` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.flatfileitemreader.saveState`
| `boolean`
| `true`
| Determines if the state should be saved for restarts.
| `spring.batch.job.flatfileitemreader.name`
| `String`
| `null`
| Name used to provide unique keys in the `ExecutionContext`.
| `spring.batch.job.flatfileitemreader.maxItemcount`
| `int`
| `Integer.MAX_VALUE`
| Maximum number of items to be read from the file.
| `spring.batch.job.flatfileitemreader.currentItemCount`
| `int`
| 0
| Number of items that have already been read. Used on restarts.
| `spring.batch.job.flatfileitemreader.comments`
| `List<String>`
| empty List
| A list of Strings that indicate commented lines (lines to be ignored) in the file.
| `spring.batch.job.flatfileitemreader.resource`
| `Resource`
| `null`
| The resource to be read.
| `spring.batch.job.flatfileitemreader.strict`
| `boolean`
| `true`
| If set to `true`, the reader throws an exception if the resource is not found.
| `spring.batch.job.flatfileitemreader.encoding`
| `String`
| `FlatFileItemReader.DEFAULT_CHARSET`
| Encoding to be used when reading the file.
| `spring.batch.job.flatfileitemreader.linesToSkip`
| `int`
| 0
| Indicates the number of lines to skip at the start of a file.
| `spring.batch.job.flatfileitemreader.delimited`
| `boolean`
| `false`
| Indicates whether the file is a delimited file (CSV and other formats). Only one of this property or `spring.batch.job.flatfileitemreader.fixedLength` can be `true` at the same time.
| `spring.batch.job.flatfileitemreader.delimiter`
| `String`
| `DelimitedLineTokenizer.DELIMITER_COMMA`
| If reading a delimited file, indicates the delimiter to parse on.
| `spring.batch.job.flatfileitemreader.quoteCharacter`
| `char`
| `DelimitedLineTokenizer.DEFAULT_QUOTE_CHARACTER`
| Used to determine the character used to quote values.
| `spring.batch.job.flatfileitemreader.includedFields`
| `List<Integer>`
| empty list
| A list of indices to determine which fields in a record to include in the item.
| `spring.batch.job.flatfileitemreader.fixedLength`
| `boolean`
| `false`
| Indicates if a file's records are parsed by column numbers. Only one of this property or `spring.batch.job.flatfileitemreader.delimited` can be `true` at the same time.
| `spring.batch.job.flatfileitemreader.ranges`
| `List<Range>`
| empty list
| List of column ranges by which to parse a fixed width record. See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/file/transform/Range.html[Range documentation].
| `spring.batch.job.flatfileitemreader.names`
| `String []`
| `null`
| List of names for each field parsed from a record. These names are the keys in the `Map<String, Object>` in the items returned from this `ItemReader`.
| `spring.batch.job.flatfileitemreader.parsingStrict`
| `boolean`
| `true`
| If set to `true`, the mapping fails if the fields cannot be mapped.
|===
See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/file/FlatFileItemReader.html[`FlatFileItemReader` documentation].
[[jdbcCursorItemReader]]
=== JdbcCursorItemReader
The `JdbcCursorItemReader` runs a query against a relational database and iterates over
the resulting cursor (`ResultSet`) to provide the resulting items. This autoconfiguration
lets you provide a `PreparedStatementSetter`, a `RowMapper`, or both. You
can also use the following properties to configure a `JdbcCursorItemReader`:
.`JdbcCursorItemReader` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.jdbccursoritemreader.saveState`
| `boolean`
| `true`
| Determines whether the state should be saved for restarts.
| `spring.batch.job.jdbccursoritemreader.name`
| `String`
| `null`
| Name used to provide unique keys in the `ExecutionContext`.
| `spring.batch.job.jdbccursoritemreader.maxItemcount`
| `int`
| `Integer.MAX_VALUE`
| Maximum number of items to be read from the file.
| `spring.batch.job.jdbccursoritemreader.currentItemCount`
| `int`
| 0
| Number of items that have already been read. Used on restarts.
| `spring.batch.job.jdbccursoritemreader.fetchSize`
| `int`
|
| A hint to the driver to indicate how many records to retrieve per call to the database system. For best performance, you usually want to set it to match the chunk size.
| `spring.batch.job.jdbccursoritemreader.maxRows`
| `int`
|
| Maximum number of items to read from the database.
| `spring.batch.job.jdbccursoritemreader.queryTimeout`
| `int`
|
| Number of milliseconds for the query to timeout.
| `spring.batch.job.jdbccursoritemreader.ignoreWarnings`
| `boolean`
| `true`
| Determines whether the reader should ignore SQL warnings when processing.
| `spring.batch.job.jdbccursoritemreader.verifyCursorPosition`
| `boolean`
| `true`
| Indicates whether the cursor's position should be verified after each read to verify that the `RowMapper` did not advance the cursor.
| `spring.batch.job.jdbccursoritemreader.driverSupportsAbsolute`
| `boolean`
| `false`
| Indicates whether the driver supports absolute positioning of a cursor.
| `spring.batch.job.jdbccursoritemreader.useSharedExtendedConnection`
| `boolean`
| `false`
| Indicates whether the connection is shared with other processing (and is therefore part of a transaction).
| `spring.batch.job.jdbccursoritemreader.sql`
| `String`
| `null`
| SQL query from which to read.
|===
See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/database/JdbcCursorItemReader.html[`JdbcCursorItemReader` documentation].
[[kafkaItemReader]]
=== KafkaItemReader
Ingesting a partition of data from a Kafka topic is useful and exactly what the
`KafkaItemReader` can do. To configure a `KafkaItemReader`, two pieces
of configuration are required. First, configuring Kafka with Spring Boot's Kafka
autoconfiguration is required (see the
https://docs.spring.io/spring-boot/docs/2.4.x/reference/htmlsingle/#boot-features-kafka[Spring Boot Kafka documentation]).
Once you have configured the Kafka properties from Spring Boot, you can configure the `KafkaItemReader`
itself by setting the following properties:
.`KafkaItemReader` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.kafkaitemreader.name`
| `String`
| `null`
| Name used to provide unique keys in the `ExecutionContext`.
| `spring.batch.job.kafkaitemreader.topic`
| `String`
| `null`
| Name of the topic from which to read.
| `spring.batch.job.kafkaitemreader.partitions`
| `List<Integer>`
| empty list
| List of partition indices from which to read.
| `spring.batch.job.kafkaitemreader.pollTimeOutInSeconds`
| `long`
| 30
| Timeout for the `poll()` operations.
| `spring.batch.job.kafkaitemreader.saveState`
| `boolean`
| `true`
| Determines whether the state should be saved for restarts.
|===
See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/kafka/KafkaItemReader.html[`KafkaItemReader` documentation].
[[item-processors]]
== ItemProcessor Configuration
The single-step batch job autoconfiguration accepts an `ItemProcessor` if one
is available within the `ApplicationContext`. If one is found of the correct type
(`ItemProcessor<Map<String, Object>, Map<String, Object>>`), it is autowired
into the step.
[[item-writers]]
== Autoconfiguration for ItemWriter implementations
This starter provides autoconfiguration for `ItemWriter` implementations that
match the supported `ItemReader` implementations: `AmqpItemWriter`,
`FlatFileItemWriter`, `JdbcItemWriter`, and `KafkaItemWriter`. This section
covers how to use autoconfiguration to configure a supported `ItemWriter`.
[[amqpitemwriter]]
=== AmqpItemWriter
To write to a RabbitMQ queue, you need two sets of configuration. First, you need an
`AmqpTemplate`. The easiest way to get this is by using Spring Boot's
RabbitMQ autoconfiguration. See the https://docs.spring.io/spring-boot/docs/2.4.x/reference/htmlsingle/#boot-features-amqp[Spring Boot RabbitMQ documentation].
Once you have configured the `AmqpTemplate`, you can configure the `AmqpItemWriter` by setting the
following properties:
.`AmqpItemWriter` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.amqpitemwriter.enabled`
| `boolean`
| `false`
| If `true`, the autoconfiguration runs.
| `spring.batch.job.amqpitemwriter.jsonConverterEnabled`
| `boolean`
| `true`
| Indicates whether `Jackson2JsonMessageConverter` should be registered to convert messages.
|===
[[flatfileitemwriter]]
=== FlatFileItemWriter
To write a file as the output of the step, you can configure `FlatFileItemWriter`.
Autoconfiguration accepts components that have been explicitly configured (such as `LineAggregator`,
`FieldExtractor`, `FlatFileHeaderCallback`, or a `FlatFileFooterCallback`) and
components that have been configured by setting the following properties specified:
.`FlatFileItemWriter` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.flatfileitemwriter.resource`
| `Resource`
| `null`
| The resource to be read.
| `spring.batch.job.flatfileitemwriter.delimited`
| `boolean`
| `false`
| Indicates whether the output file is a delimited file. If `true`, `spring.batch.job.flatfileitemwriter.formatted` must be `false`.
| `spring.batch.job.flatfileitemwriter.formatted`
| `boolean`
| `false`
| Indicates whether the output file a formatted file. If `true`, `spring.batch.job.flatfileitemwriter.delimited` must be `false`.
| `spring.batch.job.flatfileitemwriter.format`
| `String`
| `null`
| The format used to generate the output for a formatted file. The formatting is performed by using `String.format`.
| `spring.batch.job.flatfileitemwriter.locale`
| `Locale`
| `Locale.getDefault()`
| The `Locale` to be used when generating the file.
| `spring.batch.job.flatfileitemwriter.maximumLength`
| `int`
| 0
| Max length of the record. If 0, the size is unbounded.
| `spring.batch.job.flatfileitemwriter.minimumLength`
| `int`
| 0
| The minimum record length.
| `spring.batch.job.flatfileitemwriter.delimiter`
| `String`
| `,`
| The `String` used to delimit fields in a delimited file.
| `spring.batch.job.flatfileitemwriter.encoding`
| `String`
| `FlatFileItemReader.DEFAULT_CHARSET`
| Encoding to use when writing the file.
| `spring.batch.job.flatfileitemwriter.forceSync`
| `boolean`
| `false`
| Indicates whether a file should be force-synced to the disk on flush.
| `spring.batch.job.flatfileitemwriter.names`
| `String []`
| `null`
| List of names for each field parsed from a record. These names are the keys in the `Map<String, Object>` for the items received by this `ItemWriter`.
| `spring.batch.job.flatfileitemwriter.append`
| `boolean`
| `false`
| Indicates whether a file should be appended to if the output file is found.
| `spring.batch.job.flatfileitemwriter.lineSeparator`
| `String`
| `FlatFileItemWriter.DEFAULT_LINE_SEPARATOR`
| What `String` to use to separate lines in the output file.
| `spring.batch.job.flatfileitemwriter.name`
| `String`
| `null`
| Name used to provide unique keys in the `ExecutionContext`.
| `spring.batch.job.flatfileitemwriter.saveState`
| `boolean`
| `true`
| Determines whether the state should be saved for restarts.
| `spring.batch.job.flatfileitemwriter.shouldDeleteIfEmpty`
| `boolean`
| `false`
| If set to `true`, an empty file (there is no output) is deleted when the job completes.
| `spring.batch.job.flatfileitemwriter.shouldDeleteIfExists`
| `boolean`
| `true`
| If set to `true` and a file is found where the output file should be, it is deleted before the step begins.
| `spring.batch.job.flatfileitemwriter.transactional`
| `boolean`
| `FlatFileItemWriter.DEFAULT_TRANSACTIONAL`
| Indicates whether the reader is a transactional queue (indicating that the items read are returned to the queue upon a failure).
|===
See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/file/FlatFileItemWriter.html[`FlatFileItemWriter` documentation].
[[jdbcitemwriter]]
=== JdbcBatchItemWriter
To write the output of a step to a relational database, this starter provides the ability
to autoconfigure a `JdbcBatchItemWriter`. The autoconfiguration lets you provide your
own `ItemPreparedStatementSetter` or `ItemSqlParameterSourceProvider` and
configuration options by setting the following properties:
.`JdbcBatchItemWriter` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.jdbcbatchitemwriter.name`
| `String`
| `null`
| Name used to provide unique keys in the `ExecutionContext`.
| `spring.batch.job.jdbcbatchitemwriter.sql`
| `String`
| `null`
| The SQL used to insert each item.
| `spring.batch.job.jdbcbatchitemwriter.assertUpdates`
| `boolean`
| `true`
| Whether to verify that every insert results in the update of at least one record.
|===
See the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/database/JdbcBatchItemWriter.html[`JdbcBatchItemWriter` documentation].
[[kafkaitemwriter]]
=== KafkaItemWriter
To write step output to a Kafka topic, you need `KafkaItemWriter`. This starter
provides autoconfiguration for a `KafkaItemWriter` by using facilities from two places.
The first is Spring Boot's Kafka autoconfiguration. (See the https://docs.spring.io/spring-boot/docs/2.4.x/reference/htmlsingle/#boot-features-kafka[Spring Boot Kafka documentation].)
Second, this starter lets you configure two properties on the writer.
.`KafkaItemWriter` Properties
|===
| Property | Type | Default Value | Description
| `spring.batch.job.kafkaitemwriter.topic`
| `String`
| `null`
| The Kafka topic to which to write.
| `spring.batch.job.kafkaitemwriter.delete`
| `boolean`
| `false`
| Whether the items being passed to the writer are all to be sent as delete events to the topic.
|===
For more about the configuration options for the `KafkaItemWiter`, see the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/kafka/KafkaItemWriter.html[`KafkaItemWiter` documentation].

236
docs/src/main/asciidoc/batch.adoc Normal file
View File

@@ -0,0 +1,236 @@
[[batch]]
= Batch
[[partintro]]
--
This section goes into more detail about Spring Cloud Task's integration with Spring
Batch. Tracking the association between a job execution and the task in which it was
executed as well as remote partitioning through Spring Cloud Deployer are covered in
this section.
--
[[batch-association]]
== Associating a Job Execution to the Task in which It Was Executed
Spring Boot provides facilities for the execution of batch jobs within an über-jar.
Spring Boot's support of this functionality lets a developer execute multiple batch jobs
within that execution. Spring Cloud Task provides the ability to associate the execution
of a job (a job execution) with a task's execution so that one can be traced back to the
other.
Spring Cloud Task achieves this functionality by using the `TaskBatchExecutionListener`.
By default,
this listener is auto configured in any context that has both a Spring Batch Job
configured (by having a bean of type `Job` defined in the context) and the
`spring-cloud-task-batch` jar on the classpath. The listener is injected into all jobs
that meet those conditions.
[[batch-association-override]]
=== Overriding the TaskBatchExecutionListener
To prevent the listener from being injected into any batch jobs within the current
context, you can disable the autoconfiguration by using standard Spring Boot mechanisms.
To only have the listener injected into particular jobs within the context, override the
`batchTaskExecutionListenerBeanPostProcessor` and provide a list of job bean IDs, as shown
in the following example:
[source,java]
----
public TaskBatchExecutionListenerBeanPostProcessor batchTaskExecutionListenerBeanPostProcessor() {
TaskBatchExecutionListenerBeanPostProcessor postProcessor =
new TaskBatchExecutionListenerBeanPostProcessor();
postProcessor.setJobNames(Arrays.asList(new String[] {"job1", "job2"}));
return postProcessor;
}
----
NOTE: You can find a sample batch application in the samples module of the Spring Cloud
Task Project,
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/batch-job[here].
[[batch-partitioning]]
== Remote Partitioning
Spring Cloud Deployer provides facilities for launching Spring Boot-based applications on
most cloud infrastructures. The `DeployerPartitionHandler` and
`DeployerStepExecutionHandler` delegate the launching of worker step executions to Spring
Cloud Deployer.
To configure the `DeployerStepExecutionHandler`, you must provide a `Resource`
representing the Spring Boot über-jar to be executed, a `TaskLauncher`, and a
`JobExplorer`. You can configure any environment properties as well as the max number of
workers to be executing at once, the interval to poll for the results (defaults to 10
seconds), and a timeout (defaults to -1 or no timeout). The following example shows how
configuring this `PartitionHandler` might look:
[source,java]
----
@Bean
public PartitionHandler partitionHandler(TaskLauncher taskLauncher,
JobExplorer jobExplorer) throws Exception {
MavenProperties mavenProperties = new MavenProperties();
mavenProperties.setRemoteRepositories(new HashMap<>(Collections.singletonMap("springRepo",
new MavenProperties.RemoteRepository(repository))));
Resource resource =
MavenResource.parse(String.format("%s:%s:%s",
"io.spring.cloud",
"partitioned-batch-job",
"1.1.0.RELEASE"), mavenProperties);
DeployerPartitionHandler partitionHandler =
new DeployerPartitionHandler(taskLauncher, jobExplorer, resource, "workerStep");
List<String> commandLineArgs = new ArrayList<>(3);
commandLineArgs.add("--spring.profiles.active=worker");
commandLineArgs.add("--spring.cloud.task.initialize.enable=false");
commandLineArgs.add("--spring.batch.initializer.enabled=false");
partitionHandler.setCommandLineArgsProvider(
new PassThroughCommandLineArgsProvider(commandLineArgs));
partitionHandler.setEnvironmentVariablesProvider(new NoOpEnvironmentVariablesProvider());
partitionHandler.setMaxWorkers(2);
partitionHandler.setApplicationName("PartitionedBatchJobTask");
return partitionHandler;
}
----
NOTE: When passing environment variables to partitions, each partition may
be on a different machine with different environment settings.
Consequently, you should pass only those environment variables that are required.
Notice in the example above that we have set the maximum number of workers to 2.
Setting the maximum of workers establishes the maximum number of
partitions that should be running at one time.
The `Resource` to be executed is expected to be a Spring Boot über-jar with a
`DeployerStepExecutionHandler` configured as a `CommandLineRunner` in the current context.
The repository enumerated in the preceding example should be the remote repository in
which the über-jar is located. Both the manager and worker are expected to have visibility
into the same data store being used as the job repository and task repository. Once the
underlying infrastructure has bootstrapped the Spring Boot jar and Spring Boot has
launched the `DeployerStepExecutionHandler`, the step handler executes the requested
`Step`. The following example shows how to configure the `DeployerStepExecutionHandler`:
[source,java]
----
@Bean
public DeployerStepExecutionHandler stepExecutionHandler(JobExplorer jobExplorer) {
DeployerStepExecutionHandler handler =
new DeployerStepExecutionHandler(this.context, jobExplorer, this.jobRepository);
return handler;
}
----
NOTE: You can find a sample remote partition application in the samples module of the
Spring Cloud Task project,
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/partitioned-batch-job[here].
=== Notes on Developing a Batch-partitioned application for the Kubernetes Platform
* When deploying partitioned apps on the Kubernetes platform, you must use the following
dependency for the Spring Cloud Kubernetes Deployer:
+
[source,xml]
----
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-deployer-kubernetes</artifactId>
</dependency>
----
* The application name for the task application and its partitions need to follow
the following regex pattern: `[a-z0-9]([-a-z0-9]*[a-z0-9])`.
Otherwise, an exception is thrown.
=== Notes on Developing a Batch-partitioned Application for the Cloud Foundry Platform
* When deploying partitioned apps on the Cloud Foundry platform, you must use the
following dependencies for the Spring Cloud Foundry Deployer:
+
[source,xml]
----
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-deployer-cloudfoundry</artifactId>
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId>
<version>3.1.5.RELEASE</version>
</dependency>
<dependency>
<groupId>io.projectreactor.ipc</groupId>
<artifactId>reactor-netty</artifactId>
<version>0.7.5.RELEASE</version>
</dependency>
----
* When configuring the partition handler, Cloud Foundry Deployment
environment variables need to be established so that the partition handler
can start the partitions. The following list shows the required environment
variables:
- `spring_cloud_deployer_cloudfoundry_url`
- `spring_cloud_deployer_cloudfoundry_org`
- `spring_cloud_deployer_cloudfoundry_space`
- `spring_cloud_deployer_cloudfoundry_domain`
- `spring_cloud_deployer_cloudfoundry_username`
- `spring_cloud_deployer_cloudfoundry_password`
- `spring_cloud_deployer_cloudfoundry_services`
- `spring_cloud_deployer_cloudfoundry_taskTimeout`
An example set of deployment environment variables for a partitioned task that
uses a `mysql` database service might resemble the following:
[source,bash]
----
spring_cloud_deployer_cloudfoundry_url=https://api.local.pcfdev.io
spring_cloud_deployer_cloudfoundry_org=pcfdev-org
spring_cloud_deployer_cloudfoundry_space=pcfdev-space
spring_cloud_deployer_cloudfoundry_domain=local.pcfdev.io
spring_cloud_deployer_cloudfoundry_username=admin
spring_cloud_deployer_cloudfoundry_password=admin
spring_cloud_deployer_cloudfoundry_services=mysql
spring_cloud_deployer_cloudfoundry_taskTimeout=300
----
NOTE: When using PCF-Dev, the following environment variable is also required:
`spring_cloud_deployer_cloudfoundry_skipSslValidation=true`
[[batch-informational-messages]]
== Batch Informational Messages
Spring Cloud Task provides the ability for batch jobs to emit informational messages. The
"`<<stream.adoc#stream-integration-batch-events>>`" section covers this feature in detail.
[[batch-failures-and-tasks]]
== Batch Job Exit Codes
As discussed <<features.adoc#features-lifecycle-exit-codes,earlier>>, Spring Cloud Task
applications support the ability to record the exit code of a task execution. However, in
cases where you run a Spring Batch Job within a task, regardless of how the Batch Job
Execution completes, the result of the task is always zero when using the default
Batch/Boot behavior. Keep in mind that a task is a boot application and that the exit code
returned from the task is the same as a boot application.
To override this behavior and allow the task to return an exit code other than zero when a
batch job returns an
https://docs.spring.io/spring-batch/4.0.x/reference/html/step.html#batchStatusVsExitStatus[BatchStatus]
of `FAILED`, set `spring.cloud.task.batch.fail-on-job-failure` to `true`. Then the exit code
can be 1 (the default) or be based on the
https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-spring-application.html#boot-features-application-exit[specified
`ExitCodeGenerator`])
This functionality uses a new `CommandLineRunner` that replaces the one provided by Spring
Boot. By default, it is configured with the same order. However, if you want to customize
the order in which the `CommandLineRunner` is run, you can set its order by setting the
`spring.cloud.task.batch.commandLineRunnerOrder` property. To have your task return the
exit code based on the result of the batch job execution, you need to write your own
`CommandLineRunner`.
//TODO Great place for a example showing how a custom CommandLineRunner

415
docs/src/main/asciidoc/features.adoc Normal file
View File

@@ -0,0 +1,415 @@
[[features]]
= Features
[[partintro]]
--
This section goes into more detail about Spring Cloud Task, including how to use it, how
to configure it, and the appropriate extension points.
--
[[features-lifecycle]]
== The lifecycle of a Spring Cloud Task
In most cases, the modern cloud environment is designed around the execution of processes
that are not expected to end. If they do end, they are typically restarted. While most
platforms do have some way to run a process that is not restarted when it ends, the
results of that run are typically not maintained in a consumable way. Spring Cloud
Task offers the ability to execute short-lived processes in an environment and record the
results. Doing so allows for a microservices architecture around short-lived processes as
well as longer running services through 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 running Spring Boot applications with a
scheduler such as cron, it can be useful to be able to monitor the results of the
application after its completion.
Spring Cloud Task takes the approach that a Spring Boot application can have a start and
an end and still be successful. Batch applications are one example of how processes that
are expected to end (and that are often short-lived) can be helpful.
Spring Cloud Task records the lifecycle events of a given task. Most long-running
processes, typified by most web applications, do not save their lifecycle events. The
tasks at the heart of Spring Cloud Task do.
The lifecycle consists of a single task execution. This is a physical execution of a
Spring Boot application configured to be a task (that is, it has the Sprint Cloud Task dependencies).
At the beginning of a task, before any `CommandLineRunner` or `ApplicationRunner`
implementations have been run, an entry in the `TaskRepository` that records the start
event is created. This event is triggered through `SmartLifecycle#start` being triggered
by the Spring Framework. This indicates to the system that all beans are ready for use and
comes before running any of the `CommandLineRunner` or `ApplicationRunner` implementations
provided by Spring Boot.
NOTE: The recording of a task only occurs upon the successful bootstrapping of an
`ApplicationContext`. If the context fails to bootstrap at all, the task's run is not
recorded.
Upon completion of all of the `*Runner#run` calls from Spring Boot or the failure of an
`ApplicationContext` (indicated by an `ApplicationFailedEvent`), the task execution is
updated in the repository with the results.
NOTE: If the application requires the `ApplicationContext` to be closed at the
completion of a task (all `*Runner#run` methods have been called and the task
repository has been updated), set the property `spring.cloud.task.closecontextEnabled`
to true.
[[features-task-execution-details]]
=== The TaskExecution
The information stored in the `TaskRepository` is modeled in the `TaskExecution` class and
consists of the following information:
|===
|Field |Description
|`executionid`
|The unique ID for the task's run.
|`exitCode`
|The exit code generated from an `ExitCodeExceptionMapper` implementation. If there is no
exit code generated but an `ApplicationFailedEvent` is thrown, 1 is set. Otherwise, it is
assumed to be 0.
|`taskName`
|The name for the task, as determined by the configured `TaskNameResolver`.
|`startTime`
|The time the task was started, as indicated by the `SmartLifecycle#start` call.
|`endTime`
|The time the task was completed, as indicated by the `ApplicationReadyEvent`.
|`exitMessage`
|Any information available at the time of exit. This can programmatically be set by a
`TaskExecutionListener`.
|`errorMessage`
|If an exception is the cause of the end of the task (as indicated by an
`ApplicationFailedEvent`), the stack trace for that exception is stored here.
|`arguments`
|A `List` of the string command line arguments as they were passed into the executable
boot application.
|===
[[features-lifecycle-exit-codes]]
=== Mapping Exit Codes
When a task completes, it tries to return an exit code to the OS. If we take a look
at our <<getting-started-developing-first-task,original example>>, we can see that we are
not controlling that aspect of our application. So, if an exception is thrown, the JVM
returns a code that may or may not be of any use to you in debugging.
Consequently, Spring Boot provides an interface, `ExitCodeExceptionMapper`, that lets you
map uncaught exceptions to exit codes. Doing so lets you indicate, at the level of exit
codes, what went wrong. Also, by mapping exit codes in this manner, Spring Cloud Task
records the returned exit code.
If the task terminates with a SIG-INT or a SIG-TERM, the exit code is zero unless
otherwise specified within the code.
NOTE: While the task is running, the exit code is stored as a null in the repository.
Once the task completes, the appropriate exit code is stored based on the guidelines described
earlier in this section.
[[features-configuration]]
== Configuration
Spring Cloud Task provides a ready-to-use configuration, as defined in the
`DefaultTaskConfigurer` and `SimpleTaskConfiguration` classes. This section walks through
the defaults and how to customize Spring Cloud Task for your needs.
[[features-data-source]]
=== DataSource
Spring Cloud Task uses a datasource for storing the results of task executions. By
default, we provide an in-memory instance of H2 to provide a simple method of
bootstrapping development. However, in a production environment, you probably want to
configure your own `DataSource`.
If your application uses only a single `DataSource` and that serves as both your business
schema and the task repository, all you need to do is provide any `DataSource` (the
easiest way to do so is through Spring Boot's configuration conventions). This
`DataSource` is automatically used by Spring Cloud Task for the repository.
If your application uses more than one `DataSource`, you need to configure the task
repository with the appropriate `DataSource`. This customization can be done through an
implementation of `TaskConfigurer`.
[[features-table-prefix]]
=== Table Prefix
One modifiable property of `TaskRepository` is the table prefix for the task tables. By
default, they are all prefaced with `TASK_`. `TASK_EXECUTION` and `TASK_EXECUTION_PARAMS`
are two examples. However, there are potential reasons to modify this prefix. If the
schema name needs to be prepended to the table names or if more than one set of task
tables is needed within the same schema, you must change the table prefix. You can do so
by setting the `spring.cloud.task.tablePrefix` to the prefix you need, as follows:
`spring.cloud.task.tablePrefix=yourPrefix`
By using the `spring.cloud.task.tablePrefix`, a user assumes the responsibility to
create the task tables that meet both the criteria for the task table schema but
with modifications that are required for a user's business needs.
You can utilize the Spring Cloud Task Schema DDL as a guide when creating your own Task DDL as seen
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-core/src/main/resources/org/springframework/cloud/task[here].
[[features-table-initialization]]
=== Enable/Disable table initialization
In cases where you are creating the task tables and do not wish for Spring Cloud Task to
create them at task startup, set the `spring.cloud.task.initialize-enabled` property to
`false`, as follows:
`spring.cloud.task.initialize-enabled=false`
It defaults to `true`.
NOTE: The property `spring.cloud.task.initialize.enable` has been deprecated.
[[features-generated_task_id]]
=== Externally Generated Task ID
In some cases, you may want to allow for the time difference between when a task is
requested and when the infrastructure actually launches it. Spring Cloud Task lets you
create a `TaskExecution` when the task is requested. Then pass the execution ID of the
generated `TaskExecution` to the task so that it can update the `TaskExecution` through
the task's lifecycle.
A `TaskExecution` can be created by calling the `createTaskExecution` method on an
implementation of the `TaskRepository` that references the datastore that holds
the `TaskExecution` objects.
In order to configure your Task to use a generated `TaskExecutionId`, add the
following property:
`spring.cloud.task.executionid=yourtaskId`
[[features-external_task_id]]
=== External Task Id
Spring Cloud Task lets you store an external task ID for each
`TaskExecution`. An example of this would be a task ID provided by
Cloud Foundry when a task is launched on the platform.
In order to configure your Task to use a generated `TaskExecutionId`, add the
following property:
`spring.cloud.task.external-execution-id=<externalTaskId>`
[[features-parent_task_id]]
=== Parent Task Id
Spring Cloud Task lets you store a parent task ID for each `TaskExecution`. An example of
this would be a task that executes another task or tasks and you want to record which task
launched each of the child tasks. In order to configure your Task to set a parent
`TaskExecutionId` add the following property on the child task:
`spring.cloud.task.parent-execution-id=<parentExecutionTaskId>`
[[features-task-configurer]]
=== TaskConfigurer
The `TaskConfigurer` is a strategy interface that lets you customize the way components of
Spring Cloud Task are configured. By default, we provide the `DefaultTaskConfigurer` that
provides logical defaults: `Map`-based in-memory components (useful for development if no
`DataSource` is provided) and JDBC based components (useful if there is a `DataSource`
available).
The `TaskConfigurer` lets you configure three main components:
|===
|Component |Description |Default (provided by `DefaultTaskConfigurer`)
|`TaskRepository`
|The implementation of the `TaskRepository` to be used.
|`SimpleTaskRepository`
|`TaskExplorer`
|The implementation of the `TaskExplorer` (a component for read-only access to the task
repository) to be used.
|`SimpleTaskExplorer`
|`PlatformTransactionManager`
|A transaction manager to be used when running updates for tasks.
|`DataSourceTransactionManager` if a `DataSource` is used.
`ResourcelessTransactionManager` if it is not.
|===
You can customize any of the components described in the preceding table by creating a
custom implementation of the `TaskConfigurer` interface. Typically, extending the
`DefaultTaskConfigurer` (which is provided if a `TaskConfigurer` is not found) and
overriding the required getter is sufficient. However, implementing your own from scratch
may be required.
NOTE: Users should not directly use getter methods from a `TaskConfigurer` directly
unless they are using it to supply implementations to be exposed as Spring Beans.
[[features-task-name]]
=== Task Name
In most cases, the name of the task is the application name as configured in Spring
Boot. However, there are some cases where you may want to map the run of a task to a
different name. Spring Cloud Data Flow is an example of this (because you probably want
the task to be run with the name of the task definition). Because of this, we offer the
ability to customize how the task is named, through the `TaskNameResolver` interface.
By default, Spring Cloud Task provides the `SimpleTaskNameResolver`, which uses the
following options (in order of precedence):
. A Spring Boot property (configured in any of the ways Spring Boot allows) called
`spring.cloud.task.name`.
. The application name as resolved using Spring Boot's rules (obtained through
`ApplicationContext#getId`).
[[features-task-execution-listener]]
=== Task Execution Listener
`TaskExecutionListener` lets you register listeners for specific events that occur during
the task lifecycle. To do so, create a class that implements the
`TaskExecutionListener` interface. The class that implements the `TaskExecutionListener`
interface is notified of the following events:
* `onTaskStartup`: Prior to storing the `TaskExecution` into the `TaskRepository`.
* `onTaskEnd`: Prior to updating the `TaskExecution` entry in the `TaskRepository` and
marking the final state of the task.
* `onTaskFailed`: Prior to the `onTaskEnd` method being invoked when an unhandled
exception is thrown by the task.
Spring Cloud Task also lets you 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`
marking the final state of the task.
* `@FailedTask`: Prior to the `@AfterTask` method being invoked when an unhandled
exception is thrown by the task.
The following example shows the three annotations in use:
[source,java]
----
public class MyBean {
@BeforeTask
public void methodA(TaskExecution taskExecution) {
}
@AfterTask
public void methodB(TaskExecution taskExecution) {
}
@FailedTask
public void methodC(TaskExecution taskExecution, Throwable throwable) {
}
}
----
NOTE: Inserting an `ApplicationListener` earlier in the chain than `TaskLifecycleListener` exists may cause unexpected effects.
[[features-task-execution-listener-Exceptions]]
==== Exceptions Thrown by Task Execution Listener
If an exception is thrown by a `TaskExecutionListener` event handler, all listener
processing for that event handler stops. For example, if three `onTaskStartup` listeners
have started and the first `onTaskStartup` event handler throws an exception, the other
two `onTaskStartup` methods are not called. However, the other event handlers (`onTaskEnd`
and `onTaskFailed`) for the `TaskExecutionListeners` are called.
The exit code returned when a exception is thrown by a `TaskExecutionListener`
event handler is the exit code that was reported by the
https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/ExitCodeEvent.html[ExitCodeEvent].
If no `ExitCodeEvent` is emitted, the Exception thrown is evaluated to see
if it is of type
https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-application-exit[ExitCodeGenerator].
If so, it returns the exit code from the `ExitCodeGenerator`. Otherwise, `1`
is returned.
In the case that an exception is thrown in an `onTaskStartup` method, the exit code for the application will be `1`.
If an exception is thrown in either a `onTaskEnd` or `onTaskFailed`
method, the exit code for the application will be the one established using the rules enumerated above.
NOTE: In the case of an exception being thrown in a `onTaskStartup`, `onTaskEnd`, or `onTaskFailed`
you can not override the exit code for the application using `ExitCodeExceptionMapper`.
[[features-task-execution-listener-exit-messages]]
==== Exit Messages
You can set the exit message for a task programmatically by using a
`TaskExecutionListener`. This is done by setting the `TaskExecution's` `exitMessage`,
which then gets passed into the `TaskExecutionListener`. The following example shows
a method that is annotated with the `@AfterTask` `ExecutionListener` :
[source,java]
@AfterTask
public void afterMe(TaskExecution taskExecution) {
taskExecution.setExitMessage("AFTER EXIT MESSAGE");
}
An `ExitMessage` can be set at any of the listener events (`onTaskStartup`,
`onTaskFailed`, and `onTaskEnd`). The order of precedence for the three listeners follows:
. `onTaskEnd`
. `onTaskFailed`
. `onTaskStartup`
For example, if you set an `exitMessage` for the `onTaskStartup` and `onTaskFailed`
listeners and the task ends without failing, the `exitMessage` from the `onTaskStartup`
is stored in the repository. Otherwise, if a failure occurs, the `exitMessage` from
the `onTaskFailed` is stored. Also if you set the `exitMessage` with an
`onTaskEnd` listener, the `exitMessage` from the `onTaskEnd` supersedes
the exit messages from both the `onTaskStartup` and `onTaskFailed`.
[[features-single-instance-enabled]]
=== Restricting Spring Cloud Task Instances
Spring Cloud Task lets you establish that only one task with a given task name can be run
at a time. To do so, you need to establish the <<features-task-name, task name>> and set
`spring.cloud.task.single-instance-enabled=true` for each task execution. While the first
task execution is running, any other time you try to run a task with the same
<<features-task-name, task name>> and`spring.cloud.task.single-instance-enabled=true`, the
task fails with the following error message: `Task with name "application" is already
running.` The default value for `spring.cloud.task.single-instance-enabled` is `false`. The
following example shows how to set `spring.cloud.task.single-instance-enabled` to `true`:
`spring.cloud.task.single-instance-enabled=true or false`
To use this feature, you must add the following Spring Integration dependencies to your
application:
[source,xml]
<dependency>
<groupId>org.springframework.integration</groupId>
<artifactId>spring-integration-core</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.integration</groupId>
<artifactId>spring-integration-jdbc</artifactId>
</dependency>
NOTE: The exit code for the application will be 1 if the task fails because this feature
is enabled and another task is running with the same task name.
=== Disabling Spring Cloud Task Auto Configuration
In cases where Spring Cloud Task should not be auto configured for an implementation, you can disable Task's auto configuration.
This can be done either by adding the following annotation to your Task application:
```
@EnableAutoConfiguration(exclude={SimpleTaskAutoConfiguration.class})
```
You may also disable Task auto configuration by setting the `spring.cloud.task.autoconfiguration.enabled` property to `false`.
[[closing-the-context]]
=== Closing the Context
If the application requires the `ApplicationContext` to be closed at the
completion of a task (all `*Runner#run` methods have been called and the task
repository has been updated), set the property `spring.cloud.task.closecontextEnabled`
to `true`.
Another case to close the context is when the Task Execution completes however the application does not terminate.
In these cases the context is held open because a thread has been allocated
(for example: if you are using a TaskExecutor). In these cases
set the `spring.cloud.task.closecontextEnabled` property to `true` when launching your task.
This will close the application's context once the task is complete.
Thus allowing the application to terminate.

215
docs/src/main/asciidoc/getting-started.adoc Executable file
View File

@@ -0,0 +1,215 @@
[[getting-started]]
= Getting started
[[partintro]]
--
If you are just getting started with Spring Cloud Task, you should read this section.
Here, we answer the basic "`what?`", "`how?`", and "`why?`" questions. We start with a
gentle introduction to Spring Cloud Task. We then build a Spring Cloud Task application,
discussing some core principles as we go.
--
[[getting-started-introducing-spring-cloud-task]]
== Introducing Spring Cloud Task
Spring Cloud Task makes it easy to create short-lived microservices. It provides
capabilities that let short lived JVM processes be executed on demand in a production
environment.
[[getting-started-system-requirements]]
== System Requirements
You need to have Java installed (Java 8 or better). To build, you need to have Maven
installed as well.
=== Database Requirements
Spring Cloud Task uses a relational database to store the results of an executed task.
While you can begin developing a task without a database (the status of the task is logged
as part of the task repository's updates), for production environments, you want to
use a supported database. Spring Cloud Task currently supports the following databases:
* DB2
* H2
* HSQLDB
* MySql
* Oracle
* Postgres
* SqlServer
[[getting-started-developing-first-task]]
== Developing Your First Spring Cloud Task Application
A good place to start is with a simple "`Hello, World!`" application, so we create the
Spring Cloud Task equivalent to highlight the features of the framework. Most IDEs have
good support for Apache Maven, so we use it as the build tool for this project.
NOTE: The spring.io web site contains many https://spring.io/guides[“`Getting Started`”
guides] that use Spring Boot. If you need to solve a specific problem, check there first.
You can shortcut the following steps by going to the
https://start.spring.io/[Spring Initializr] and creating a new project. Doing so
automatically generates a new project structure so that you can start coding right away.
We recommend experimenting with the Spring Initializr to become familiar with it.
[[getting-started-creating-project]]
=== Creating the Spring Task Project using Spring Initializr
Now we can create and test an application that prints `Hello, World!` to the console.
To do so:
. Visit the link:https://start.spring.io/[Spring Initialzr] site.
.. Create a new Maven project with a *Group* name of `io.spring.demo` and an *Artifact* name of `helloworld`.
.. In the Dependencies text box, type `task` and then select the `Cloud Task` dependency.
.. In the Dependencies text box, type `jdbc` and then select the `JDBC` dependency.
.. In the Dependencies text box, type `h2` and then select the `H2`. (or your favorite database)
.. Click the *Generate Project* button
. Unzip the helloworld.zip file and import the project into your favorite IDE.
[[getting-started-writing-the-code]]
=== Writing the Code
To finish our application, we need to update the generated `HelloworldApplication` with the following contents so that it launches a Task.
[source,java]
----
package io.spring.demo.helloworld;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
@EnableTask
public class HelloworldApplication {
@Bean
public CommandLineRunner commandLineRunner() {
return new HelloWorldCommandLineRunner();
}
public static void main(String[] args) {
SpringApplication.run(HelloworldApplication.class, args);
}
public static class HelloWorldCommandLineRunner implements CommandLineRunner {
@Override
public void run(String... strings) throws Exception {
System.out.println("Hello, World!");
}
}
}
----
While it may seem small, quite a bit is going on. For more about Spring
Boot specifics, see the
https://docs.spring.io/spring-boot/docs/current/reference/html/[Spring Boot reference documentation].
Now we can open the `application.properties` file in `src/main/resources`.
We need to configure two properties in `application.properties`:
* `application.name`: To set the application name (which is translated to the task name)
* `logging.level`: To set the logging for Spring Cloud Task to `DEBUG` in order to
get a view of what is going on.
The following example shows how to do both:
[source]
----
logging.level.org.springframework.cloud.task=DEBUG
spring.application.name=helloWorld
----
[[getting-started-at-task]]
==== Task Auto Configuration
When including Spring Cloud Task Starter dependency, Task auto configures all beans to bootstrap it's functionality.
Part of this configuration registers the `TaskRepository` and the infrastructure for its use.
In our demo, the `TaskRepository` uses an embedded H2 database to record the results
of a task. This H2 embedded database is not a practical solution for a production environment, since
the H2 DB goes away once the task ends. However, for a quick getting-started
experience, we can use this in our example as well as echoing to the logs what is being updated
in that repository. In the <<features-configuration>> section (later in this
documentation), we cover how to customize the configuration of the pieces provided by
Spring Cloud Task.
When our sample application runs, Spring Boot launches our `HelloWorldCommandLineRunner`
and outputs our "`Hello, World!`" message to standard out. The `TaskLifecycleListener`
records the start of the task and the end of the task in the repository.
[[getting-started-main-method]]
==== The main method
The main method serves as the entry point to any java application. Our main method
delegates to Spring Boot's https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-spring-application.html[SpringApplication] class.
[[getting-started-clr]]
==== The CommandLineRunner
Spring includes many ways to bootstrap an application's logic. Spring Boot provides
a convenient method of doing so in an organized manner through its `*Runner` interfaces
(`CommandLineRunner` or `ApplicationRunner`). A well behaved task can bootstrap any
logic by using one of these two runners.
The lifecycle of a task is considered from before the `*Runner#run` methods are executed
to once they are all complete. Spring Boot lets an application use multiple
`*Runner` implementations, as does Spring Cloud Task.
NOTE: Any processing bootstrapped from mechanisms other than a `CommandLineRunner` or
`ApplicationRunner` (by using `InitializingBean#afterPropertiesSet` for example) is not
recorded by Spring Cloud Task.
[[getting-started-running-the-example]]
=== Running the Example
At this point, our application should work. Since this application is Spring Boot-based,
we can run it from the command line by using `$ mvn spring-boot:run` from the root
of our application, as shown (with its output) in the following example:
[source]
----
$ mvn clean spring-boot:run
....... . . .
....... . . . (Maven log output here)
....... . . .
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.0.3.RELEASE)
2018-07-23 17:44:34.426 INFO 1978 --- [ main] i.s.d.helloworld.HelloworldApplication : Starting HelloworldApplication on Glenns-MBP-2.attlocal.net with PID 1978 (/Users/glennrenfro/project/helloworld/target/classes started by glennrenfro in /Users/glennrenfro/project/helloworld)
2018-07-23 17:44:34.430 INFO 1978 --- [ main] i.s.d.helloworld.HelloworldApplication : No active profile set, falling back to default profiles: default
2018-07-23 17:44:34.472 INFO 1978 --- [ main] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@1d24f32d: startup date [Mon Jul 23 17:44:34 EDT 2018]; root of context hierarchy
2018-07-23 17:44:35.280 INFO 1978 --- [ main] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Starting...
2018-07-23 17:44:35.410 INFO 1978 --- [ main] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Start completed.
2018-07-23 17:44:35.419 DEBUG 1978 --- [ main] o.s.c.t.c.SimpleTaskConfiguration : Using org.springframework.cloud.task.configuration.DefaultTaskConfigurer TaskConfigurer
2018-07-23 17:44:35.420 DEBUG 1978 --- [ main] o.s.c.t.c.DefaultTaskConfigurer : No EntityManager was found, using DataSourceTransactionManager
2018-07-23 17:44:35.522 DEBUG 1978 --- [ main] o.s.c.t.r.s.TaskRepositoryInitializer : Initializing task schema for h2 database
2018-07-23 17:44:35.525 INFO 1978 --- [ main] o.s.jdbc.datasource.init.ScriptUtils : Executing SQL script from class path resource [org/springframework/cloud/task/schema-h2.sql]
2018-07-23 17:44:35.558 INFO 1978 --- [ main] o.s.jdbc.datasource.init.ScriptUtils : Executed SQL script from class path resource [org/springframework/cloud/task/schema-h2.sql] in 33 ms.
2018-07-23 17:44:35.728 INFO 1978 --- [ main] o.s.j.e.a.AnnotationMBeanExporter : Registering beans for JMX exposure on startup
2018-07-23 17:44:35.730 INFO 1978 --- [ main] o.s.j.e.a.AnnotationMBeanExporter : Bean with name 'dataSource' has been autodetected for JMX exposure
2018-07-23 17:44:35.733 INFO 1978 --- [ main] o.s.j.e.a.AnnotationMBeanExporter : Located MBean 'dataSource': registering with JMX server as MBean [com.zaxxer.hikari:name=dataSource,type=HikariDataSource]
2018-07-23 17:44:35.738 INFO 1978 --- [ main] o.s.c.support.DefaultLifecycleProcessor : Starting beans in phase 0
2018-07-23 17:44:35.762 DEBUG 1978 --- [ main] o.s.c.t.r.support.SimpleTaskRepository : Creating: TaskExecution{executionId=0, parentExecutionId=null, exitCode=null, taskName='application', startTime=Mon Jul 23 17:44:35 EDT 2018, endTime=null, exitMessage='null', externalExecutionId='null', errorMessage='null', arguments=[]}
2018-07-23 17:44:35.772 INFO 1978 --- [ main] i.s.d.helloworld.HelloworldApplication : Started HelloworldApplication in 1.625 seconds (JVM running for 4.764)
Hello, World!
2018-07-23 17:44:35.782 DEBUG 1978 --- [ main] o.s.c.t.r.support.SimpleTaskRepository : Updating: TaskExecution with executionId=1 with the following {exitCode=0, endTime=Mon Jul 23 17:44:35 EDT 2018, exitMessage='null', errorMessage='null'}
----
The preceding output has three lines that of interest to us here:
* `SimpleTaskRepository` logged the creation of the entry in the `TaskRepository`.
* The execution of our `CommandLineRunner`, demonstrated by the "`Hello, World!`" output.
* `SimpleTaskRepository` logs the completion of the task in the `TaskRepository`.
NOTE: A simple task application can be found in the samples module of the Spring Cloud
Task Project
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/timestamp[here].

BIN
docs/src/main/asciidoc/images/task_schema.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

1
docs/src/main/asciidoc/index.htmladoc Normal file
View File

@@ -0,0 +1 @@
include::_index.adoc[]

1
docs/src/main/asciidoc/index.htmlsingleadoc Normal file
View File

@@ -0,0 +1 @@
include::_index_single.adoc[]

46
docs/src/main/asciidoc/preface.adoc Normal file
View File

@@ -0,0 +1,46 @@
[[preface]]
= Preface
[[task-documentation-about]]
This section provides a brief overview of the Spring Cloud Task reference documentation.
Think of it as a map for the rest of the document. You can read this reference guide in a
linear fashion or you can skip sections if something does not interest you.
== About the documentation
The Spring Cloud Task reference guide is available in {spring-cloud-task-docs}[html]
and {spring-cloud-task-docs}/index.pdf[pdf],
{spring-cloud-task-docs}/index.epub[epub] . The
latest copy is available at {spring-cloud-task-docs-current}.
Copies of this document may be made for your own use and for distribution to others,
provided that you do not charge any fee for such copies and further provided that each
copy contains this Copyright Notice, whether distributed in print or electronically.
[[task-documentation-getting-help]]
== Getting help
Having trouble with Spring Cloud Task? We would like to help!
* Ask a question. We monitor https://stackoverflow.com[stackoverflow.com] for questions
tagged with https://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
a problem with the docs or if you just want to improve them, please {github-code}[get
involved].
[[task-documentation-first-steps]]
== First Steps
If you are just getting started with Spring Cloud Task or with 'Spring' in general, we
suggesting reading the <<getting-started.adoc#getting-started>> chapter.
To get started from scratch, read the following sections:
* <<getting-started.adoc#getting-started-introducing-spring-cloud-task, Introducing Spring Cloud Task>>
* <<getting-started.adoc#getting-started-system-requirements, System Requirements>> +
To follow the tutorial, read
<<getting-started.adoc#getting-started-developing-first-task, Developing Your First Spring Cloud Task Application>> +
To run your example, read
<<getting-started.adoc#getting-started-running-the-example, Running the Example>>

2
docs/src/main/asciidoc/sagan-index.adoc Normal file
View File

@@ -0,0 +1,2 @@
Spring Cloud Task allows a user to develop and run short lived microservices using Spring Cloud and run them locally, in the cloud, even on Spring Cloud Data Flow. Just add `@EnableTask` and run your app as a Spring Boot app (single application context).
If you are new to Spring Cloud Task, take a look at our https://docs.spring.io/spring-cloud-task/docs/2.0.0.RELEASE/reference/htmlsingle/#getting-started[Getting Started] docs.

1
docs/src/main/asciidoc/spring-cloud-task.adoc Symbolic link
View File

@@ -0,0 +1 @@
index.htmladoc

1
docs/src/main/asciidoc/spring-cloud-task.epubadoc Normal file
View File

@@ -0,0 +1 @@
include::_index_pdf.adoc[]

1
docs/src/main/asciidoc/spring-cloud-task.htmlsingleadoc Symbolic link
View File

@@ -0,0 +1 @@
index.htmlsingleadoc

1
docs/src/main/asciidoc/spring-cloud-task.pdfadoc Normal file
View File

@@ -0,0 +1 @@
include::_index_pdf.adoc[]

213
docs/src/main/asciidoc/stream.adoc Normal file
View File

@@ -0,0 +1,213 @@
[[stream-integration]]
= Spring Cloud Stream Integration
[[partintro]]
--
A task by itself can be useful, but integration of a task into a larger ecosystem lets it
be useful for more complex processing and orchestration. This section
covers the integration options for Spring Cloud Task with Spring Cloud Stream.
--
[[stream-integration-launching-sink]]
== Launching a Task from a Spring Cloud Stream
You can launch tasks from a stream. To do so, create a sink that listens for a message
that contains a `TaskLaunchRequest` as its payload. The `TaskLaunchRequest` contains:
* `uri`: To the task artifact that is to be executed.
* `applicationName`: The name that is associated with the task. If no
applicationName is set, the `TaskLaunchRequest` generates a task name
comprised of the following: `Task-<UUID>`.
* `commandLineArguments`: A list containing the command line arguments for the task.
* `environmentProperties`: A map containing the environment variables to be used by the
task.
* `deploymentProperties`: A map containing the properties that are used by the deployer to
deploy the task.
NOTE: If the payload is of a different type, the sink throws an exception.
For example, a stream can be created that has a processor that takes in data from an
HTTP source and creates a `GenericMessage` that contains the `TaskLaunchRequest` and sends
the message to its output channel. The task sink would then receive the message from its
input channnel and then launch the task.
To create a taskSink, you need only create a Spring Boot application that includes the
`EnableTaskLauncher` annotation, as shown in the following example:
[source,java]
----
@SpringBootApplication
@EnableTaskLauncher
public class TaskSinkApplication {
public static void main(String[] args) {
SpringApplication.run(TaskSinkApplication.class, args);
}
}
----
The https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples[samples
module] of the Spring Cloud Task project contains a sample Sink and Processor. To install
these samples into your local maven repository, run a maven build from the
`spring-cloud-task-samples` directory with the `skipInstall` property set to `false`, as
shown in the following example:
`mvn clean install`
NOTE: The `maven.remoteRepositories.springRepo.url` property must be set to the location
of the remote repository in which the über-jar is located. If not set, there is no remote
repository, so it relies upon the local repository only.
[[stream-integration-launching-sink-dataflow]]
=== Spring Cloud Data Flow
To create a stream in Spring Cloud Data Flow, you must first register the Task Sink
Application we created. In the following example, we are registering the Processor and
Sink sample applications by using the Spring Cloud Data Flow shell:
[source,bash]
----
app register --name taskSink --type sink --uri maven://io.spring.cloud:tasksink:<version>
app register --name taskProcessor --type processor --uri maven:io.spring.cloud:taskprocessor:<version>
----
The following example shows how to create a stream from the Spring Cloud Data Flow shell:
[source,bash]
stream create foo --definition "http --server.port=9000|taskProcessor|taskSink" --deploy
[[stream-integration-events]]
== Spring Cloud Task Events
Spring Cloud Task provides the ability to emit events through a Spring Cloud Stream
channel when the task is run through a Spring Cloud Stream channel. A task listener is
used to publish the `TaskExecution` on a message channel named `task-events`. This feature
is autowired into any task that has `spring-cloud-stream`, `spring-cloud-stream-<binder>`,
and a defined task on its classpath.
NOTE: To disable the event emitting listener, set the `spring.cloud.task.events.enabled`
property to `false`.
With the appropriate classpath defined, the following task emits the `TaskExecution` as an
event on the `task-events` channel (at both the start and the end of the task):
[source, java]
----
@SpringBootApplication
public class TaskEventsApplication {
public static void main(String[] args) {
SpringApplication.run(TaskEventsApplication.class, args);
}
@Configuration
public static class TaskConfiguration {
@Bean
public CommandLineRunner commandLineRunner() {
return new CommandLineRunner() {
@Override
public void run(String... args) throws Exception {
System.out.println("The CommandLineRunner was executed");
}
};
}
}
}
----
NOTE: A binder implementation is also required to be on the classpath.
NOTE: A sample task event application can be found in the samples module
of the Spring Cloud Task Project,
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/task-events[here].
[[stream-integration-disable-task-events]]
=== Disabling Specific Task Events
To disable task events, you can set the `spring.cloud.task.events.enabled` property to
`false`.
[[stream-integration-batch-events]]
== Spring Batch Events
When executing a Spring Batch job through 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 through Spring
Cloud Task:
* `JobExecutionListener` listens for `job-execution-events`
* `StepExecutionListener` listens for `step-execution-events`
* `ChunkListener` listens for `chunk-events`
* `ItemReadListener` listens for `item-read-events`
* `ItemProcessListener` listens for `item-process-events`
* `ItemWriteListener` listens for `item-write-events`
* `SkipListener` listens for `skip-events`
These listeners are autoconfigured into any `AbstractJob` when the appropriate
beans (a `Job` and a `TaskLifecycleListener`) exist in the context. 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 a `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 would
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.
NOTE: A sample batch event application can be found in the samples module
of the Spring Cloud Task Project,
https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/batch-events[here].
=== Sending Batch Events to Different Channels
One of the options that Spring Cloud Task offers for batch events is the ability to alter
the channel to which a specific listener can emit its messages. To do so, use the
following configuration:
`spring.cloud.stream.bindings.<the channel>.destination=<new destination>`. For example,
if `StepExecutionListener` needs to emit its messages to another channel called
`my-step-execution-events` instead of the default `step-execution-events`, you can add the
following configuration:
`spring.cloud.stream.bindings.step-execution-events.destination=my-step-execution-events`
=== Disabling Batch Events
To disable the listener functionality for all batch events, use the following
configuration:
`spring.cloud.task.batch.events.enabled=false`
To disable a specific batch event, use the following configuration:
`spring.cloud.task.batch.events.<batch event listener>.enabled=false`:
The following listing shows individual listeners that you can disable:
[source,bash]
----
spring.cloud.task.batch.events.job-execution.enabled=false
spring.cloud.task.batch.events.step-execution.enabled=false
spring.cloud.task.batch.events.chunk.enabled=false
spring.cloud.task.batch.events.item-read.enabled=false
spring.cloud.task.batch.events.item-process.enabled=false
spring.cloud.task.batch.events.item-write.enabled=false
spring.cloud.task.batch.events.skip.enabled=false
----
=== Emit Order for Batch Events
By default, batch events have `Ordered.LOWEST_PRECEDENCE`. To change this value (for
example, to 5 ), use the following configuration:
[source,bash]
----
spring.cloud.task.batch.events.job-execution-order=5
spring.cloud.task.batch.events.step-execution-order=5
spring.cloud.task.batch.events.chunk-order=5
spring.cloud.task.batch.events.item-read-order=5
spring.cloud.task.batch.events.item-process-order=5
spring.cloud.task.batch.events.item-write-order=5
spring.cloud.task.batch.events.skip-order=5
----

695
docs/src/main/javadoc/spring-javadoc.css Normal file
View File

@@ -0,0 +1,695 @@
/* Javadoc style sheet */
/*
Overall document style
*/
@import url('resources/fonts/dejavu.css');
body {
background-color: #ffffff;
color: #353833;
font-family: 'DejaVu Sans', Arial, Helvetica, sans-serif;
font-size: 14px;
margin: 0;
}
a:link, a:visited {
text-decoration: none;
color: #4A6782;
}
a:hover, a:focus {
text-decoration: none;
color: #bb7a2a;
}
a:active {
text-decoration: none;
color: #4A6782;
}
a[name] {
color: #353833;
}
a[name]:hover {
text-decoration: none;
color: #353833;
}
pre {
font-family: 'DejaVu Sans Mono', monospace;
font-size: 14px;
}
h1 {
font-size: 20px;
}
h2 {
font-size: 18px;
}
h3 {
font-size: 16px;
font-style: italic;
}
h4 {
font-size: 13px;
}
h5 {
font-size: 12px;
}
h6 {
font-size: 11px;
}
ul {
list-style-type: disc;
}
code, tt {
font-family: 'DejaVu Sans Mono', monospace;
font-size: 14px;
padding-top: 4px;
margin-top: 8px;
line-height: 1.4em;
}
dt code {
font-family: 'DejaVu Sans Mono', monospace;
font-size: 14px;
padding-top: 4px;
}
table tr td dt code {
font-family: 'DejaVu Sans Mono', monospace;
font-size: 14px;
vertical-align: top;
padding-top: 4px;
}
sup {
font-size: 8px;
}
/*
Document title and Copyright styles
*/
.clear {
clear: both;
height: 0px;
overflow: hidden;
}
.aboutLanguage {
float: right;
padding: 0px 21px;
font-size: 11px;
z-index: 200;
margin-top: -9px;
}
.legalCopy {
margin-left: .5em;
}
.bar a, .bar a:link, .bar a:visited, .bar a:active {
color: #FFFFFF;
text-decoration: none;
}
.bar a:hover, .bar a:focus {
color: #bb7a2a;
}
.tab {
background-color: #0066FF;
color: #ffffff;
padding: 8px;
width: 5em;
font-weight: bold;
}
/*
Navigation bar styles
*/
.bar {
background-color: #4D7A97;
color: #FFFFFF;
padding: .8em .5em .4em .8em;
height: auto; /*height:1.8em;*/
font-size: 11px;
margin: 0;
}
.topNav {
background-color: #4D7A97;
color: #FFFFFF;
float: left;
padding: 0;
width: 100%;
clear: right;
height: 2.8em;
padding-top: 10px;
overflow: hidden;
font-size: 12px;
}
.bottomNav {
margin-top: 10px;
background-color: #4D7A97;
color: #FFFFFF;
float: left;
padding: 0;
width: 100%;
clear: right;
height: 2.8em;
padding-top: 10px;
overflow: hidden;
font-size: 12px;
}
.subNav {
background-color: #dee3e9;
float: left;
width: 100%;
overflow: hidden;
font-size: 12px;
}
.subNav div {
clear: left;
float: left;
padding: 0 0 5px 6px;
text-transform: uppercase;
}
ul.navList, ul.subNavList {
float: left;
margin: 0 25px 0 0;
padding: 0;
}
ul.navList li {
list-style: none;
float: left;
padding: 5px 6px;
text-transform: uppercase;
}
ul.subNavList li {
list-style: none;
float: left;
}
.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {
color: #FFFFFF;
text-decoration: none;
text-transform: uppercase;
}
.topNav a:hover, .bottomNav a:hover {
text-decoration: none;
color: #bb7a2a;
text-transform: uppercase;
}
.navBarCell1Rev {
background-color: #F8981D;
color: #253441;
margin: auto 5px;
}
.skipNav {
position: absolute;
top: auto;
left: -9999px;
overflow: hidden;
}
/*
Page header and footer styles
*/
.header, .footer {
clear: both;
margin: 0 20px;
padding: 5px 0 0 0;
}
.indexHeader {
margin: 10px;
position: relative;
}
.indexHeader span {
margin-right: 15px;
}
.indexHeader h1 {
font-size: 13px;
}
.title {
color: #2c4557;
margin: 10px 0;
}
.subTitle {
margin: 5px 0 0 0;
}
.header ul {
margin: 0 0 15px 0;
padding: 0;
}
.footer ul {
margin: 20px 0 5px 0;
}
.header ul li, .footer ul li {
list-style: none;
font-size: 13px;
}
/*
Heading styles
*/
div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {
background-color: #dee3e9;
border: 1px solid #d0d9e0;
margin: 0 0 6px -8px;
padding: 7px 5px;
}
ul.blockList ul.blockList ul.blockList li.blockList h3 {
background-color: #dee3e9;
border: 1px solid #d0d9e0;
margin: 0 0 6px -8px;
padding: 7px 5px;
}
ul.blockList ul.blockList li.blockList h3 {
padding: 0;
margin: 15px 0;
}
ul.blockList li.blockList h2 {
padding: 0px 0 20px 0;
}
/*
Page layout container styles
*/
.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {
clear: both;
padding: 10px 20px;
position: relative;
}
.indexContainer {
margin: 10px;
position: relative;
font-size: 12px;
}
.indexContainer h2 {
font-size: 13px;
padding: 0 0 3px 0;
}
.indexContainer ul {
margin: 0;
padding: 0;
}
.indexContainer ul li {
list-style: none;
padding-top: 2px;
}
.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {
font-size: 12px;
font-weight: bold;
margin: 10px 0 0 0;
color: #4E4E4E;
}
.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {
margin: 5px 0 10px 0px;
font-size: 14px;
font-family: 'DejaVu Sans Mono', monospace;
}
.serializedFormContainer dl.nameValue dt {
margin-left: 1px;
font-size: 1.1em;
display: inline;
font-weight: bold;
}
.serializedFormContainer dl.nameValue dd {
margin: 0 0 0 1px;
font-size: 1.1em;
display: inline;
}
/*
List styles
*/
ul.horizontal li {
display: inline;
font-size: 0.9em;
}
ul.inheritance {
margin: 0;
padding: 0;
}
ul.inheritance li {
display: inline;
list-style: none;
}
ul.inheritance li ul.inheritance {
margin-left: 15px;
padding-left: 15px;
padding-top: 1px;
}
ul.blockList, ul.blockListLast {
margin: 10px 0 10px 0;
padding: 0;
}
ul.blockList li.blockList, ul.blockListLast li.blockList {
list-style: none;
margin-bottom: 15px;
line-height: 1.4;
}
ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {
padding: 0px 20px 5px 10px;
border: 1px solid #ededed;
background-color: #f8f8f8;
}
ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {
padding: 0 0 5px 8px;
background-color: #ffffff;
border: none;
}
ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {
margin-left: 0;
padding-left: 0;
padding-bottom: 15px;
border: none;
}
ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {
list-style: none;
border-bottom: none;
padding-bottom: 0;
}
table tr td dl, table tr td dl dt, table tr td dl dd {
margin-top: 0;
margin-bottom: 1px;
}
/*
Table styles
*/
.overviewSummary, .memberSummary, .typeSummary, .useSummary, .constantsSummary, .deprecatedSummary {
width: 100%;
border-left: 1px solid #EEE;
border-right: 1px solid #EEE;
border-bottom: 1px solid #EEE;
}
.overviewSummary, .memberSummary {
padding: 0px;
}
.overviewSummary caption, .memberSummary caption, .typeSummary caption,
.useSummary caption, .constantsSummary caption, .deprecatedSummary caption {
position: relative;
text-align: left;
background-repeat: no-repeat;
color: #253441;
font-weight: bold;
clear: none;
overflow: hidden;
padding: 0px;
padding-top: 10px;
padding-left: 1px;
margin: 0px;
white-space: pre;
}
.overviewSummary caption a:link, .memberSummary caption a:link, .typeSummary caption a:link,
.useSummary caption a:link, .constantsSummary caption a:link, .deprecatedSummary caption a:link,
.overviewSummary caption a:hover, .memberSummary caption a:hover, .typeSummary caption a:hover,
.useSummary caption a:hover, .constantsSummary caption a:hover, .deprecatedSummary caption a:hover,
.overviewSummary caption a:active, .memberSummary caption a:active, .typeSummary caption a:active,
.useSummary caption a:active, .constantsSummary caption a:active, .deprecatedSummary caption a:active,
.overviewSummary caption a:visited, .memberSummary caption a:visited, .typeSummary caption a:visited,
.useSummary caption a:visited, .constantsSummary caption a:visited, .deprecatedSummary caption a:visited {
color: #FFFFFF;
}
.overviewSummary caption span, .memberSummary caption span, .typeSummary caption span,
.useSummary caption span, .constantsSummary caption span, .deprecatedSummary caption span {
white-space: nowrap;
padding-top: 5px;
padding-left: 12px;
padding-right: 12px;
padding-bottom: 7px;
display: inline-block;
float: left;
background-color: #F8981D;
border: none;
height: 16px;
}
.memberSummary caption span.activeTableTab span {
white-space: nowrap;
padding-top: 5px;
padding-left: 12px;
padding-right: 12px;
margin-right: 3px;
display: inline-block;
float: left;
background-color: #F8981D;
height: 16px;
}
.memberSummary caption span.tableTab span {
white-space: nowrap;
padding-top: 5px;
padding-left: 12px;
padding-right: 12px;
margin-right: 3px;
display: inline-block;
float: left;
background-color: #4D7A97;
height: 16px;
}
.memberSummary caption span.tableTab, .memberSummary caption span.activeTableTab {
padding-top: 0px;
padding-left: 0px;
padding-right: 0px;
background-image: none;
float: none;
display: inline;
}
.overviewSummary .tabEnd, .memberSummary .tabEnd, .typeSummary .tabEnd,
.useSummary .tabEnd, .constantsSummary .tabEnd, .deprecatedSummary .tabEnd {
display: none;
width: 5px;
position: relative;
float: left;
background-color: #F8981D;
}
.memberSummary .activeTableTab .tabEnd {
display: none;
width: 5px;
margin-right: 3px;
position: relative;
float: left;
background-color: #F8981D;
}
.memberSummary .tableTab .tabEnd {
display: none;
width: 5px;
margin-right: 3px;
position: relative;
background-color: #4D7A97;
float: left;
}
.overviewSummary td, .memberSummary td, .typeSummary td,
.useSummary td, .constantsSummary td, .deprecatedSummary td {
text-align: left;
padding: 0px 0px 12px 10px;
width: 100%;
}
th.colOne, th.colFirst, th.colLast, .useSummary th, .constantsSummary th,
td.colOne, td.colFirst, td.colLast, .useSummary td, .constantsSummary td {
vertical-align: top;
padding-right: 0px;
padding-top: 8px;
padding-bottom: 3px;
}
th.colFirst, th.colLast, th.colOne, .constantsSummary th {
background: #dee3e9;
text-align: left;
padding: 8px 3px 3px 7px;
}
td.colFirst, th.colFirst {
white-space: nowrap;
font-size: 13px;
}
td.colLast, th.colLast {
font-size: 13px;
}
td.colOne, th.colOne {
font-size: 13px;
}
.overviewSummary td.colFirst, .overviewSummary th.colFirst,
.overviewSummary td.colOne, .overviewSummary th.colOne,
.memberSummary td.colFirst, .memberSummary th.colFirst,
.memberSummary td.colOne, .memberSummary th.colOne,
.typeSummary td.colFirst {
width: 25%;
vertical-align: top;
}
td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {
font-weight: bold;
}
.tableSubHeadingColor {
background-color: #EEEEFF;
}
.altColor {
background-color: #FFFFFF;
}
.rowColor {
background-color: #EEEEEF;
}
/*
Content styles
*/
.description pre {
margin-top: 0;
}
.deprecatedContent {
margin: 0;
padding: 10px 0;
}
.docSummary {
padding: 0;
}
ul.blockList ul.blockList ul.blockList li.blockList h3 {
font-style: normal;
}
div.block {
font-size: 14px;
font-family: 'DejaVu Serif', Georgia, "Times New Roman", Times, serif;
}
td.colLast div {
padding-top: 0px;
}
td.colLast a {
padding-bottom: 3px;
}
/*
Formatting effect styles
*/
.sourceLineNo {
color: green;
padding: 0 30px 0 0;
}
h1.hidden {
visibility: hidden;
overflow: hidden;
font-size: 10px;
}
.block {
display: block;
margin: 3px 10px 2px 0px;
color: #474747;
}
.deprecatedLabel, .descfrmTypeLabel, .memberNameLabel, .memberNameLink,
.overrideSpecifyLabel, .packageHierarchyLabel, .paramLabel, .returnLabel,
.seeLabel, .simpleTagLabel, .throwsLabel, .typeNameLabel, .typeNameLink {
font-weight: bold;
}
.deprecationComment, .emphasizedPhrase, .interfaceName {
font-style: italic;
}
div.block div.block span.deprecationComment, div.block div.block span.emphasizedPhrase,
div.block div.block span.interfaceName {
font-style: normal;
}
div.contentContainer ul.blockList li.blockList h2 {
padding-bottom: 0px;
}
/*
Spring
*/
pre.code {
background-color: #F8F8F8;
border: 1px solid #CCCCCC;
border-radius: 3px 3px 3px 3px;
overflow: auto;
padding: 10px;
margin: 4px 20px 2px 0px;
}
pre.code code, pre.code code * {
font-size: 1em;
}
pre.code code, pre.code code * {
padding: 0 !important;
margin: 0 !important;
}