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’ll want to utilize a supported database. Below is a list of the ones currently supported:

We need to start by creating a Maven pom.xml file. The pom.xml is the recipe that will be used to build your project. Open your favorite text editor and add the following:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<groupId>com.example</groupId>
	<artifactId>myproject</artifactId>
	<packaging>jar</packaging>
	<version>0.0.1-SNAPSHOT</version>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.2.RELEASE</version>
	</parent>

	<properties>
		<start-class>com.example.SampleTask</start-class>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

This should give you a working build. You can test it out by running mvn package (you can ignore the "jar will be empty - no content was marked for inclusion!" warning for now).

	Note
	At this point you could import the project into an IDE (most modern Java IDE’s include built-in support for Maven). For simplicity we will continue to use a plain text editor for this example.

A Spring Cloud Task is made up of a Spring Boot application that is expected to end. In our POM above, we created the shell of a Spring Boot application from a dependency perspective by setting our parent to use the spring-boot-starter-parent.

Spring Boot provides a number of additional "Starter POMs". Some of which are appropriate for use within tasks (spring-boot-starter-batch, spring-boot-starter-jdbc, etc) and some may not be ('spring-boot-starter-web` is probably not going to be used in a task). The indicator of if a starter makes sense or not comes down to if the resulting application will end (batch based applications typically end, the spring-boot-starter-web dependency bootstraps a servlet container which probably wont').

For this example, we’ll only need to add a single additional dependency, the one for Spring Cloud Task itself:

		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-task</artifactId>
			<version>1.2.3.RELEASE</version>
		</dependency>

To finish our application, we need to create a single Java file. Maven will compile the sources from src/main/java by default so you need to create that folder structure. Then add a file named src/main/java/com/example/SampleTask.java:

package com.example;

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.task.configuration.EnableTask;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
@EnableTask
public class SampleTask {

	@Bean
	public CommandLineRunner commandLineRunner() {
		return new HelloWorldCommandLineRunner();
	}

	public static void main(String[] args) {
		SpringApplication.run(SampleTask.class, args);
	}

	public static class HelloWorldCommandLineRunner implements CommandLineRunner {

		@Override
		public void run(String... strings) throws Exception {
			System.out.println("Hello World!");
		}
	}
}

While it may not look like much, quite a bit is going on. To read more about the Spring Boot specifics, take a look at their reference documentation here: http://docs.spring.io/spring-boot/docs/current/reference/html/

We’ll also need to create an application.properties in src/main/resources. We’ll configure two properties in it: the application name (which is translated to the task name) and we’ll set the logging for spring cloud task to DEBUG so that we can see what’s going on:

logging.level.org.springframework.cloud.task=DEBUG
spring.application.name=helloWorld

6.3.3 The CommandLineRunner

In Spring, there are many ways to bootstrap an application’s logic. Spring Boot provides a convenient method of doing so in an organized manner via their *Runner interfaces (CommandLineRunner or ApplicationRunner). A well behaved task will bootstrap any logic via 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 allows an application to use multiple *Runner implementation and Spring Cloud Task doesn’t attempt to impede on this convention.

	Note
	Any processing bootstrapped from mechanisms other than a CommandLineRunner or ApplicationRunner (using InitializingBean#afterPropertiesSet for example) will not be recorded by Spring Cloud Task.

At this point, your application should work. Since this application is Spring Boot based, we can run it from the command line via the command $ mvn spring-boot:run from the root of our applicaiton:

$ mvn clean spring-boot:run
....... . . .
....... . . . (Maven log output here)
....... . . .


  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.3.3.RELEASE)

2016-01-25 11:08:10.183  INFO 12943 --- [           main] com.example.SampleTask                   : Starting SampleTask on Michaels-MacBook-Pro-2.local with PID 12943 (/Users/mminella/Documents/IntelliJWorkspace/spring-cloud-task-example/target/classes started by mminella in /Users/mminella/Documents/IntelliJWorkspace/spring-cloud-task-example)
2016-01-25 11:08:10.185  INFO 12943 --- [           main] com.example.SampleTask                   : No active profile set, falling back to default profiles: default
2016-01-25 11:08:10.226  INFO 12943 --- [           main] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@2a2c3676: startup date [Mon Jan 25 11:08:10 CST 2016]; root of context hierarchy
2016-01-25 11:08:11.051  INFO 12943 --- [           main] o.s.j.e.a.AnnotationMBeanExporter        : Registering beans for JMX exposure on startup
2016-01-25 11:08:11.065  INFO 12943 --- [           main] o.s.c.t.r.support.SimpleTaskRepository   : Creating: TaskExecution{executionId=0, externalExecutionID='null', exitCode=0, taskName='application', startTime=Mon Jan 25 11:08:11 CST 2016, endTime=null, statusCode='null', exitMessage='null', arguments=[]}
Hello World!
2016-01-25 11:08:11.071  INFO 12943 --- [           main] com.example.SampleTask                   : Started SampleTask in 1.095 seconds (JVM running for 3.826)
2016-01-25 11:08:11.220  INFO 12943 --- [       Thread-1] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@2a2c3676: startup date [Mon Jan 25 11:08:10 CST 2016]; root of context hierarchy
2016-01-25 11:08:11.222  INFO 12943 --- [       Thread-1] o.s.c.t.r.support.SimpleTaskRepository   : Updating: TaskExecution{executionId=0, externalExecutionID='null', exitCode=0, taskName='application', startTime=Mon Jan 25 11:08:11 CST 2016, endTime=Mon Jan 25 11:08:11 CST 2016, statusCode='null', exitMessage='null', arguments=[]}
2016-01-25 11:08:11.222  INFO 12943 --- [       Thread-1] o.s.j.e.a.AnnotationMBeanExporter        : Unregistering JMX-exposed beans on shutdown

If you notice, there are three lines of interest in the above output:

	Note
	A simple task application can be found in the samples module of the Spring Cloud Task Project here.

The information stored in the TaskRepository is modeled in the TaskExecution class and consists of the following information:

When a task completes, it will want to return an exit code to the OS. If we take a look at our original example, we can see that we are not controlling that aspect of our application. So if an exception is thrown, the JVM will return a code that may or may not be of any use to you in the debugging of that.

As such, Spring Boot provides an interface, ExitCodeExceptionMapper that allows you to map uncaught exceptions to exit codes. This allows you to be able to indicate at that level what went wrong. Also, by mapping exit codes in this manner, Spring Cloud Task will record the exit code returned.

If the task is terminated with a SIG-INT or a SIG-TERM, the exit code will be zero unless otherwise specified within the code.

	Note
	While the task is running the exit code will be stored as a null in the repository. Once complete the appropriate exit code will be stored based on the guidelines enumerated above.

Spring Cloud Task utilizes 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’ll want to configure your own DataSource.

If your application utilizes only a single DataSource and that will serve as both your business schema as well as the task repository, all you need to do is provide any DataSource (via Spring Boot’s configuration conventions is the easiest way). This will be automatically used by Spring Cloud Task for the repository.

If your application utilizes more than one DataSource, you’ll need to configure the task repository with the appropriate DataSource. This customization can be done via an implementation of the TaskConfigurer.

One modifiable property of the 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 names needs to be prepended to the table names, or if more than one set of task tables is needed within the same schema, then the table prefix will need to be changed. This is done by setting the spring.cloud.task.tablePrefix to the prefix that is required.

 spring.cloud.task.tablePrefix=<yourPrefix>

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.enable property to false. It is currently defaulted to true.

 spring.cloud.task.initialize.enable=<true or false>

In some cases a user wants to allow for the time difference between when a task is requested and when the infrastructure actually launches it. Spring Cloud Task allows a user to create a TaskExecution at the time 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.

The TaskExecution can be created by calling the createTaskExecution method on an implementation of the TaskRepository that references the datastore storing the TaskExecutions.

In order to configure your Task to use a generated TaskExecutionId add the following property:

 spring.cloud.task.executionid=<yourtaskId>

Spring Cloud Task allows a user to store an external task Id for each TaskExecution. An example of this would be a task id that is 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>

Spring Cloud Task allows a user to store an parent task Id for each TaskExecution. An example of this would be a task that executes another task or tasks and the user would like to store what task launched 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>

The TaskConfigurer is a strategy interface allowing for users to 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 if there is a DataSource available.

The TaskConfigurer allows the configuration of three main components:

Customizing any of the above is accomplished via a custom implementation of the TaskConfigurer interface. Typically, extending the DefaultTaskConfigurer (which is provided out of the box if a TaskConfigurer is not found) and overriding the required getter is sufficient, however, implementing your own from scratch may be required.

In most cases, the name of the task will be the application name as configured via Spring Boot. However, there are some cases, where you may want to map the run of a task to a different name. Spring Data Flow is an example of this (where you 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 via the TaskNameResolver interface.

By default, Spring Cloud Task provides the SimpleTaskNameResolver which will use the following options (in order of precedence):

Allows a user to register listeners for specific events that occur during the task lifecycle. This is done by creating a class that implements the TaskExecutionListener interface. The class that implements the TaskExecutionListener interface will be notified for the following events:

Spring Cloud Task also allows a user add TaskExecution Listeners to methods within a bean by using the following method annotations:

 public class MyBean {

	@BeforeTask
	public void methodA(TaskExecution taskExecution) {
	}

	@AfterTask
	public void methodB(TaskExecution taskExecution) {
	}

	@FailedTask
	public void methodC(TaskExecution taskExecution, Throwable throwable) {
	}
}

@AfterTask
public void afterMe(TaskExecution taskExecution) {
    taskExecution.setExitMessage("AFTER EXIT MESSAGE");
}

Allows a user to establish that only one task with a given task name can be run at a time. To do this the user establishes the task name and sets spring.cloud.task.singleInstanceEnabled=true for each task execution. While the first task execution is running, any other time user tries to run a task with the same task name and spring.cloud.task.singleInstanceEnabled=true the task will fail with the following error message Task with name "application" is already running. The default for spring.cloud.task.singleInstanceEnabled is false.

 spring.cloud.task.singleInstanceEnabled=<true or false>

In order for this feature to be used you must include the following Spring Integration dependencies to your application:

---
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-core</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-jdbc</artifactId>
</dependency>
---

To prevent the listener from being injected into any batch jobs within the current context, the autoconfiguration can be disabled via standard Spring Boot mechanisms.

To only have the listener injected into particular jobs within the context, the batchTaskExecutionListenerBeanPostProcessor may be overridden and a list of job bean ids can be provided:

public TaskBatchExecutionListenerBeanPostProcessor batchTaskExecutionListenerBeanPostProcessor() {
	TaskBatchExecutionListenerBeanPostProcessor postProcessor =
		new TaskBatchExecutionListenerBeanPostProcessor();

	postProcessor.setJobNames(Arrays.asList(new String[] {"job1", "job2"}));

	return postProcessor;
}

	Note
	A sample batch application can be found in the samples module of the Spring Cloud Task Project here.

<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-deployer-yarn</artifactId>
</dependency>

<dependencyManagement>
    <dependencies>
...
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>18.0</version>
        </dependency>
    </dependencies>
...
</dependencyManagement>

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-deployer-kubernetes</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-deployer-mesos</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-deployer-cloudfoundry</artifactId>
</dependency>
<dependency>
    <groupId>io.projectreactor</groupId>
    <artifactId>reactor-core</artifactId>
    <version>3.0.2.RELEASE</version>
</dependency>
<dependency>
    <groupId>io.projectreactor.ipc</groupId>
    <artifactId>reactor-netty</artifactId>
    <version>0.5.1.RELEASE</version>
</dependency>

An example set of deployment environment variables for a partitioned task that uses a mysql database service would look something like this:

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

To create a stream in Spring Cloud Data Flow first we would want to register the Task Sink Application we created. In the example below we are registering the Processor and Sink sample applications using the Spring Cloud Data Flow shell:

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>

Creating a stream from the Spring Cloud Data Flow shell would look like this:

stream create foo --definition "http --server.port=9000|taskProcessor|taskSink" --deploy

To task events, the spring.cloud.task.events.enabled property can be set to false.

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 this 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 my-step-execution-events instead of the default step-execution-events the following configuration can be added:

spring.cloud.stream.bindings.step-execution-events.destination=my-step-execution-events`

To disable the all batch event listener functionality, 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:

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

By default batch events have Ordered.LOWEST_PRECEDENCE , to change this value ( for example to 5 ) use the following configuration:

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