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.

Getting Started

1. System Requirements

The Spring Cloud Data Flow server deploys streams (long-lived applications) and tasks (short-lived applications) to Cloud
Foundry. The server is a lightweight Spring Boot application. It can run on Cloud Foundry or your laptop, but it is more
common to run the server in Cloud Foundry.

Spring Cloud Data Flow requires a few data services to perform streaming, task/batch processing, and analytics. You have
two options when you provision Spring Cloud Data Flow and related services on Cloud Foundry:

The simplest (and automated) method is to use the Spring Cloud Data Flow for PCF
tile. This is an opinionated tile for Pivotal Cloud Foundry. It automatically provisions the server and the required
data services, thus simplifying the overall getting-started experience. You can read more about the installation
here.

Alternatively, you can provision all the components manually. The following section goes into the specifics of how to
do so.

1.1. Provision a Redis Service Instance on Cloud Foundry

A Redis instance is required for analytics apps and is typically bound to such apps when you create an analytics
stream by using the per-app-binding feature.

You can use cf marketplace to discover which plans are available to you, depending on the details of your Cloud Foundry setup.
For example, you can use Pivotal Web Services, as the following example shows:

cf create-service rediscloud 30mb redis

1.2. Provision a Rabbit Service Instance on Cloud Foundry

RabbitMQ is used as a messaging middleware between streaming apps and is bound to each deployed streaming
app. Apache Kafka is the other option. We can use the SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES setting in Data
Flow configuration or use the SPRING_CLOUD_SKIPPER_SERVER_PLATFORM_CLOUDFOUNDRY_ACCOUNTS[pws]_DEPLOYMENT_SERVICES setting in
Skipper, which automatically binds RabbitMQ to the deployed streaming applications.

You can use cf marketplace to discover which plans are available to you, depending on the details of your Cloud Foundry setup.
For example, you can use Pivotal Web Services:

cf create-service cloudamqp lemur rabbit

1.3. Provision a MySQL Service Instance on Cloud Foundry

An RDBMS is used to persist Data Flow state, such as stream and task definitions, deployments, and executions.

You can use cf marketplace to discover which plans are available to you, depending on the details of your Cloud Foundry setup.
For example, you can use Pivotal Web Services:

cf create-service cleardb spark my_mysql

2. Cloud Foundry Installation

Starting with 1.3.x, the Data Flow Server can run in either skipper or classic (non-skipper) mode. You can specify the mode
when you start the Data Flow server by setting the spring.cloud.dataflow.features.skipper-enabled property.
By default, the classic mode is enabled.

Download the Data Flow server and shell applications, as the following example shows:

You need to fill in {org}, {space}, {email}, {password} and {middlewareServiceName} before running these commands. Once you have the desired config values in manifest.yml, you can run the cf push command to provision the skipper-server.

Only set 'Skip SSL Validation' to true if you run on a Cloud Foundry instance by using self-signed
certificates (for example, in development). Do not use self-signed certificates for production.

Configure and run the Data Flow Server

One of the most important configuration details is providing credentials to the Cloud Foundry instance so that the server can itself spawn applications.
You can use any Spring Boot-compatible configuration mechanism (passing program arguments, editing configuration files before building the application, using
Spring Cloud Config, using environment variables, and others), although some may prove more practicable than others, depending on how you typically deploy applications to Cloud Foundry.

2.1. General Configuration

You must use a unique name for your app. An application with the same name in the same organization causes your
deployment to fail.

The recommended minimum memory setting for the server is 2G. Also, to push apps to PCF and obtain
application property metadata, the server downloads applications to a Maven repository hosted on the local disk. While
you can specify up to 2G as a typical maximum value for disk space on a PCF installation, you can increase this to
10G. Read the maximum disk quota section for information on
how to configure this PCF property. Also, the Data Flow server itself implements a Last-Recently-Used algorithm to
free disk space when it falls below a low-water-mark value.

If you are pushing to a space with multiple users (for example, on PWS), the route you chose for your application name may already be taken. You can use the --random-route option to avoid this when you push the server application.

By default, the application registry in Spring Cloud Data Flow’s Cloud Foundry server is empty. It is intentionally designed to let you have the flexibility of choosing and registering applications as you find appropriate for the given use-case requirement. Depending on the message-binder you choose, you can register between RabbitMQ- or Apache Kafka-based Maven artifacts.

If you need to configure multiple Maven repositories, a proxy, or authorization for a private repository, see Maven Configuration.

2.2. Deploying by Using Environment Variables

The following configuration is for Pivotal Web Services. You need to fill in {org}, {space},
{email} and {password} before running these commands.

If you are going to use Skipper to deploy Streams, deploy Skipper first and then configure the URI location where the Skipper server runs and set the server to be in skipper mode. The following example shows how to do so:

The Spring Cloud Data Flow server does not have any default remote maven repository configured.
This is intentionally designed to provide the flexibility, so you can override and point to a remote repository of your choice.
The out-of-the-box applications that are supported by Spring Cloud Data Flow are available in Spring’s repository. If you want to use them, set it as the remote repository, as the following example shows:

If you are going to use Skipper to deploy Streams, deploy Skipper first and then configure the URI location where the Skipper server runs and set the feature toggle to use skipper, as the following example shows:

Since Skipper is a Spring Boot application, you can also pass the configuration properties as command line options instead of environment variables. For example, SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES becomes --spring.cloud.deployer.cloudfoundry.stream.services.

Now we are ready to start the server application, as follows:

java -jar spring-cloud-dataflow-server-cloudfoundry-1.7.1.RELEASE.jar

All other parameterization options that were available when running the server on Cloud Foundry are
still available. This is particularly true for configuring defaults for applications. To use them,
substitute cf set-env syntax with export.

4. Data Flow Shell

Launching the Data Flow shell requires that you specify the appropriate data flow server mode.
The following example shows how to start the Data Flow Shell for the Data Flow server running in classic mode:

$ java -jar spring-cloud-dataflow-shell-1.7.1.RELEASE.jar

5. Deploying Streams

By default, the application registry is empty. If you would like to register all out-of-the-box stream applications
built with the RabbitMQ binder in bulk, run the following command:

You have two options for deploying Streams: the “traditional” way that Data Flow has always used and a new way that delegates to the Skipper server. Deploying by using Skipper lets you update and rollback the streams, while the traditional way does not.

5.1. Creating Streams without Skipper

The following example shows how to create a simple stream with an HTTP source and a log sink:

Now you can see whether hello world is in the log files for the log application.

Skipper includes the concept of platforms,
so it is important to define the “accounts” based on the project preferences. In the preceding YAML file, the accounts map
to pws as the platform. You can modify this, and you can have any number of platform definitions.
The Spring Cloud Skipper reference guide has more details.

6. Deploying Streams by Using Skipper

This section proceeds with the assumption that Spring Cloud Data Flow, Spring Cloud Skipper, RDBMS, and your desired messaging
middleware are all running in PWS. The following listing shows the apps running in a sample org and space:

We start by deploying a stream with the time-source pointing to 1.2.0.RELEASE and log-sink pointing
to 1.1.0.RELEASE. The goal is to perform a rolling upgrade of the log-sink application to 1.2.0.RELEASE.

The greater-than and less-than signs around > log-1.1.0.RELEASE < indicate that this is the default version that is used when matching log in the DSL for a stream definition.
You can change the default version by using the app default command.

There are two versions of the log-sink applications. The ticker-314-log-v1 application instance is going down
(route already removed) and the newly spawned ticker-314-log-v2 application is bootstrapping. The version number is incremented and
the version-number (v2) is included in the new application name.

Once the new application is up and running, you can verify the logs, as the following example shows:

7. Deploying Tasks

Now you can create a simple timestamp task, as the following example shows:

dataflow:>task create mytask --definition "timestamp --format='yyyy'"

Now you can examine the tail of the logs (for example, cf logs mytask) and then launch the task in the UI or in the Data Flow Shell, as the following example shows:

dataflow:>task launch mytask

You will see the year (2018 at the time of this writing) printed in the logs. The execution status of the task is stored
in the database, and you can retrieve information about the task execution by using the
task execution list and task execution status --id <ID_OF_TASK> shell commands or though the Data Flow UI.

The current underlying PCF task capabilities are considered experimental for PCF version
versions less than 1.9. See Feature Togglers
for how to disable task support in Data Flow.

Applications

A selection of pre-built stream and task/batch starter apps for various data integration and processing scenarios to facilitate learning and experimentation. The table below includes the pre-built applications at a glance. For more details, review how to register supported applications.

Architecture

9. Introduction

Spring Cloud Data Flow simplifies the development and deployment of applications focused on data processing use cases.
The major concepts of the architecture are Applications, the Data Flow Server, and the target runtime.

Applications come in two flavors:

Long-lived Stream applications where an unbounded amount of data is consumed or produced through messaging middleware.

Short-lived Task applications that process a finite set of data and then terminate.

Depending on the runtime, applications can be packaged in two ways:

Spring Boot uber-jar that is hosted in a maven repository, file, or HTTP(S).

Docker image.

The runtime is the place where applications execute.
The target runtimes for applications are platforms that you may already be using for other application deployments.

The supported platforms are:

Cloud Foundry

Kubernetes

Local Server

The local server is supported in production for Task deployment as a replacement for the Spring Batch Admin project. The local server is not supported in production for Stream deployments.

There is a deployer Service Provider Interface (SPI) that lets you extend Data Flow to deploy onto other runtimes.
There are community implementations

Enable the Spring Cloud Data Flow Server to delegate the deployment and runtime status of applications to the Spring Cloud Skipper Server, which has the capability to deploy to multiple platforms.

Selecting the Spring Cloud Skipper option also enables the ability to update and rollback applications in a Stream at runtime.

The Data Flow server is also responsible for:

Interpreting and executing a stream DSL that describes the logical flow of data through multiple long-lived applications.

Launching a long-lived task application.

Interpreting and executing a composed task DSL that describes the logical flow of data through multiple short-lived applications.

Applying a deployment manifest that describes the mapping of applications onto the runtime - for example, to set the initial number of instances, memory requirements, and data partitioning.

Providing the runtime status of deployed applications.

As an example, the stream DSL to describe the flow of data from an HTTP source to an Apache Cassandra sink would be written using a Unix pipes and filter syntax " http | cassandra ". Each name in the DSL is mapped to an application that can that Maven or Docker repositories. You can also register an application to an http location. Many source, processor, and sink applications for common use cases (such as JDBC, HDFS, HTTP, and router) are provided by the Spring Cloud Data Flow team. The pipe symbol represents the communication between the two applications through messaging middleware. The two messaging middleware brokers that are supported are:

Apache Kafka

RabbitMQ

In the case of Kafka, when deploying the stream, the Data Flow server is responsible for creating the topics that correspond to each pipe symbol and configure each application to produce or consume from the topics so the desired flow of data is achieved. Similarly for RabbitMQ, exchanges and queues are created as needed to achieve the desired flow.

The interaction of the main components is shown in the following image:

Figure 1. The Spring Cloud Data High Level Architecure

In the preceding diagram, a DSL description of a stream is POSTed to the Data Flow Server. Based on the mapping of DSL application names to Maven and Docker artifacts, the http-source and cassandra-sink applications are deployed on the target runtime. Data that is posted to the HTTP application will then be stored in Cassandra. The Samples Repository shows this use case in full detail.

10. Microservice Architectural Style

The Data Flow Server deploys applications onto the target runtime that conform to the microservice architectural style. For example, a stream represents a high-level application that consists of multiple small microservice applications each running in their own process. Each microservice application can be scaled up or down independently of the other and each has its own versioning lifecycle. Using Data Flow with Skipper enables you to independently upgrade or rollback each application at runtime.

Both Streaming and Task-based microservice applications build upon Spring Boot as the foundational library.
This gives all microservice applications functionality such as health checks, security, configurable logging, monitoring, and management functionality, as well as executable JAR packaging.

It is important to emphasize that these microservice applications are 'just apps' that you can run by yourself by using java -jar and passing in appropriate configuration properties. We provide many common microservice applications for common operations so you need not start from scratch when addressing common use cases that build upon the rich ecosystem of Spring Projects, such as Spring Integration, Spring Data, and Spring Batch. Creating your own microservice application is similar to creating other Spring Boot applications. You can start by using the Spring Initializr web site to create the basic scaffolding of either a Stream or Task-based microservice.

In addition to passing the appropriate application properties to each applications, the Data Flow server is responsible for preparing the target platform’s infrastructure so that the applications can be deployed. For example, in Cloud Foundry, it would bind specified services to the applications and execute the cf push command for each application. For Kubernetes, it would create the replication controller, service, and load balancer.

The Data Flow Server helps simplify the deployment of multiple, relatated, applications onto a target runtime, setting up necessary input and output topics, partitions, and metrics functionality. However, one could also opt to deploy each of the microservice applications manually and not use Data Flow at all. This approach might be more appropriate to start out with for small scale deployments, gradually adopting the convenience and consistency of Data Flow as you develop more applications.
Manual deployment of Stream- and Task-based microservices is also a useful educational exercise that can help you better understand some of the automatic application configuration and platform targeting steps that the Data Flow Server provides.

10.1. Comparison to Other Platform Architectures

Spring Cloud Data Flow’s architectural style is different than other Stream and Batch processing platforms. For example in Apache Spark, Apache Flink, and Google Cloud Dataflow, applications run on a dedicated compute engine cluster. The nature of the compute engine gives these platforms a richer environment for performing complex calculations on the data as compared to Spring Cloud Data Flow, but it introduces the complexity of another execution environment that is often not needed when creating data-centric applications. That does not mean you cannot do real-time data computations when using Spring Cloud Data Flow. Refer to the section Analytics, which describes the integration of Redis to handle common counting-based use cases. Spring Cloud Stream also supports using Reactive APIs such as Project Reactor and RxJava which can be useful for creating functional style applications that contain time-sliding-window and moving-average functionality. Similarly, Spring Cloud Stream also supports the development of applications in that use the Kafka Streams API.

Apache Storm, Hortonworks DataFlow, and Spring Cloud Data Flow’s predecessor, Spring XD, use a dedicated application execution cluster, unique to each product, that determines where your code should run on the cluster and performs health checks to ensure that long-lived applications are restarted if they fail. Often, framework-specific interfaces are required in order to correctly “plug in” to the cluster’s execution framework.

As we discovered during the evolution of Spring XD, the rise of multiple container frameworks in 2015 made creating our own runtime a duplication of effort. There is no reason to build your own resource management mechanics when there are multiple runtime platforms that offer this functionality already. Taking these considerations into account is what made us shift to the current architecture, where we delegate the execution to popular runtimes, which you may already be using for other purposes. This is an advantage in that it reduces the cognitive distance for creating and managing data-centric applications as many of the same skills used for deploying other end-user/web applications are applicable.

11. Data Flow Server

11.1. Endpoints

The Data Flow Server uses an embedded servlet container and exposes REST endpoints for creating, deploying, undeploying, and destroying streams and tasks, querying runtime state, analytics, and the like. The Data Flow Server is implemented by using Spring’s MVC framework and the Spring HATEOAS library to create REST representations that follow the HATEOAS principle, as shown in the following image:

Figure 2. The Spring Cloud Data Flow Server

[NOTE] The Data Flow Server that deploys applications to the local machine is not intended to be used in production for streaming use cases but for the development and testing of stream based applications.
The local Data Flow is intended to be used in production for batch use cases as a replacement for the Spring Batch Admin project.
Both streaming and batch use cases are intended to be used in production when deploying to Cloud Foundry or Kuberenetes.

11.2. Security

The Data Flow Server executable jars support basic HTTP, LDAP(S), File-based, and OAuth 2.0 authentication to access its endpoints. Refer to the security section for more information.

12. Streams

12.1. Topologies

The Stream DSL describes linear sequences of data flowing through the system. For example, in the stream definition http | transformer | cassandra, each pipe symbol connects the application on the left to the one on the right. Named channels can be used for routing and to fan in/fan out data to multiple messaging destinations.

The concept of a tap can be used to ‘listen’ to the data that is flowing across any of the pipe symbols. "Taps" are just other streams that use an input any one of the "pipes" in a target stream and have an independent life cycle from the target stream.

12.2. Concurrency

For an application that consumes events, Spring Cloud Stream exposes a concurrency setting that controls the size of a thread pool used for dispatching incoming messages. See the Consumer properties documentation for more information.

12.3. Partitioning

A common pattern in stream processing is to partition the data as it moves from one application to the next. Partitioning is a critical concept in stateful processing, for either performance or consistency reasons, to ensure that all related data is processed together. For example, in a time-windowed average calculation example, it is important that all measurements from any given sensor are processed by the same application instance. Alternatively, you may want to cache some data related to the incoming events so that it can be enriched without making a remote procedure call to retrieve the related data.

Spring Cloud Data Flow supports partitioning by configuring Spring Cloud Stream’s output and input bindings. Spring Cloud Stream provides a common abstraction for implementing partitioned processing use cases in a uniform fashion across different types of middleware. Partitioning can thus be used whether the broker itself is naturally partitioned (for example, Kafka topics) or not (RabbitMQ). The following image shows how data could be partitioned into two buckets, such that each instance of the average processor application consumes a unique set of data.

Figure 3. Spring Cloud Stream Partitioning

To use a simple partitioning strategy in Spring Cloud Data Flow, you need only set the instance count for each application in the stream and a partitionKeyExpression producer property when deploying the stream. The partitionKeyExpression identifies what part of the message is used as the key to partition data in the underlying middleware. An ingest stream can be defined as http | averageprocessor | cassandra. (Note that the Cassandra sink is not shown in the diagram above.) Suppose the payload being sent to the HTTP source was in JSON format and had a field called sensorId. For example, consider the case of deploying the stream with the shell command stream deploy ingest --propertiesFile ingestStream.properties where the contents of the ingestStream.properties file are as follows:

The result is to deploy the stream such that all the input and output destinations are configured for data to flow through the applications but also ensure that a unique set of data is always delivered to each averageprocessor instance. In this case, the default algorithm is to evaluate payload.sensorId % partitionCount where the partitionCount is the application count in the case of RabbitMQ and the partition count of the topic in the case of Kafka.

Also note that you cannot currently scale partitioned streams. Read Scaling at Runtime for more information.

12.4. Message Delivery Guarantees

Streams are composed of applications that use the Spring Cloud Stream library as the basis for communicating with the underlying messaging middleware product. Spring Cloud Stream also provides an opinionated configuration of middleware from several vendors, in particular providing persistent publish-subscribe semantics.

The Binder abstraction in Spring Cloud Stream is what connects the application to the middleware. There are several configuration properties of the binder that are portable across all binder implementations and some that are specific to the middleware.

For consumer applications, there is a retry policy for exceptions generated during message handling. The retry policy is configured by using the common consumer propertiesmaxAttempts, backOffInitialInterval, backOffMaxInterval, and backOffMultiplier. The default values of these properties retry the callback method invocation 3 times and wait one second for the first retry. A backoff multiplier of 2 is used for the second and third attempts.

When the number of retry attempts has exceeded the maxAttempts value, the exception and the failed message become the payload of a message and are sent to the application’s error channel. By default, the default message handler for this error channel logs the message. You can change the default behavior in your application by creating your own message handler that subscribes to the error channel.

Spring Cloud Stream also supports a configuration option for both Kafka and RabbitMQ binder implementations that sends the failed message and stack trace to a dead letter queue. The dead letter queue is a destination and its nature depends on the messaging middleware (for example, in the case of Kafka, it is a dedicated topic). To enable this for RabbitMQ set the republishtoDlq and autoBindDlqconsumer properties and the autoBindDlqproducer property to true when deploying the stream. To always apply these producer and consumer properties when deploying streams, configure them as common application properties when starting the Data Flow server.

Additional messaging delivery guarantees are those provided by the underlying messaging middleware that is chosen for the application for both producing and consuming applications. Refer to the Kafka Consumer and Producer and Rabbit Consumer and Producer documentation for more details. You can find extensive declarative support for all the native QOS options.

13. Stream Programming Models

While Spring Boot provides the foundation for creating DevOps-friendly microservice applications, other libraries in the Spring ecosystem help create Stream-based microservice applications. The most important of these is Spring Cloud Stream.

The essence of the Spring Cloud Stream programming model is to provide an easy way to describe multiple inputs and outputs of an application that communicate over messaging middleware. These input and outputs map onto Kafka topics or Rabbit exchanges and queues as well as the KStream/KTable programming model. Common application configuration for a Source that generates data, a Processor that consumes and produces data, and a Sink that consumes data is provided as part of the library.

13.1. Imperative Programming Model

Spring Cloud Stream is most closely integrated with Spring Integration’s imperative "one event at a time" programming model. This means you write code that handles a single event callback, as shown in the following example,

In this case, the String payload of a message coming on the input channel is handed to the log method. The @EnableBinding annotation is used to tie the input channel to the external middleware.

13.2. Functional Programming Model

However, Spring Cloud Stream can support other programming styles, such as reactive APIs, where incoming and outgoing data is handled as continuous data flows and how each individual message should be handled is defined. With many reactive AOIs, you can also use operators that describe functional transformations from inbound to outbound data flows.
Here is an example:

14. Application Versioning

Application versioning within a Stream is now supported when using Data Flow together with Skipper. You can update application and deployment properties as well as the version of the application.
Rolling back to a previous application version is also supported.

15. Task Programming Model

The Spring Cloud Task programming model provides:

Persistence of the Task’s lifecycle events and exit code status.

Lifecycle hooks to execute code before or after a task execution.

The ability to emit task events to a stream (as a source) during the task lifecycle.

17. Runtime

17.1. Fault Tolerance

The target runtimes supported by Data Flow all have the ability to restart a long-lived application. Spring Cloud Data Flow sets up health probes are required by the runtime environment when deploying the application.
You also have the ability to customize the health probes.

The collective state of all applications that make up the stream is used to determine the state of the stream. If an application fails, the state of the stream changes from ‘deployed’ to ‘partial’.

17.2. Resource Management

Each target runtime lets you control the amount of memory, disk, and CPU allocated to each application. These are passed as properties in the deployment manifest by using key names that are unique to each runtime. Refer to each platform’s server documentation for more information.

17.3. Scaling at Runtime

When deploying a stream, you can set the instance count for each individual application that makes up the stream.
Once the stream is deployed, each target runtime lets you control the target number of instances for each individual application.
Using the APIs, UIs, or command line tools for each runtime, you can scale up or down the number of instances as required.

Currently, scaling at runtime is not supported with the Kafka binder, as well as with partitioned streams, for which the suggested workaround is redeploying the stream with an updated number of instances.
Both cases require a static consumer to be set up, based on information about the total instance count and current instance index.

Server Configuration

This section describes how to configure Spring Cloud Data Flow server’s features, such as security and which relational database to use.
It also describes how to configure Spring Cloud Data Flow shell’s features.

18. Feature Toggles

Data Flow server offers a specific set of features that you can enable or disable when launching. These features include all the lifecycle operations and REST endpoints (server, client implementations including Shell and the UI) for:

Streams

Tasks

Analytics

You can enable or disable these features by setting the following boolean properties when you launch the Data Flow server:

spring.cloud.dataflow.features.streams-enabled

spring.cloud.dataflow.features.tasks-enabled

spring.cloud.dataflow.features.analytics-enabled

By default, all features are enabled.
Note: Since the analytics feature is enabled by default, the Data Flow server is expected to have a valid Redis store available as its analytic repository (we provide a default implementation of analytics based on Redis). This also means that the Data Flow server’s health depends on the redis store availability as well. If you do not want to enable HTTP endpoints to read analytics data written to Redis, you can disable the analytics feature by using the spring.cloud.dataflow.features.analytics-enabled property to false.

The REST endpoint (/features) provides information on the enabled and disabled features.

19. Deployer Properties

You can also set other optional properties that alter the way Spring Cloud Data Flow deploys stream and task apps to Cloud Foundry:

You can configure the default memory and disk sizes for a deployed application. By default, they are 1024 MB memory
and 1024 MB disk. To change these to (for example) 512 and 2048 respectively, use the following commands:

You can customize the health check mechanism used by Cloud Foundry to assert whether apps are running by using the SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_HEALTH_CHECK environment variable. The current supported options
are http (the default), port, and none.

You can also set environment variables that specify the the HTTP-based health check endpoint and timeout: SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_HEALTH_CHECK_ENDPOINT and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_HEALTH_CHECK_TIMEOUT, respectively. These default to /health (the Spring Boot default location) and 120 seconds.

You can also specify deployment properties by using the DSL. For instance, if you want to set the allocated memory for the http application to 512m and also bind a mysql service to the jdbc application, you can run the following commands:

20. Application Names and Prefixes

To help avoid clashes with routes across spaces in Cloud Foundry, a naming strategy that provides a random prefix to a
deployed application is available and is enabled by default. You can override the default configurations
and set the respective properties by using cf set-env commands.

For instance, if you want to disable the randomization, you can override it by using the following command:

The preceding example binds the http app to the myhost.mydomain.com/my-path URL. Note that this
example shows all of the available customization options. In practice, you can use only one or two out of the three.

22. Docker Applications

Starting with version 1.2, it is possible to register and deploy Docker based apps as part of streams and tasks by using
Data Flow for Cloud Foundry.

If you use Spring Boot and RabbitMQ-based Docker images, you can provide a common deployment property
to facilitate binding the apps to the RabbitMQ service. Assuming your RabbitMQ service is named rabbit, you can provide the following:

For non-Java or non-Boot applications, your Docker app must parse the VCAP_SERVICES variable in order to bind to any available services.

Passing application properties

When using non-Boot applications, chances are that you want to pass the application properties by using traditional
environment variables, as opposed to using the special SPRING_APPLICATION_JSON variable. To do so, set the
following variables for streams and tasks, respectively:

23. Application-level Service Bindings

When deploying streams in Cloud Foundry, you can take advantage of application-specific service bindings, so not all
services are globally configured for all the apps orchestrated by Spring Cloud Data Flow.

For instance, if you want to provide a mysql service binding only for the jdbc application in the following stream
definition, you can pass the service binding as a deployment property:

where mysqlService is the name of the service specifically bound only to the jdbc application and the http
application does not get the binding by this method.

If you have more than one service to bind, they can be passed as comma-separated items
(for example: deployer.jdbc.cloudfoundry.services=mysqlService,someService).

24. User-provided Services

In addition to marketplace services, Cloud Foundry supports
User-provided Services (UPS). Throughout this reference manual,
regular services have been mentioned, but there is nothing precluding the use of User-provided Services as well, whether for use as the
messaging middleware (for example, if you want to use an external Apache Kafka installation) or for use by some
of the stream applications (for example, an Oracle Database).

Now we review an example of extracting and supplying the connection credentials from a UPS.

25. Database Connection Pool

The Data Flow server uses the Spring Cloud Connector library to create the DataSource with a default connection pool size of 4.
To change the connection pool size and maximum wait time, set the following two properties spring.cloud.skipper.server.cloudfoundry.maxPoolSize and spring.cloud.skipper.server.cloudfoundry.maxWaitTime. The wait time is specified in milliseconds.

26. Maximum Disk Quota

By default, every application in Cloud Foundry starts with 1G disk quota and this can be adjusted to a default maximum of
2G. The default maximum can also be overridden up to 10G by using Pivotal Cloud Foundry’s (PCF) Ops Manager GUI.

This configuration is relevant for Spring Cloud Data Flow because every stream and task deployment is composed of applications
(typically Spring Boot uber-jar’s), and those applications are resolved from a remote maven repository. After resolution,
the application artifacts are downloaded to the local Maven Repository for caching and reuse. With this happening in the background,
the default disk quota (1G) can fill up rapidly, especially when we experiment with streams that
are made up of unique applications. In order to overcome this disk limitation and depending
on your scaling requirements, you may want to change the default maximum from 2G to 10G. Let’s review the
steps to change the default maximum disk quota allocation.

27. Scale Application

Once the disk quota change has been successfully applied and assuming you have a running application,
you can scale the application with a new disk_limit through the CF CLI, as the following example shows:

28. Managing Disk Use

Even when configuring the Data Flow server to use 10G of space, there is the possibility of exhausting
the available space on the local disk.
If you deploy the Data Flow server by using the default port health check type, you must explicitly monitor the disk space on the server in order to avoid running out space.
If you deploy the server by using the http health check type (see the next example), the Data Flow server is restarted if there is low disk space.
This is due to Spring Boot’s Disk Space Health Indicator.
You can configure the settings of the Disk Space Health Indicator by using the properties that have the management.health.diskspace prefix.

For version 1.7, we are investigating the use of Volume Services for the Data Flow server to store .jar artifacts before pushing them to Cloud Foundry.

The following example shows how to deploy the http health check type to an endpoint called /management/health:

29. Application Resolution Alternatives

Though we highly recommend using Maven Repository for application resolution and registration
in Cloud Foundry, there might be situations where an alternative approach would make sense. The following alternative options
could help you resolve applications when running on Cloud Foundry.

With the help of Spring Boot, we can serve static content
in Cloud Foundry. A simple Spring Boot application can bundle all the required stream and task applications. By having it
run on Cloud Foundry, the static application can then serve the über-jar’s. From the shell, you can, for example, register the
application with the name http-source.jar by using --uri=http://<Route-To-StaticApp>/http-source.jar.

The über-jar’s can be hosted on any external server that’s reachable over HTTP. They can be resolved from raw GitHub URIs
as well. From the shell, you can, for example, register the app with the name http-source.jar by using --uri=http://<Raw_GitHub_URI>/http-source.jar.

Static Buildpack support in Cloud Foundry is another
option. A similar HTTP resolution works on this model, too.

Volume Services is another great option.
The required über-jars can be hosted in an external file system. With the help of volume-services, you can, for
example, register the application with the name http-source.jar by using --uri=file://<Path-To-FileSystem>/http-source.jar.

30. Database Connection Pool

The Data Flow server uses the Spring Cloud Connector library to create the DataSource with a default connection pool size of 4.
To change the connection pool size and maximum wait time, set the following two properties spring.cloud.dataflow.server.cloudfoundry.maxPoolSize and spring.cloud.dataflow.server.cloudfoundry.maxWaitTime.
The wait time is specified in milliseconds.

31. Security

By default, the Data Flow server is unsecured and runs on an unencrypted HTTP connection. You can secure your REST endpoints
(as well as the Data Flow Dashboard) by enabling HTTPS and requiring clients to authenticate.
For more details about securing the
REST endpoints and configuring to authenticate against an OAUTH backend (UAA and SSO running on Cloud Foundry),
see the security section from the core reference guide. You can configure the security details in dataflow-server.yml or pass them as environment variables through cf set-env commands.

31.1. Authentication and Cloud Foundry

Spring Cloud Data Flow can either integrate with Pivotal Single Sign-On Service
(for example, on PWS) or Cloud Foundry User Account and Authentication (UAA) Server.

31.1.1. Pivotal Single Sign-On Service

When deploying Spring Cloud Data Flow to Cloud Foundry, you can bind the
application to the Pivotal Single Sign-On Service. By doing so, Spring Cloud
Data Flow takes advantage of the
Spring Cloud Single Sign-On Connector,
which provides Cloud Foundry-specific auto-configuration support for OAuth 2.0.

To do so, bind the Pivotal Single Sign-On Service to your Data Flow Server application and
Single Sign-On (SSO) over OAuth2 will be enabled by default.

Authorization is similarly supported for non-Cloud Foundry security scenarios.
See the security section from the core Data Flow reference guide.

As the provisioning of roles can vary widely across environments, we by
default assign all Spring Cloud Data Flow roles to users.

31.1.2. Cloud Foundry UAA

The availability of Cloud Foundry User Account and Authentication (UAA) depends on the Cloud Foundry environment.
In order to provide UAA integration, you have to manually provide the necessary
OAuth2 configuration properties (for example, by setting the SPRING_APPLICATION_JSON
property).

The following JSON example shows how to create a security configuration:

By default, the spring.cloud.dataflow.security.cf-use-uaa property is set to true. This property activates a special
AuthoritiesExtractor called CloudFoundryDataflowAuthoritiesExtractor.

If you do not use CloudFoundry UAA, you should set spring.cloud.dataflow.security.cf-use-uaa to false.

Under the covers, this AuthoritiesExtractor calls out to the
Cloud Foundry
Apps API and ensure that users are in fact Space Developers.

If the authenticated user is verified as a Space Developer, all roles are assigned.
Otherwise, no roles whatsoever are assigned. In that case, you may see the following
Dashboard screen:

Figure 4. Accessing the Data Flow Dashboard without Roles

32. Configuration Reference

You must provide several pieces of configuration. These are Spring Boot @ConfigurationProperties, so you can set
them as environment variables or by any other means that Spring Boot supports. The following listing is in environment
variable format, as that is an easy way to get started configuring Boot applications in Cloud Foundry:

# Default values appear after the equal signs.
# Example values, typical for Pivotal Web Services, are included as comments.
# URL of the CF API (used when using cf login -a for example) - for example, https://api.run.pivotal.io
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_URL).
spring.cloud.deployer.cloudfoundry.url=
# The name of the organization that owns the space above - for example, youruser-org
# (To set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_ORG).
spring.cloud.deployer.cloudfoundry.org=
# The name of the space into which modules will be deployed - for example, development
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SPACE).
spring.cloud.deployer.cloudfoundry.space=
# The root domain to use when mapping routes - for example, cfapps.io
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_DOMAIN).
spring.cloud.deployer.cloudfoundry.domain=
# The user name and password of the user to use to create applications
# (to set the environment variables, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_USERNAME
# and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_PASSWORD).
spring.cloud.deployer.cloudfoundry.username=
spring.cloud.deployer.cloudfoundry.password=
# Whether to allow self-signed certificates during SSL validation (you should NOT do so in production)
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_SKIP_SSL_VALIDATION).
spring.cloud.deployer.cloudfoundry.skipSslValidation=false
# A comma-separated set of service instance names to bind to every deployed stream application.
# Among other things, this should include a service that is used
# for Spring Cloud Stream binding, such as Rabbit
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_SERVICES).
spring.cloud.deployer.cloudfoundry.stream.services=
# The health check type to use for stream apps. Accepts 'none' and 'port'.
spring.cloud.deployer.cloudfoundry.stream.health-check=
# A comma-separated set of service instance names to bind to every deployed task application.
# Among other things, this should include an RDBMS service that is used
# for Spring Cloud Task execution reporting, such as my_mysql
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_SERVICES).
spring.cloud.deployer.cloudfoundry.task.services=
# Timeout, in seconds, to use when doing blocking API calls to Cloud Foundry
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_API_TIMEOUT
# and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_API_TIMEOUT).
spring.cloud.deployer.cloudfoundry.stream.apiTimeout=360
spring.cloud.deployer.cloudfoundry.task.apiTimeout=360
# Timeout, in milliseconds, to use when querying the Cloud Foundry API to compute app status
# (to set the environment variable, use SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_STATUS_TIMEOUT
# and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_STATUS_TIMEOUT).
spring.cloud.deployer.cloudfoundry.stream.statusTimeout=5000
spring.cloud.deployer.cloudfoundry.task.statusTimeout=5000

Note that you can set spring.cloud.deployer.cloudfoundry.services,
spring.cloud.deployer.cloudfoundry.buildpack, or the Spring Cloud Deployer-standard
spring.cloud.deployer.memory and spring.cloud.deployer.disk
as part of an individual deployment request by using the deployer.<app-name> shortcut, as the following example shows:

You can also set this property at the global level for all the streams as applicable to any deployment property by setting
SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_JAVA_OPTS as the server level property.

33. Debugging

If you want to get better insights into what is happening when your streams and tasks are being deployed, you may want
to turn on the following features:

Reactor “stacktraces”, showing which operators were involved before an error occurred. This feature is helpful, as the deployer
relies on project reactor and regular stacktraces may not always allow understanding the flow before an error happened.
Note that this comes with a performance penalty, so it is disabled by default.

34. Spring Cloud Config Server

You can use Spring Cloud Config Server to centralize configuration properties for Spring Boot applications. Likewise,
both Spring Cloud Data Flow and the applications orchestrated by Spring Cloud Data Flow can be integrated with
a configuration server to use the same capabilities.

34.1. Stream, Task, and Spring Cloud Config Server

Similar to Spring Cloud Data Flow server, you can configure both the stream and task applications to resolve the centralized properties from the configuration server.
Setting the spring.cloud.config.uri property for the deployed applications is a common way to bind to the configuration server.
See the Spring Cloud Config Client reference guide for more information.
Since this property is likely to be used across all applications deployed by the Data Flow server, the Data Flow server’s spring.cloud.dataflow.applicationProperties.stream property for stream applications and spring.cloud.dataflow.applicationProperties.task property for task applications can be used to pass the uri of the Config Server to each deployed stream or task application. See the section on common application properties for more information.

Note that, if you use applications from the App Starters project, these applications already embed the spring-cloud-services-starter-config-client dependency.
If you build your application from scratch and want to add the client side support for config server, you can add a dependency reference to the config server client library. The following snippet shows a Maven example:

You may see a WARN logging message if the application that uses this library cannot connect to the configuration
server when the application starts and whenever the /health endpoint is accessed.
If you know that you are not using config server functionality, you can disable the client library by setting the
SPRING_CLOUD_CONFIG_ENABLED environment variable to false.
Another, more drastic, option is to disable the platform health check by setting the
SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_HEALTH_CHECK environment variable to none.

34.2. Sample Manifest Template

The following manifest.yml template includes the required environment variables for the Spring Cloud Data Flow server and deployed
applications and tasks to successfully run on Cloud Foundry and automatically resolve centralized properties from my-config-server
at runtime:

where my-config-server is the name of the Spring Cloud Config Service instance running on Cloud Foundry.

By binding the
service to both Spring Cloud Data Flow server and all the Spring Cloud Stream and Spring Cloud Task applications
respectively, we can now resolve centralized properties backed by this service.

34.3. Self-signed SSL Certificate and Spring Cloud Config Server

Often, in a development environment, we may not have a valid certificate to enable SSL communication between clients and
the backend services. However, the configuration server for Pivotal Cloud Foundry uses HTTPS for all client-to-service communication,
so we need to add a self-signed SSL certificate in environments with no valid certificates.

By using the same manifest.yml template listed in the previous section for the server, we can provide the self-signed
SSL certificate by setting TRUST_CERTS: <API_ENDPOINT>.

However, the deployed applications also require TRUST_CERTS as a flat environment variable (as opposed to being wrapped inside
SPRING_APPLICATION_JSON), so we must instruct the server with yet another set of tokens (SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_STREAM_USE_SPRING_APPLICATION_JSON: false
and SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_USE_SPRING_APPLICATION_JSON: false) for stream and task applications,
respectively. With this setup, the applications receive their application properties as regular environment variables.

The following listing shows the updated manifest.yml with the required changes. Both the Data Flow server and deployed applications
get their configuration from the my-config-server Cloud Config server (deployed as a Cloud Foundry service).

35. Configure Scheduling

This section discusses how to configure Spring Cloud Data Flow to connect to the
PCF-Scheduler as its agent to execute tasks.

Before following these instructions, be sure to have an instance of the PCF-Scheduler service running in your Cloud
Foundry space. To create a PCF-Scheduler in your space (assuming it is in your Market Place) execute the following
from the CF CLI: cf create-service scheduler-for-pcf standard <name of service>. Name of a service
is later used to bound running application in PCF.

For scheduling, you must add (or update) the following environment variables in your environment:

Where the SPRING_CLOUD_SCHEDULER_CLOUDFOUNDRY_SCHEDULER_URL has the following format: scheduler.<Domain-Name> (for
example, scheduler.local.pcfdev.io). Check the actual address from your PCF environment.

Shell

This section covers the options for starting the shell and more advanced functionality relating to how the shell handles white spaces, quotes, and interpretation of SpEL expressions.
The introductory chapters to the
Stream DSL and Composed Task DSL are good places to start for the most common usage of shell commands.

36. Shell Options

The shell is built upon the Spring Shell project.
There are command line options generic to Spring Shell and some specific to Data Flow.
The shell takes the following command line options

The spring.shell.commandFile option can be used to point to an existing file that contains
all the shell commands to deploy one or many related streams and tasks.
Multiple files execution is also supported, they should be passed as comma delimited string :

--spring.shell.commandFile=file1.txt,file2.txt

This is useful when creating some scripts to help automate deployment.

Also, the following shell command helps to modularize a complex script into multiple independent files:

dataflow:>script --file <YOUR_AWESOME_SCRIPT>

37. Listing Available Commands

Typing help at the command prompt gives a listing of all available commands.
Most of the commands are for Data Flow functionality, but a few are general purpose.

Tab completion is also available inside the stream or composed task DSL expression for application or task properties. You can also use TAB to get hints in a stream DSL expression for what available sources, processors, or sinks can be used.

39. White Space and Quoting Rules

It is only necessary to quote parameter values if they contain spaces or the | character. The following example passes a SpEL expression (which is applied to any data it encounters) to a transform processor:

transform --expression='new StringBuilder(payload).reverse()'

If the parameter value needs to embed a single quote, use two single quotes, as follows:

scan --query='Select * from /Customers where name=''Smith'''

39.1. Quotes and Escaping

There is a Spring Shell-based client that talks to the Data Flow Server and is responsible for parsing the DSL.
In turn, applications may have applications properties that rely on embedded languages, such as the Spring Expression Language.

The shell, Data Flow DSL parser, and SpEL have rules about how they handle quotes and how syntax escaping works.
When combined together, confusion may arise.
This section explains the rules that apply and provides examples of the most complicated situations you may encounter when all three components are involved.

It’s not always that complicated

If you do not use the Data Flow shell (for example, you use the REST API directly) or if application properties are not SpEL expressions, then the escaping rules are simpler.

39.1.1. Shell rules

Arguably, the most complex component when it comes to quotes is the shell. The rules can be laid out quite simply, though:

A shell command is made of keys (--something) and corresponding values. There is a special, keyless mapping, though, which is described later.

A value cannot normally contain spaces, as space is the default delimiter for commands.

Spaces can be added though, by surrounding the value with quotes (either single (') or double (") quotes).

39.1.2. Property files rules

Rules are relaxed when loading the properties from files.
* The special characters used in property files (both Java and YAML) needs to be escaped. For example \ should be replaced by \\, '\t` by \\t and so forth.
* For Java property files (--propertiesFile <FILE_PATH>.properties) the property values should not be surrounded by quotes! It is not needed even if they contain spaces.

filter.expression=payload > 5

For YAML property files (--propertiesFile <FILE_PATH>.yaml), though, the values need to be surrounded by double quotes.

app:
filter:
filter:
expression: "payload > 5"

39.1.3. DSL Parsing Rules

At the parser level (that is, inside the body of a stream or task definition) the rules are as follows:

Option values are normally parsed until the first space character.

They can be made of literal strings, though, surrounded by single or double quotes.

To embed such a quote, use two consecutive quotes of the desired kind.

As such, the values of the --expression option to the filter application are semantically equivalent in the following examples:

This works because there are no spaces. It is not very legible, though.

2

This uses single quotes to protect the whole argument. Hence, the actual single quotes need to be doubled.

3

SpEL recognizes String literals with either single or double quotes, so this last method is arguably the most readable.

Please note that the preceding examples are to be considered outside of the shell (for example, when calling the REST API directly).
When entered inside the shell, chances are that the whole stream definition is itself inside double quotes, which would need to be escaped. The whole example then becomes the following:

39.1.4. SpEL Syntax and SpEL Literals

The last piece of the puzzle is about SpEL expressions.
Many applications accept options that are to be interpreted as SpEL expressions, and, as seen above, String literals are handled in a special way there, too. The rules are as follows:

Literals can be enclosed in either single or double quotes.

Quotes need to be doubled to embed a literal quote. Single quotes inside double quotes need no special treatment, and the reverse is also true.

As a last example, assume you want to use the transform processor.
This processor accepts an expression option which is a SpEL expression. It is to be evaluated against the incoming message, with a default of payload (which forwards the message payload untouched).

It is important to understand that the following statements are equivalent:

transform --expression=payload
transform --expression='payload'

However, they are different from the following (and variations upon them):

In the first line, there are single quotes around the string (at the Data Flow parser level), but they need to be doubled because they are inside a string literal (started by the first single quote after the equals sign).

2

The second and third lines, use single and double quotes respectively to encompass the whole string at the Data Flow parser level. Consequently, the other kind of quote can be used inside the string. The whole thing is inside the --definition argument to the shell, though, which uses double quotes. Consequently, double quotes are escaped (at the shell level)

Streams

This section goes into more detail about how you can create Streams, which are collections of
Spring Cloud Stream applications. It covers topics such as
creating and deploying Streams.

If you are just starting out with Spring Cloud Data Flow, you should probably read the
Getting Started guide before diving into
this section.

40. Introduction

A Stream is are a collection of long-lived Spring Cloud Stream applications that communicate with each other over messaging middleware.
A text-based DSL defines the configuration and data flow between the applications. While many applications are provided for you to implement common use-cases, you typically create a custom Spring Cloud Stream application to implement custom business logic.

The general lifecycle of a Stream is:

Register applications.

Create a Stream Definition.

Deploy the Stream.

Undeploy or Destroy the Stream.

Upgrade or Rollack applications in the Stream.

If you use Skipper, you can upgrade or rollback applications in the Stream.

There are two options for deploying streams:

Use a Data Flow Server implementation that deploys to a single platform.

Configure the Data Flow Server to delegate the deployment to a new server in the Spring Cloud ecosystem named Skipper.

When using the first option, you can use the Local Data Flow Server to deploy streams to your local machine, the Data Flow Server for Cloud Foundry to deploy streams to a single org and space on Cloud Foundry.
Similarly, you can use Data Flow Server for Kuberenetes to deploy a stream to a single namespace on a Kubernetes cluster.
See the Spring Cloud Data Flow project page for a list of Data Flow server implementations.

When using the second option, you can configure Skipper to deploy applications to one or more Cloud Foundry orgs and spaces, one or more namespaces on a Kubernetes cluster, or to the local machine.
When deploying a stream in Data Flow using Skipper, you can specify which platform to use at deployment time.
Skipper also provides Data Flow with the ability to perform updates to deployed streams.
There are many ways the applications in a stream can be updated, but one of the most common examples is to upgrade a processor application with new custom business logic while leaving the existing source and sink applications alone.

40.1. Stream Pipeline DSL

A stream is defined by using a unix-inspired Pipeline syntax.
The syntax uses vertical bars, also known as “pipes” to connect multiple commands.
The command ls -l | grep key | less in Unix takes the output of the ls -l process and pipes it to the input of the grep key process.
The output of grep in turn is sent to the input of the less process.
Each | symbol connects the standard output of the command on the left to the standard input of the command on the right.
Data flows through the pipeline from left to right.

In Data Flow, the Unix command is replaced by a Spring Cloud Stream application and each pipe symbol represents connecting the input and output of applications over messaging middleware, such as RabbitMQ or Apache Kafka.

Each Spring Cloud Stream application is registered under a simple name.
The registration process specifies where the application can be obtained (for example, in a Maven Repository or a Docker registry). You can find out more information on how to register Spring Cloud Stream applications in this section.
In Data Flow, we classify the Spring Cloud Stream applications as Sources, Processors, or Sinks.

As a simple example, consider the collection of data from an HTTP Source writing to a File Sink.
Using the DSL, the stream description is:

http | file

A stream that involves some processing would be expressed as:

http | filter | transform | file

Stream definitions can be created by using the shell’s stream create command, as shown in the following example:

dataflow:> stream create --name httpIngest --definition "http | file"

The Stream DSL is passed in to the --definition command option.

The deployment of stream definitions is done through the shell’s stream deploy command.

dataflow:> stream deploy --name ticktock

The Getting Started section shows you how to start the server and how to start and use the Spring Cloud Data Flow shell.

Note that the shell calls the Data Flow Servers' REST API. For more information on making HTTP requests directly to the server, consult the REST API Guide.

40.2. Stream Application DSL

The Stream Pipeline DSL described in the previous section automatically sets the input and output binding properties of each Spring Cloud Stream application.
This can be done because there is only one input and/or output destination in a Spring Cloud Stream application that uses the provided binding interface of a Source, Processor, or Sink.
However, a Spring Cloud Stream application can define a custom binding interface such as the one shown below

In these cases with multiple input and output bindings, Data Flow cannot make any assumptions about the flow of data from one application to another.
Therefore the developer needs to set the binding properties to 'wire up' the application.
The Stream Application DSL uses a comma, instead of the pipe symbol, to indicate that Data Flow should not configure the binding properties of the application.
For example:

There are four applications in this stream.
The baristaApp has two output destinations, hotDrinks and coldDrinks intended to be consumed by the hotDrinkDeliveryApp and coldDrinkDeliveryApp respectively.
When deploying this stream, you need to set the binding properties so that the baristaApp sends hot drink messages to the hotDrinkDeliveryApp destination and cold drink messages to the coldDrinkDeliveryApp destination.
For example

If you want to use consumer groups, you will need to set the Spring Cloud Stream application property spring.cloud.stream.bindings.<channelName>.producer.requiredGroups and spring.cloud.stream.bindings.<channelName>.group on the producer and consumer applications respectively.

Another common use case for the Stream Application DSL is to deploy a http gateway application that sends a synchronous request/reply message to a Kafka or RabbitMQ application.
In this case both the http gateway application and the Kafka or RabbitMQ application can be a Spring Integration application that does not make use of the Spring Cloud Stream library.

It is also possible to deploy just a single application using the Stream application DSL.

40.3. Application properties

Each application takes properties to customize its behavior. As an example, the http source module exposes a port setting that allows the data ingestion port to be changed from the default value.

This port property is actually the same as the standard Spring Boot server.port property.
Data Flow adds the ability to use the shorthand form port instead of server.port.
One may also specify the longhand version as well, as shown in the following example:

41. Stream Lifecycle

41.1. Register a Stream App

You can register a Stream App with the App Registry by using the Spring Cloud Data Flow Shell
app register command. You must provide a unique name, an application type, and a URI that can be
resolved to the app artifact. For the type, specify source, processor, sink, or app.
Here are a few examples for source, processor and sink:

If you would like to register multiple apps at one time, you can store them in a properties file
where the keys are formatted as <type>.<name> and the values are the URIs.

For example, if you would like to register the snapshot versions of the http and log
applications built with the RabbitMQ binder, you could have the following in a properties file (for example, stream-apps.properties):

Registering an application using --type app is the same as registering a source, processor or sink.
Applications of the type app are only allowed to be used in the Stream Application DSL, which uses a comma instead of the pipe symbol in the DSL, and instructs Data Flow not to configure the Spring Cloud Stream binding properties of the application.
The application that is registered using --type app does not have to be a Spring Cloud Stream app, it can be any Spring Boot application.
See the Stream Application DSL introduction for more information on using this application type.

41.1.1. Register Supported Applications and Tasks

For convenience, we have the static files with application-URIs (for both maven and docker) available
for all the out-of-the-box stream and task/batch app-starters. You can point to this file and import
all the application-URIs in bulk. Otherwise, as explained previously, you can register them individually or have your own custom property file with only the required application-URIs in it. It is recommended, however, to have a “focused” list of desired application-URIs in a custom property file.

The following table lists the bit.ly links to the available Stream Application Starters based on Spring Boot 1.5.x:

The following table lists the bit.ly links to the available Stream Application Starters based on Spring Boot 2.0.x:

App Starter actuator endpoints are secured by default. You can disable security by deploying streams with the property app.*.spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration. On Kubernetes refer to the section Liveness and readiness probes to configure security for actuator endpoints.

You can also pass the --local option (which is true by default) to indicate whether the
properties file location should be resolved within the shell process itself. If the location should
be resolved from the Data Flow Server process, specify --local false.

When using either app register or app import, if an app is already registered with
the provided name and type, it is not overridden by default. If you would like to override the
pre-existing app coordinates, then include the --force option.

Note, however, that, once downloaded, applications may be cached locally on the Data Flow server, based on the resource
location. If the resource location does not change (even though the actual resource bytes may be different), then it
is not re-downloaded. When using maven:// resources on the other hand, using a constant location may still circumvent
caching (if using -SNAPSHOT versions).

Moreover, if a stream is already deployed and using some version of a registered app, then (forcibly) re-registering a
different app has no effect until the stream is deployed again.

In some cases, the Resource is resolved on the server side. In others, the
URI is passed to a runtime container instance where it is resolved. Consult
the specific documentation of each Data Flow Server for more detail.

41.1.2. Whitelisting application properties

Stream and Task applications are Spring Boot applications that are aware of many Common Application Properties, such as server.port but also families of properties such as those with the prefix spring.jmx and logging. When creating your own application, you should whitelist properties so that the shell and the UI can display them first as primary properties when presenting options through TAB completion or in drop-down boxes.

To whitelist application properties, create a file named spring-configuration-metadata-whitelist.properties in the META-INF resource directory. There are two property keys that can be used inside this file. The first key is named configuration-properties.classes. The value is a comma separated list of fully qualified @ConfigurationProperty class names. The second key is configuration-properties.names, whose value is a comma-separated list of property names. This can contain the full name of the property, such as server.port, or a partial name to whitelist a category of property names, such as spring.jmx.

41.1.3. Creating and Using a Dedicated Metadata Artifact

You can go a step further in the process of describing the main properties that your stream or task app supports by
creating a metadata companion artifact. This jar file contains only the Spring boot JSON file about
configuration properties metadata and the whitelisting file described in the previous section.

The following example shows the contents of such an artifact, for the canonical log sink:

Note that the spring-configuration-metadata.json file is quite large. This is because it contains the concatenation of all the properties that
are available at runtime to the log sink (some of them come from spring-boot-actuator.jar, some of them come from
spring-boot-autoconfigure.jar, some more from spring-cloud-starter-stream-sink-log.jar, and so on). Data Flow
always relies on all those properties, even when a companion artifact is not available, but here all have been merged
into a single file.

To help with that (you do not want to try to craft this giant JSON file by hand), you can use the
following plugin in your build:

This plugin comes in addition to the spring-boot-configuration-processor that creates the individual JSON files.
Be sure to configure both.

The benefits of a companion artifact include:

Being much lighter. (The companion artifact is usually a few kilobytes, as opposed to megabytes for the actual app.) Consequently, they are quicker to download,
allowing quicker feedback when using, for example, app info or the Dashboard UI.

As a consequence of being lighter, they can be used in resource constrained environments (such as PaaS) when metadata is
the only piece of information needed.

For environments that do not deal with Spring Boot uber jars directly (for example, Docker-based runtimes such as
Kubernetes or Cloud Foundry), this is the only way to provide metadata about the properties supported by the app.

Remember, though, that this is entirely optional when dealing with uber jars. The uber jar itself also includes the
metadata in it already.

41.1.4. Using the Companion Artifact

Once you have a companion artifact at hand, you need to make the system aware of it so that it can be used.

When registering a single app with app register, you can use the optional --metadata-uri option in the shell, as follows:

When registering several files by using the app import command, the file should contain a <type>.<name>.metadata line
in addition to each <type>.<name> line. Strictly speaking, doing so is optional (if some apps have it but some others do not, it works), but it is best practice.

The following example shows a Dockerized app, where the metadata artifact is being hosted in a Maven repository (retrieving
it through http:// or file:// would be equally possible).

For supporting property whitelisting, Spring Cloud Stream applications running in Spring Cloud Data Flow may include the Spring Boot configuration-processor as an optional dependency, as shown in the following example:

Make sure that the spring-boot-maven-plugin is included in the POM.
The plugin is necessary for creating the executable jar that is registered with Spring Cloud Data Flow.
Spring Initialzr includes the plugin in the generated POM.

41.2. Creating a Stream

The Spring Cloud Data Flow Server exposes a full RESTful API for managing the lifecycle of stream definitions, but the easiest way to use is it is through the Spring Cloud Data Flow shell. Start the shell as described in the Getting Started section.

New streams are created with the help of stream definitions. The definitions are built from a simple DSL. For example, consider what happens if we execute the following shell command:

dataflow:> stream create --definition "time | log" --name ticktock

This defines a stream named ticktock that is based off the DSL expression time | log. The DSL uses the "pipe" symbol (|), to connect a source to a sink.

41.2.1. Application Properties

Application properties are the properties associated with each application in the stream. When the application is deployed, the application properties are applied to the application through
command line arguments or environment variables, depending on the underlying deployment implementation.

The following stream can have application properties defined at the time of stream creation:

dataflow:> stream create --definition "time | log" --name ticktock

The shell command app info --name <appName> --type <appType> displays the white-listed application properties for the application.
For more info on the property white listing, refer to Whitelisting application properties

The following listing shows the white_listed properties for the time app:

Note that, in the preceding example, the fixed-delay and level properties defined for the apps time and log are the "'short-form'" property names provided by the shell completion.
These "'short-form'" property names are applicable only for the white-listed properties. In all other cases, only fully qualified property names should be used.

41.2.2. Common Application Properties

In addition to configuration through DSL, Spring Cloud Data Flow provides a mechanism for setting common properties to all
the streaming applications that are launched by it.
This can be done by adding properties prefixed with spring.cloud.dataflow.applicationProperties.stream when starting
the server.
When doing so, the server passes all the properties, without the prefix, to the instances it launches.

For example, all the launched applications can be configured to use a specific Kafka broker by launching the
Data Flow server with the following options:

Doing so causes the properties spring.cloud.stream.kafka.binder.brokers and spring.cloud.stream.kafka.binder.zkNodes
to be passed to all the launched applications.

Properties configured with this mechanism have lower precedence than stream deployment properties.
They are overridden if a property with the same key is specified at stream deployment time (for example,
app.http.spring.cloud.stream.kafka.binder.brokers overrides the common property).

41.3. Deploying a Stream

This section describes how to deploy a Stream when the Spring Cloud Data Flow server is responsible for deploying the stream. The following section, Stream Lifecycle with Skipper, covers the new deployment and upgrade features when the Spring Cloud Data Flow server delegates to Skipper for stream deployment. The description of how deployment properties applies to both approaches of Stream deployment.

Give the ticktock stream definition:

dataflow:> stream create --definition "time | log" --name ticktock

To deploy the stream, use the following shell command:

dataflow:> stream deploy --name ticktock

The Data Flow Server resolves time and log to maven coordinates and uses those to launch the time and log applications of the stream, as shown in the following listing:

In the preceding example, the time source sends the current time as a message each second, and the log sink outputs it by using the logging framework.
You can tail the stdout log (which has an <instance> suffix). The log files are located within the directory displayed in the Data Flow Server’s log output, as shown in the following listing:

However, it is not very common in real-world use cases to create and deploy the stream in one step.
The reason is that when you use the stream deploy command, you can pass in properties that define how to map the applications onto the platform (for example, what is the memory size of the container to use, the number of each application to run, and whether to enable data partitioning features).
Properties can also override application properties that were set when creating the stream.
The next sections cover this feature in detail.

41.3.1. Deployment Properties

When deploying a stream, you can specify properties that fall into two groups:

Properties that control how the apps are deployed to the target platform.
These properties use a deployer prefix and are referred to as deployer properties.

Properties that set application properties or override application properties set during stream creation and are referred to as application properties.

The syntax for deployer properties is deployer.<app-name>.<short-property-name>=<value>, and the syntax for application properties app.<app-name>.<property-name>=<value>. This syntax is used when passing deployment properties through the shell. You may also specify them in a YAML file, which is discussed later in this chapter.

The following table shows the difference in behavior between setting deployer and application properties when deploying an application.

Application Properties

Deployer Properties

Example Syntax

app.filter.expression=something

deployer.filter.count=3

What the application "sees"

expression=something or, if expression is one of the whitelisted properties, <some-prefix>.expression=something

Nothing

What the deployer "sees"

Nothing

spring.cloud.deployer.count=3. The spring.cloud.deployer prefix is automatically and always prepended to the property name.

Note that count is the reserved property name used by the underlying deployer. Consequently, if the application also has a custom property named count, it is not supported
when specified in 'short-form' form during stream deployment as it could conflict with the instance count deployer property. Instead, the count as a custom application property can be
specified in its fully qualified form (for example, app.something.somethingelse.count) during stream deployment or it can be specified by using the 'short-form' or the fully qualified form during the stream creation,
where it is processed as an app property.

File references use the --propertiesFile option and point it to a local .properties, .yaml or .yml file
(that is, a file that resides in the filesystem of the machine running the shell). Being read
as a .properties file, normal rules apply (ISO 8859-1 encoding, =, <space> or
: delimiter, and others), although we recommend using = as a key-value pair delimiter,
for consistency. The following example shows a stream deploy command that uses the --propertiesFile option:

Passing application properties

The application properties can also be specified when deploying a stream. When specified during deployment, these application properties can either be specified as
'short-form' property names (applicable for white-listed properties) or as fully qualified property names. The application properties should have the prefix app.<appName/label>.

For example, consider the following stream command:

dataflow:> stream create --definition "time | log" --name ticktock

The stream in the precedig example can also be deployed with application properties by using the 'short-form' property names, as shown in the following example:

Passing Spring Cloud Stream properties

Spring Cloud Data Flow sets the required Spring Cloud Stream properties for the applications inside the stream. Most importantly, the spring.cloud.stream.bindings.<input/output>.destination is set internally for the apps to bind.

If you want to override any of the Spring Cloud Stream properties, they can be set with deployment properties.

If there are multiple binders available in the classpath for each of the applications and the binder is chosen for each deployment, then the stream can be deployed with the specific Spring Cloud Stream properties, as follows:

Overriding the destination names is not recommended, because Spring Cloud Data Flow internally takes care of setting this property.

Passing Per-binding Producer and Consumer Properties

A Spring Cloud Stream application can have producer and consumer properties set on a per-binding basis.
While Spring Cloud Data Flow supports specifying short-hand notation for per-binding producer properties such as partitionKeyExpression and partitionKeyExtractorClass (as described in Passing Stream Partition Properties), all the supported Spring Cloud Stream producer/consumer properties can be set as Spring Cloud Stream properties for the app directly as well.

The consumer properties can be set for the inbound channel name with the prefix app.[app/label name].spring.cloud.stream.bindings.<channelName>.consumer.. The producer properties can be set for the outbound channel name with the prefix app.[app/label name].spring.cloud.stream.bindings.<channelName>.producer..
Consider the following example:

dataflow:> stream create --definition "time | log" --name ticktock

The stream can be deployed with producer and consumer properties, as follows:

Passing Stream Partition Properties

A common pattern in stream processing is to partition the data as it is streamed.
This entails deploying multiple instances of a message-consuming app and using
content-based routing so that messages with a given key (as determined at runtime)
are always routed to the same app instance. You can pass the partition properties during
stream deployment to declaratively configure a partitioning strategy to route each
message to a specific consumer instance.

The following list shows variations of deploying partitioned streams:

app.[app/label name].producer.partitionKeyExtractorClass:
The class name of a PartitionKeyExtractorStrategy (default: null)

app.[app/label name].producer.partitionKeyExpression:
A SpEL expression, evaluated against the message, to determine the partition key.
Only applies if partitionKeyExtractorClass is null. If both are null, the app
is not partitioned (default: null)

app.[app/label name].producer.partitionSelectorClass:
The class name of a PartitionSelectorStrategy (default: null)

app.[app/label name].producer.partitionSelectorExpression:
A SpEL expression, evaluated against the partition key, to determine the partition
index to which the message is routed. The final partition index is the
return value (an integer) modulo [nextModule].count. If both the class and
expression are null, the underlying binder’s default PartitionSelectorStrategy
is applied to the key (default: null)

In summary, an app is partitioned if its count is > 1 and the previous app has a
partitionKeyExtractorClass or partitionKeyExpression (partitionKeyExtractorClass takes precedence).
When a partition key is extracted, the partitioned app instance is determined by
invoking the partitionSelectorClass, if present, or the partitionSelectorExpression % partitionCount.
partitionCount is application count, in the case of RabbitMQ, or the underlying
partition count of the topic, in the case of Kafka.

If neither a partitionSelectorClass nor a partitionSelectorExpression is
present, the result is key.hashCode() % partitionCount.

Passing application content type properties

In a stream definition, you can specify that the input or the output of an application must be converted to a different type.
You can use the inputType and outputType properties to specify the content type for the incoming data and outgoing data, respectively.

The http app is expected to send the data in JSON and the filter app receives the JSON data
and processes it as a Spring Tuple.
In order to do so, we use the inputType property on the filter app to convert the data into the expected Spring Tuple format.
The transform application processes the Tuple data and sends the processed data to the downstream log application.

Consider the following example of sending some data to the http application:

Depending on how applications are chained, the content type conversion can be specified either as an --outputType in the upstream app or as an --inputType in the downstream app.
For instance, in the above stream, instead of specifying the --inputType on the 'transform' application to convert, the option --outputType=application/x-spring-tuple can also be specified on the 'http' application.

41.6. Validating a Stream

Sometimes the one or more of the apps contained within a stream definition contain an invalid URI in its registration.
This can caused by an invalid URI entered at app registration time or the app was removed from the repository from which it was to be drawn.
To verify that all the apps contained in a stream are resolve-able, a user can use the validate command.
For example:

In the example above the user validated their ticktock stream. As we see that both the source:time and sink:log are valid.
Now let’s see what happens if we have a stream definition with a registered app with an invalid URI.

42. Stream Lifecycle with Skipper

Skipper is a server that you discover Spring Boot applications and manage their lifecycle on multiple Cloud Platforms.

Applications in Skipper are bundled as packages that contain the application’s resource location, application properties and deployment properites.
You can think Skipper packages as analogous to packages found in tools such as apt-get or brew.

When Data Flow deploys a Stream, it will generate and upload a package to Skipper that represents the applications in the Stream.
Subsequent commands to upgrade or rollback the applications within the Stream are passed through to Skipper.
In addition, the Stream definition is reverse engineered from the package and the status of the Stream is also delegated to Skipper.

42.1. Register a Versioned Stream App

Skipper extends the Register a Stream App
lifecycle with support of multi-versioned stream applications.
This allows to upgrade or rollback those applications at runtime using the deployment properties.

Register a versioned stream application using the app register command. You must provide a unique name, application type, and a URI that can be resolved to the app artifact.
For the type, specify "source", "processor", or "sink". The version is resolved from the URI. Here are a few examples:

All applications in a stream should have a default version set for the stream to be deployed.
Otherwise they will be treated as unregistered application during the deployment.
Use the app default to set the defaults.

There is an important optional command argument (called --platformName) to the stream deploy command.
Skipper can be configured to deploy to multiple platforms.
Skipper is pre-configured with a platform named default, which deploys applications to the local machine where Skipper is running.
The default value of the command line argument --platformName is default.
If you commonly deploy to one platform, when installing Skipper, you can override the configuration of the default platform.
Otherwise, specify the platformName to one of the values returned by the stream platform-list command.

42.3. Updating a Stream

To update the stream, use the command stream update which takes as a command argument either --properties or --propertiesFile.
You can pass in values to these command arguments in the same format as when deploy the stream with or without Skipper.
There is an important new top level prefix available when using Skipper, which is version.
If the Stream http | log was deployed, and the version of log which registered at the time of deployment was 1.1.0.RELEASE, the following command will update the Stream to use the 1.2.0.RELEASE of the log application.
Before updating the stream with the specific version of the app, we need to make sure that the app is registered with that version.

42.4. Force update of a Stream

When upgrading a stream, the --force option can be used to deploy new instances of currently deployed applications even if no applicaton or deployment properties have changed.
This behavior is needed in the case when configuration information is obtained by the application itself at startup time, for example from Spring Cloud Config Server.
You can specify which applications to force upgrade by using the option --app-names.
If you do not specify any application names, all the applications will be force upgraded.
You can specify --force and --app-names options together with --properties or --propertiesFile options.

42.5. Stream versions

Skipper keeps a history of the streams that were deployed.
After updating a Stream, there will be a second version of the stream.
You can query for the history of the versions using the command stream history --name <name-of-stream>.

42.6. Stream Manifests

Skipper keeps a “manifest” of the all the applications, their application properties, and their deployment properties after all values have been substituted.
This represents the final state of what was deployed to the platform.
You can view the manifest for any of the versions of a Stream by using the following command:

The majority of the deployment and application properties were set by Data Flow to enable the applications to talk to each other and to send application metrics with identifying labels.

42.7. Rollback a Stream

You can rollback to a previous version of the stream using the command stream rollback.

dataflow:>stream rollback --name httptest

The optional --releaseVersion command argument adds the version of the stream.
If not specified, the rollback goes to the previous stream version.

42.8. Application Count

The application count is a dynamic property of the system.
If, due to scaling at runtime, the application to be upgraded has 5 instances running, then 5 instances of the upgraded application are deployed.

42.9. Skipper’s Upgrade Strategy

Skipper has a simple 'red/black' upgrade strategy. It deploys the new version of the applications, using as many instances as the currently running version, and checks the /health endpoint of the application.
If the health of the new application is good, then the previous application is undeployed.
If the health of the new application is bad, then all new applications are undeployed and the upgrade is considered to be not successful.

The upgrade strategy is not a rolling upgrade, so if five applications of the application are running, then in a sunny-day scenario, five of the new applications are also running before the older version is undeployed.

To create a stream that acts as a 'tap' on another stream requires specifying the source destination name for the tap stream. The syntax for the source destination name is as follows:

:<streamName>.<label/appName>

To create a tap at the output of http in the preceding stream, the source destination name is mainstream.http
To create a tap at the output of the first transform app in the stream above, the source destination name is mainstream.step1

Note the colon (:) prefix before the destination names. The colon lets the parser recognize this as a destination name instead of an app name.

43.2. Using Labels in a Stream

When a stream is made up of multiple apps with the same name, they must be qualified with labels:
stream create --definition "http | firstLabel: transform --expression=payload.toUpperCase() | secondLabel: transform --expression=payload+'!' | log" --name myStreamWithLabels --deploy

43.3. Named Destinations

Instead of referencing a source or sink application, you can use a named destination.
A named destination corresponds to a specific destination name in the middleware broker (Rabbit, Kafka, and others).
When using the | symbol, applications are connected to each other with messaging middleware destination names created by the Data Flow server.
In keeping with the Unix analogy, one can redirect standard input and output using the less-than (<) and greater-than (>) characters.
To specify the name of the destination, prefix it with a colon (:).
For example, the following stream has the destination name in the source position:

This stream receives messages from the destination called myDestination, located at the broker, and connects it to the log app. You can also create additional streams that consume data from the same named destination.

In the precding stream, both the destinations (destination1 and destination2) are located in the broker. The messages flow from the source destination to the sink destination over a bridge app that connects them.

43.4. Fan-in and Fan-out

By using named destinations, you can support fan-in and fan-out use cases. Fan-in use cases are when multiple sources all send data to the same named destination, as shown in the following example:

s3 > :data
ftp > :data
http > :data

The preceding example directs the data payloads from the Amazon S3, FTP, and HTTP sources to the same named destination called data. Then an additional stream created with the following DSL expression would have all the data from those three sources sent to the file sink:

:data > file

The fan-out use case is when you determine the destination of a stream based on some information that is only known at runtime.
In this case, the Router Application can be used to specify how to direct the incoming message to one of N named destinations.

44. Stream Java DSL

Instead of using the shell to create and deploy streams, you can use the Java-based DSL provided by the spring-cloud-dataflow-rest-client module.
The Java DSL is a convenient wrapper around the DataFlowTemplate class that enables creating and deploying streams programmatically.

To get started, you need to add the following dependency to your project, as follows:

44.1. Overview

The classes at the heart of the Java DSL are StreamBuilder, StreamDefinition, Stream, StreamApplication, and DataFlowTemplate.
The entry point is a builder method on Stream that takes an instance of a DataFlowTemplate.
To create an instance of a DataFlowTemplate, you need to provide a URI location of the Data Flow Server.

Spring Boot auto-configuration for StreamBuilder and DataFlowTemplate is also available. The properties in DataFlowClientProperties can be used to configure the connection to the Data Flow server. The common property to start using is spring.cloud.dataflow.client.uri

The create method returns an instance of a StreamDefinition representing a Stream that has been created but not deployed.
This is called the definition style since it takes a single string for the stream definition, same as in the shell.
If applications have not yet been registered in the Data Flow server, you can use the DataFlowOperations class to register them.
With the StreamDefinition instance, you have methods available to deploy or destory the stream.

Stream stream = streamDefinition.deploy();

The Stream instance provides getStatus, destroy and undeploy methods to control and query the stream.
If you are going to immediately deploy the stream, there is no need to create a separate local variable of the type StreamDefinition. You can just chain the calls together, as follows:

The deploy method is overloaded to take a java.util.Map of deployment properties.

The StreamApplication class is used in the 'fluent' Java DSL style and is discussed in the next section. The StreamBuilder class is returned from the method Stream.builder(dataFlowOperations). In larger applications, it is common to create a single instance of the StreamBuilder as a Spring @Bean and share it across the application.

44.2. Java DSL styles

The Java DSL offers two styles to create Streams.

The definition style keeps the feel of using the pipes and filters textual DSL in the shell. This style is selected by using the definition method after setting the stream name - for example, Stream.builder(dataFlowOperations).name("ticktock").definition(<definition goes here>).

The fluent style lets you chain together sources, processors, and sinks by passing in an instance of a StreamApplication. This style is selected by using the source method after setting the stream name - for example, Stream.builder(dataFlowOperations).name("ticktock").source(<stream application instance goes here>). You then chain together processor() and sink() methods to create a stream definition.

Is this case, application properties are also overridden at deployment time in addition to setting the deployer property count for the log application.
When using the fluent style, the deployment properties are added by using the method addDeploymentProperty (for example, new StreamApplication("log").addDeploymentProperty("count", 2)), and you do not need to prefix the property with deployer.<app_name>.

In order to create and deploy your streams, you need to make sure that the corresponding apps have been registered in the DataFlow server first.
Attempting to create or deploy a stream that contains an unknown app throws an exception. You can register your application by using the DataFlowTemplate, as follows:

The Stream applications can also be beans within your application that are injected in other classes to create Streams.
There are many ways to structure Spring applications, but one way is to have an @Configuration class define the StreamBuilder and StreamApplications, as shown in the following example:

44.3. Using the DeploymentPropertiesBuilder

Regardless of style you choose, the deploy(Map<String, String> deploymentProperties) method allows customization of how your streams will be deployed. We made it a easier to create a map with properties by using a builder style, as well as creating static methods for some properties so you don’t need to remember the name of such properties. If you take the previous example of createDeploymentProperties it could be rewritten as:

This utility class is meant to help with the creation of a Map and adds a few methods to assist with defining pre-defined properties.

45. Deploying using Skipper

If you desire to deploy your streams using Skipper, you need to pass certain properties to the server specific to a Skipper based deployment, for example selecting the target platfrom.
The SkipperDeploymentPropertiesBuilder provides you all the properties in DeploymentPropertiesBuilder and adds those needed for Skipper.

46. Stream Applications with Multiple Binder Configurations

In some cases, a stream can have its applications bound to multiple spring cloud stream binders when they are required to connect to different messaging
middleware configurations. In those cases, it is important to make sure the applications are configured appropriately with their binder
configurations. For example, consider the following stream:

http | transform --expression=payload.toUpperCase() | log

In this stream, each application connects to messaging middleware in the following way:

The HTTP source sends events to RabbitMQ (rabbit1).

The Transform processor receives events from RabbitMQ (rabbit1) and sends the processed events into Kafka (kafka1).

The log sink receives events from Kafka (kafka1).

Here, rabbit1 and kafka1 are the binder names given in the spring cloud stream application properties.
Based on this setup, the applications have the following binder(s) in their classpath with the appropriate configuration:

HTTP: Rabbit binder

Transform: Both Kafka and Rabbit binders

Log: Kafka binder

The spring-cloud-stream binder configuration properties can be set within the applications themselves.
If not, they can be passed through deployment properties when the stream is deployed as shown in the following example:

47.1. Simple Stream Processing

As an example of a simple processing step, we can transform the payload of the HTTP posted data to upper case by using the following stream definition:
http | transform --expression=payload.toUpperCase() | log

This example has shown that payload splits that contain the same word are routed to the same application instance.

47.3. Other Source and Sink Application Types

This example shows something a bit more complicated: swapping out the time source for something else. Another supported source type is http, which accepts data for ingestion over HTTP POSTs. Note that the http source accepts data on a different port from the Data Flow Server (default 8080). By default, the port is randomly assigned.

To create a stream using an http source but still using the same log sink, we would change the original command in the Simple Stream Processing example to the following:

Note that we do not see any other output this time until we actually post some data (by using a shell command). In order to see the randomly assigned port on which the http source is listening, run the following command:

dataflow:> runtime apps

You should see that the corresponding http source has a url property containing the host and port information on which it is listening. You are now ready to post to that url, as shown in the following example:

We could also change the sink implementation. You could pipe the output to a file (file), to hadoop (hdfs), or to any of the other sink applications that are available. You can also define your own applications.

Tasks

This section goes into more detail about how you can work with Spring Cloud Task.
It covers topics such as creating and running task applications.

If you are just starting out with Spring Cloud Data Flow, you should probably read the “Getting Started” guide before diving into this section.

48. Introduction

A task executes a process on demand.
In the case of Spring Cloud Task, a task is a Spring Boot application that is annotated with @EnableTask.
A user launches a task that performs a certain process, and, once complete, the task ends. Unlike a stream where a stream definition can have at most one deployment a single task definition can be launched multiple times simultaneously.
An example of a task would be a Spring Boot application that exports data from a JDBC repository to an HDFS instance.
Tasks record the start time and the end time as well as the boot exit code in a relational database.
The task implementation is based on the Spring Cloud Task project.

48.1. Application properties

Each application takes properties to customize its behavior. As an example, the timestamp task format setting establishes a output format that is different from the default value.

This timestamp property is actually the same as the timestamp.format property specified by the timestamp application.
Data Flow adds the ability to use the shorthand form format instead of timestamp.format.
One may also specify the longhand version as well, as shown in the following example:

49.1. Creating a Task Application

While Spring Cloud Task does provide a number of out-of-the-box applications (at spring-cloud-task-app-starters), most task applications require custom development.
To create a custom task application:

Use the Spring Initializer to create a new project, making sure to select the following starters:

Cloud Task: This dependency is the spring-cloud-starter-task.

JDBC: This dependency is the spring-jdbc starter.

Within your new project, create a new class to serve as your main class, as follows:

With this class, you need one or more CommandLineRunner or ApplicationRunner implementations within your application. You can either implement your own or use the ones provided by Spring Boot (there is one for running batch jobs, for example).

Packaging your application with Spring Boot into an über jar is done through the standard {spring-boot-docs-reference}/html/getting-started-first-application.html#getting-started-first-application-executable-jar[Spring Boot conventions].
The packaged application can be registered and deployed as noted below.

49.1.1. Task Database Configuration

When launching a task application, be sure that the database driver that is being used by Spring Cloud Data Flow is also a dependency on the task application.
For example, if your Spring Cloud Data Flow is set to use Postgresql, be sure that the task application also has Postgresql as a dependency.

When you run tasks externally (that is, from the command line) and you want Spring Cloud Data Flow to show the TaskExecutions in its UI, be sure that common datasource settings are shared among the both.
By default, Spring Cloud Task uses a local H2 instance, and the execution is recorded to the database used by Spring Cloud Data Flow.

49.2. Registering a Task Application

You can register a Task App with the App Registry by using the Spring Cloud Data Flow Shell app register command.
You must provide a unique name and a URI that can be resolved to the app artifact. For the type, specify "task".
The following listing shows three examples:

When providing a URI with the maven scheme, the format should conform to the following:

maven://<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>

If you would like to register multiple apps at one time, you can store them in a properties file where the keys are formatted as <type>.<name> and the values are the URIs.
For example, the followinng listing would be a valid properties file:

task.foo=file:///tmp/foo.jar
task.bar=file:///tmp/bar.jar

Then you can use the app import command and provide the location of the properties file by using the --uri option, as follows:

For convenience, we have the static files with application-URIs (for both maven and docker) available for all the out-of-the-box Task app-starters.
You can point to this file and import all the application-URIs in bulk.
Otherwise, as explained earlier in this chapter, you can register them individually or have your own custom property file with only the required application-URIs in it.
It is recommended, however, to have a “focused” list of desired application-URIs in a custom property file.

You can also pass the --local option (which is TRUE by default) to indicate whether the properties file location should be resolved within the shell process itself.
If the location should be resolved from the Data Flow Server process, specify --local false.

When using either app register or app import, if a task app is already registered with
the provided name, it is not overridden by default. If you would like to override the
pre-existing task app, then include the --force option.

In some cases, the Resource is resolved on the server side.
In other cases, the URI is passed to a runtime container instance where it is resolved.
Consult the specific documentation of each Data Flow Server for more detail.

49.3. Creating a Task Definition

You can create a task Definition from a task app by providing a definition name as well as
properties that apply to the task execution. Creating a task definition can be done through
the RESTful API or the shell. To create a task definition by using the shell, use the
task create command to create the task definition, as shown in the following example:

Additional properties meant for a TaskLauncher itself can be passed in by using a --properties option.
The format of this option is a comma-separated string of properties prefixed with app.<task definition name>.<property>.
Properties are passed to TaskLauncher as application properties.
It is up to an implementation to choose how those are passed into an actual task application.
If the property is prefixed with deployer instead of app, it is passed to TaskLauncher as a deployment property and its meaning may be TaskLauncher implementation specific.

49.4.1. Common application properties

In addition to configuration through DSL, Spring Cloud Data Flow provides a mechanism for setting common properties to all the task applications that are launched by it.
This can be done by adding properties prefixed with spring.cloud.dataflow.applicationProperties.task when starting the server.
When doing so, the server passes all the properties, without the prefix, to the instances it launches.

For example, all the launched applications can be configured to use the properties prop1 and prop2 by launching the Data Flow server with the following options:

This causes the properties, prop1=value1 and prop2=value2, to be passed to all the launched applications.

Properties configured by using this mechanism have lower precedence than task deployment properties.
They are overridden if a property with the same key is specified at task launch time (for example, app.trigger.prop2
overrides the common property).

49.5. Limit the number concurrent task launches

Spring Cloud Data Flow allows a user establish the maximum number of concurrently running tasks to prevent the saturation of IaaS/hardware resources.
This limit can be configured by setting the spring.cloud.dataflow.task.maximum-concurrent-tasks property. By default it is set to 20.
If the number of concurrently running tasks is equal or greater than the value set by spring.cloud.dataflow.task.maximum-concurrent-tasks the next
task launch request will be declined and a warning message will be returned via the RESTful API, Shell or UI.

49.6. Reviewing Task Executions

Once the task is launched, the state of the task is stored in a relational DB. The state
includes:

Task Name

Start Time

End Time

Exit Code

Exit Message

Last Updated Time

Parameters

A user can check the status of their task executions through the RESTful API or the shell.
To display the latest task executions through the shell, use the task execution list command.

To get a list of task executions for just one task definition, add --name and
the task definition name, for example task execution list --name foo. To retrieve full
details for a task execution use the task execution status command with the id of the task execution,
for example task execution status --id 549.

49.7. Destroying a Task Definition

Destroying a Task Definition removes the definition from the definition repository.
This can be done through the RESTful API or the shell.
To destroy a task through the shell, use the task destroy command, as shown in the following example:

dataflow:>task destroy mytask
Destroyed task 'mytask'

The task execution information for previously launched tasks for the definition remains in the task repository.

This does not stop any currently executing tasks for this definition. Instead, it removes the task definition from the database.

49.8. Validating a Task

Sometimes the one or more of the apps contained within a task definition contain an invalid URI in its registration.
This can be caused by an invalid URI entered at app registration time or the app was removed from the repository from which it was to be drawn.
To verify that all the apps contained in a task are resolve-able, a user can use the validate command.
For example:

In the example above the user validated their time-stamp task. As we see task:timestamp app is valid.
Now let’s see what happens if we have a stream definition with a registered app with an invalid URI.

In this case Spring Cloud Data Flow states that the task is invalid because task:badtimestamp has an invalid URI.

50. Subscribing to Task/Batch Events

You can also tap into various task and batch events when the task is launched.
If the task is enabled to generate task or batch events (with the additional dependencies spring-cloud-task-stream and, in the case of Kafka as the binder, spring-cloud-stream-binder-kafka), those events are published during the task lifecycle.
By default, the destination names for those published events on the broker (Rabbit, Kafka, and others) are the event names themselves (for instance: task-events, job-execution-events, and so on).

The following table lists the default task and batch event and destination names on the broker:

Table 1. Task and Batch Event Destinations

Event

Destination

Task events

task-events

Job Execution events

job-execution-events

Step Execution events

step-execution-events

Item Read events

item-read-events

Item Process events

item-process-events

Item Write events

item-write-events

Skip events

skip-events

51. Composed Tasks

Spring Cloud Data Flow lets a user create a directed graph where each node of the graph is a task application.
This is done by using the DSL for composed tasks.
A composed task can be created through the RESTful API, the Spring Cloud Data Flow Shell, or the Spring Cloud Data Flow UI.

51.1. Configuring the Composed Task Runner

51.1.1. Registering the Composed Task Runner

By default, the Composed Task Runner application is not registered with Spring Cloud Data Flow.
Consequently, to launch composed tasks, we must first register the Composed
Task Runner as an application with Spring Cloud Data Flow, as follows:

You can also configure Spring Cloud Data Flow to use a different task definition name for the composed task runner.
This can be done by setting the spring.cloud.dataflow.task.composedTaskRunnerName property to the name of your choice.
You can then register the composed task runner application with the name you set by using that property.

51.1.2. Configuring the Composed Task Runner

The Composed Task Runner application has a dataflow.server.uri property that is used for validation and for launching child tasks.
This defaults to localhost:9393. If you run a distributed Spring Cloud Data Flow server, as you would if you deploy the server on Cloud Foundry, YARN, or Kubernetes, you need to provide the URI that can be used to access the server.
You can either provide this dataflow.server.uri property for the Composed Task Runner application when launching a composed task or you can provide a spring.cloud.dataflow.server.uri property for the Spring Cloud Data Flow server when it is started.
For the latter case, the dataflow.server.uri Composed Task Runner application property is automatically set when a composed task is launched.

In some cases, you may wish to execute an instance of the Composed Task Runner through the Task Launcher sink.
In that case, you must configure the Composed Task Runner to use the same datasource that the Spring Cloud Data Flow instance is using.
The datasource properties are set with the TaskLaunchRequest through the use of the commandlineArguments or the environmentProperties switches.
This is because the Composed Task Runner monitors the task_executions table to check the status of the tasks that it is running.
Using information from the table, it determines how it should navigate the graph.

Configuration Options

The ComposedTaskRunner task has the following options:

increment-instance-enabled
Allows a single ComposedTaskRunner instance to be re-executed without changing the parameters. Default is false which means a ComposedTaskRunner instance can only be executed once with a given set of parameters, if true it can be re-executed. (Boolean, default: false).
ComposedTaskRunner is built using Spring Batch and thus upon a successful execution the batch job is considered complete.
To launch the same ComposedTaskRunner definition multiple times you must set the increment-instance-enabled property to true or change the parameters for the definition for each launch.

interval-time-between-checks
The amount of time in millis that the ComposedTaskRunner will wait between checks of the database to see if a task has completed. (Integer, default: 10000).
ComposedTaskRunner uses the datastore to determine the status of each child tasks. This interval indicates to ComposedTaskRunner how often it should check the status its child tasks.

max-wait-time
The maximum amount of time in millis that a individual step can run before the execution of the Composed task is failed (Integer, default: 0).
Determines the maximum time each child task is allowed to run before the CTR will terminate with a failure. The default of 0 indicates no timeout.

split-thread-allow-core-thread-timeout
Specifies whether to allow split core threads to timeout. Default is false; (Boolean, default: false)
Sets the policy governing whether core threads may timeout and terminate if no tasks arrive within the keep-alive time, being replaced if needed when new tasks arrive.

split-thread-core-pool-size
Split’s core pool size. Default is 1; (Integer, default: 1)
Each child task contained in a split requires a thread in order to execute. So for example a definition like: <AAA || BBB || CCC> && <DDD || EEE> would require a split-thread-core-pool-size of 3.
This is because the largest split contains 3 child tasks. A count of 2 would mean that AAA and BBB would run in parallel but CCC would wait until either AAA or BBB to finish in order to run.
Then DDD and EEE would run in parallel.

split-thread-keep-alive-seconds
Split’s thread keep alive seconds. Default is 60. (Integer, default: 60)
If the pool currently has more than corePoolSize threads, excess threads will be terminated if they have been idle for more than the keepAliveTime.

If fewer than corePoolSize threads are running, the Executor always prefers adding a new thread rather than queuing.

If corePoolSize or more threads are running, the Executor always prefers queuing a request rather than adding a new thread.

If a request cannot be queued, a new thread is created unless this would exceed maximumPoolSize, in which case, the task will be rejected.

split-thread-wait-for-tasks-to-complete-on-shutdown
Whether to wait for scheduled tasks to complete on shutdown, not interrupting running tasks and executing all tasks in the queue. Default is false; (Boolean, default: false)

Note
when using the options above as environment variables, convert to uppercase, remove the dash character and replace with the underscore character. For example: increment-instance-enabled would be INCREMENT_INSTANCE_ENABLED.

In the preceding example, we assume that the applications to be used by our composed task have not been registered yet.
Consequently, in the first two steps, we register two task applications.
We then create our composed task definition by using the task create command.
The composed task DSL in the preceding example, when launched, runs mytaskapp and then runs the timestamp application.

But before we launch the my-composed-task definition, we can view what Spring Cloud Data Flow generated for us.
This can be done by executing the task list command, as shown (including its output) in the following example:

In the example, Spring Cloud Data Flow created three task definitions, one for each of the applications that makes up our composed task (my-composed-task-mytaskapp and my-composed-task-timestamp) as well as the composed task (my-composed-task) definition.
We also see that each of the generated names for the child tasks is made up of the name of the composed task and the name of the application, separated by a dash - (as in my-composed-task-mytaskapp).

Task Application Parameters

The task applications that make up the composed task definition can also contain parameters, as shown in the following example:

In the preceding example, we see that my-compose-task launched and that it also launched the other tasks in sequential order.
All of them executed successfully with Exit Code as 0.

Passing properties to the child tasks

To set the properties for child tasks in a composed task graph at task launch time,
you would use the following format of app.<composed task definition name>.<child task app name>.<property>.
Using the following Composed Task definition as an example:

Similar to application properties, the deployer properties can also be set for child tasks using the format format of deployer.<composed task definition name>.<child task app name>.<deployer-property>.

Exit Statuses

The following list shows how the Exit Status is set for each step (task) contained in the composed task following each step execution:

If the TaskExecution has an ExitMessage, that is used as the ExitStatus.

If no ExitMessage is present and the ExitCode is set to zero, then the ExitStatus for the step is COMPLETED.

If no ExitMessage is present and the ExitCode is set to any non-zero number, the ExitStatus for the step is FAILED.

51.2.3. Destroying a Composed Task

The command used to destroy a stand-alone task is the same as the command used to destroy a composed task.
The only difference is that destroying a composed task also destroys the child tasks associated with it.
The following example shows the task list before and after using the destroy command:

51.2.4. Stopping a Composed Task

In cases where a composed task execution needs to be stopped, you can do so through the:

RESTful API

Spring Cloud Data Flow Dashboard

To stop a composed task through the dashboard, select the Jobs tab and click the Stop button next to the job execution that you want to stop.

The composed task run is stopped when the currently running child task completes.
The step associated with the child task that was running at the time that the composed task was stopped is marked as STOPPED as well as the composed task job execution.

51.2.5. Restarting a Composed Task

In cases where a composed task fails during execution and the status of the composed task is FAILED, the task can be restarted.
You can do so through the:

RESTful API

The shell

Spring Cloud Data Flow Dashboard

To restart a composed task through the shell, launch the task with the same parameters.
To restart a composed task through the dashboard, select the Jobs tab and click the Restart button next to the job execution that you want to restart.

Restarting a Composed Task job that has been stopped (through the Spring Cloud Data Flow Dashboard or RESTful API) relaunches the STOPPED child task and then launches the remaining (unlaunched) child tasks in the specified order.

52. Composed Tasks DSL

52.1. Conditional Execution

Conditional execution is expressed by using a double ampersand symbol (&&).
This lets each task in the sequence be launched only if the previous task
successfully completed, as shown in the following example:

task create my-composed-task --definition "task1 && task2"

When the composed task called my-composed-task is launched, it launches the task called task1 and, if it completes successfully, then the task called task2 is launched.
If task1 fails, then task2 does not launch.

You can also use the Spring Cloud Data Flow Dashboard to create your conditional execution, by using the designer to drag and drop applications that are required and connecting them together to create your directed graph, as shown in the following image:

Figure 5. Conditional Execution

The preceding diagram is a screen capture of the directed graph as it being created by using the Spring Cloud Data Flow Dashboard.
You can see that are four components in the diagram that comprise a conditional execution:

Start icon: All directed graphs start from this symbol.
There is only one.

You can view a diagram of your directed graph by clicking the Detail button next to the composed task definition on the Definitions tab.

52.2. Transitional Execution

The DSL supports fine- grained control over the transitions taken during the execution of the directed graph.
Transitions are specified by providing a condition for equality based on the exit status of the previous task.
A task transition is represented by the following symbol ->.

52.2.1. Basic Transition

In the preceding example, foo would launch, and, if it had an exit status of FAILED, the bar task would launch.
If the exit status of foo was COMPLETED, baz would launch.
All other statuses returned by foo have no effect, and the task would terminate normally.

Using the Spring Cloud Data Flow Dashboard to create the same " basic transition " would resemble the following image:

Figure 6. Basic Transition

The preceding diagram is a screen capture of the directed graph as it being created in the Spring Cloud Data Flow Dashboard.
Notice that there are two different types of connectors:

Dashed line: Represents transitions from the application to one of the possible destination applications.

Solid line: Connects applications in a conditional execution or a connection between the application and a control node (start or end).

To create a transitional connector:

When creating a transition, link the application to each possible destination by using the connector.

Once complete, go to each connection and select it by clicking it.

A bolt icon appears.

Click that icon.

Enter the exit status required for that connector.

The solid line for that connector turns to a dashed line.

52.2.2. Transition With a Wildcard

Wildcards are supported for transitions by the DSL, as shown in the following:

In the preceding example, foo would launch, and, if it had an exit status of FAILED, the bar task would launch.
If foo had an exit status of UNKNOWN, baz would launch.
For any exit status of foo other than FAILED or UNKNOWN, qux would launch and, upon successful completion, quux would launch.

Using the Spring Cloud Data Flow Dashboard to create the same “transition with conditional execution” would resemble the following image:

Figure 8. Transition With Conditional Execution

In this diagram we see the dashed line (transition) connecting the foo application to the target applications, but a solid line connecting the conditional executions between foo, qux, and quux.

52.3. Split Execution

Splits allow multiple tasks within a composed task to be run in parallel.
It is denoted by using angle brackets (<>) to group tasks and flows that are to be run in parallel.
These tasks and flows are separated by the double pipe || symbol, as shown in the following example:

In the preceding example, tasks foo, bar, and baz are launched in parallel.
Once they all complete, then tasks qux and quux are launched in parallel.
Once they complete, the composed task ends.
However, if foo, bar, or baz fails, the split containing qux and quux does not launch.

Using the Spring Cloud Data Flow Dashboard to create the same “split with multiple groups” would resemble the following image:

Figure 10. Split as a part of a conditional execution

Notice that there is a SYNC control node that is inserted by the designer when
connecting two consecutive splits.

52.3.1. Split Containing Conditional Execution

A split can also have a conditional execution within the angle brackets, as shown in the following example:

task create my-split-task --definition "<foo && bar || baz>"

In the preceding example, we see that foo and baz are launched in parallel.
However, bar does not launch until foo completes successfully.

Using the Spring Cloud Data Flow Dashboard to create the same " split containing conditional execution " resembles the following image:

Figure 11. Split with conditional execution

52.3.2. Establishing the proper thread count for splits

Each child task contained in a split requires a thread in order to execute. To set this properly you want to look at your graph and count the split that has the largest number of child tasks, this will be the number of threads you will need to utilize.
To set the thread count use the split-thread-core-pool-size property (defaults to 1). So for example a definition like: <AAA || BBB || CCC> && <DDD || EEE> would require a split-thread-core-pool-size of 3.
This is because the largest split contains 3 child tasks. A count of 2 would mean that AAA and BBB would run in parallel but CCC would wait until either AAA or BBB to finish in order to run.
Then DDD and EEE would run in parallel.

53. Launching Tasks from a Stream

You can launch a task from a stream by using one of the available task-launcher sinks. Currently the platforms supported by the task-launcher sinks are:

A task-launcher sink expects a message containing a TaskLaunchRequest object in its payload.
From the TaskLaunchRequest object, the task-launcher obtains the URI of the artifact to be launched, as well as the environment properties, command line arguments, deployment properties, and application name to be used by the task.

The task-launcher-local can be added to the available sinks by executing the app register command, as follows (for the Rabbit Binder, in this case):

In the case of a Maven-based task that is to be launched, the task-launcher application is responsible for downloading the artifact.
You must configure the task-launcher with the appropriate configuration of Maven Properties, such as --maven.remote-repositories.repo1.url=http://repo.spring.io/libs-milestone" to resolve artifacts (in this case against a milestone repo). Note that this repostory can be different than the one used to register the task-launcher application itself.

53.1. TriggerTask

One way to launch a task with the task-launcher is to use the triggertask source.
The triggertask source emits a message with a TaskLaunchRequest object that contains the required launch information.
The triggertask can be added to the available sources by running the app register command, as follows (for the Rabbit Binder, in this case):

If you run runtime apps, you can find the log file for the task launcher sink.
By using the tail command on that file, you can find the log file for the launched tasks.
Setting of triggertask.environment-properties establishes the Data Flow Server’s H2 Database as the database where the task executions will be recorded.
You can then see the list of task executions by using the shell command task execution list, as shown (with its output) in the following example:

53.3. Launching a Composed Task From a Stream

A composed task can be launched with one of the task-launcher sinks as discussed here.
Since we use the ComposedTaskRunner directly, we need to set up the task definitions it uses prior to the creation of the composed task launching stream.
Suppose we wanted to create the following composed task definition: AAA && BBB.
The first step would be to create the task definitions, as shown in the following example:

In the preceding example, we see that the tasklaunchrequest-transform is establishing two primary components:

uri: The URI of the ComposedTaskRunner that is used

command-line-arguments: To configure the ComposedTaskRunner

For now, we focus on the configuration that is required to launch the ComposedTaskRunner:

graph: this is the graph that is to be executed by the ComposedTaskRunner.
In this case it is AAA&&BBB.

increment-instance-enabled: This lets each execution of ComposedTaskRunner be unique.
ComposedTaskRunner is built by using Spring Batch.
Thus, we want a new Job Instance for each launch of the ComposedTaskRunner.
To do this, we set increment-instance-enabled to be true.

spring.datasource.*: The datasource that is used by Spring Cloud
Data Flow, which lets the user track the tasks launched by the
ComposedTaskRunner and the state of the job execution.
Also, this is so that the ComposedTaskRunner can track the state of the tasks it launched and update its state.

54. Sharing Spring Cloud Data Flow’s Datastore with Tasks

As discussed in the Tasks documentation Spring
Cloud Data Flow allows a user to view Spring Cloud Task App executions. So in
this section we will discuss what is required by a Task Application and Spring
Cloud Data Flow to share the task execution information.

54.1. A Common DataStore Dependency

Spring Cloud Data Flow supports many database types out-of-the-box,
so all the user typically has to do is declare the spring_datasource_* environment variables
to establish what data store Spring Cloud Data Flow will need.
So whatever database you decide to use for Spring Cloud Data Flow make sure that the your task also
includes that database dependency in its pom.xml or gradle.build file. If the database dependency
that is used by Spring Cloud Data Flow is not present in the Task Application, the task will fail
and the task execution will not be recorded.

54.2. A Common Data Store

Spring Cloud Data Flow and your task application must access the same datastore instance.
This is so that the task executions recorded by the task application can be read by Spring Cloud Data Flow to list them in the Shell and Dashboard views.
Also the task app must have read & write privileges to the task data tables that are used by Spring Cloud Data Flow.

Given the understanding of Datasource dependency between Task apps and Spring Cloud Data Flow, let’s review how to apply them in various Task orchestration scenarios.

54.2.1. Simple Task Launch

When launching a task from Spring Cloud Data Flow, Data Flow adds its datasource
properties (spring.datasource.url, spring.datasource.driverClassName, spring.datasource.username, spring.datasource.password)
to the app properties of the task being launched. Thus a task application
will record its task execution information to the Spring Cloud Data Flow repository.

54.2.2. Task Launcher Sink

The Task Launcher Sink allows tasks to be launched via a stream as discussed here.
Since tasks launched by the Task Launcher Sink may not want their task executions
recorded to the same datastore as Spring Cloud Data Flow,
each TaskLaunchRequest
received by the Task Launcher Sink must have the required datasource information established as app properties or command line arguments.
Both TaskLaunchRequest-Transform
and TriggerTask Source are examples
of how a source and a processor allow a user to set the datasource properties via the app properties or command line arguments.

54.2.3. Composed Task Runner

Spring Cloud Data Flow allows a user to create a directed graph where each node
of the graph is a task application and this is done via the
Composed Task Runner.
In this case the rules that applied to a Simple Task Launch
or Task Launcher Sink apply to the composed task runner as well.
All child apps must also have access to the datastore that is being used by the composed task runner
Also, All child apps must have the same database dependency as the composed task runner enumerated in their pom.xml or gradle.build file.

54.2.4. Launching a task externally from Spring Cloud Data Flow

Users may wish to launch Spring Cloud Task applications via another method (scheduler for example) but still track the task execution via Spring Cloud Data Flow.
This can be done so long as the task applications observe the rules specified here and here.

If a user wishes to use Spring Cloud Data Flow to view their
Spring Batch jobs, the user must make sure that
their batch application use the @EnableTask annotation and follow the rules enumerated here and here.
More information is available here.

55. Scheduling Tasks

Spring Cloud Data Flow lets a user schedule the execution of tasks via a cron expression.
A schedule can be created through the RESTful API or the Spring Cloud Data Flow UI.

55.1. The Scheduler

Spring Cloud Data Flow will schedule the execution of its tasks via a scheduling agent that is available on the cloud platform.
For example: on the Cloud Foundry platform Spring Cloud Data Flow will use the PCF Scheduler.

Figure 12. Architectural Overview

55.2. Enabling Scheduling

By default the Spring Cloud Data Flow leaves the scheduling feature disabled. To enable the scheduling feature the following feature properties must be set to true:

55.3. The Lifecycle of a Schedule

55.3.1. Scheduling a Task Execution

You can schedule a task execution via the:

RESTful API

Spring Cloud Data Flow Dashboard

To schedule a task from the UI click the Tasks tab at the top of the screen, this will take you to the Task Definitions screen. Then from the Task Definition that you wish to schedule click the "clock" icon associated with task definition you wish to schedule.
This will lead you to a Create Schedule(s) screen, where you will create a unique name for the schedule and enter the associated cron expression.
Keep in mind you can always create multiple schedules for a single task definition.

55.3.2. Deleting a Schedule

You can delete a schedule via the:

RESTful API

Spring Cloud Data Flow Dashboard

To delete a schedule through the dashboard, select the Schedule tab under Tasks tab and click the garbage can icon next to the schedule you wish to delete.

Any currently running tasks that were run by the scheduling agent will not be stopped if the schedule is deleted. It only prevents future executions.

Tasks on Cloud Foundry

56. Version Compatibility

The task functionality depends on the latest versions of PCF for runtime support. This
release requires PCF version 1.7.12 or higher to run tasks. Tasks are an experimental
feature in PCF 1.7 and 1.8 and a GA feature in PCF 1.9.

57. Running Task Applications

Running a task application within Spring Cloud Data Flow goes through a slightly different
lifecycle than running a stream application. Both types of applications need to be registered
with the appropriate artifact coordinates. Both need a definition created with the SCDF DSL.
However, the similarities end there.

With stream-based applications, you “deploy” them with the intent that they run until they
are undeployed. A stream definition is only deployed once (it can be scaled, but only
deployed as one instance of the stream as a whole). However, tasks are “launched”. A single
task definition can be launched many times. With each launch, the task starts, runs,
and shuts down, with PCF cleaning up the resources once the shutdown has occurred. The
following sections outline the process of creating, launching, destroying, and viewing tasks.

57.1. Creating a Task

Similar to streams, creating a task application is done by using the SCDF DSL or through the
dashboard. To create a task definition in SCDF, you must either develop a task
application or use one of the out-of-the-box task app-starters.
The maven coordinates of the task application should be registered in SCDF. For more
details on how to register task applications, see Registering a Task Application
in the core docs.

The following example uses the out-of-the-box timestamp task application:

You can pass in additional properties meant for a TaskLauncher itself by using a --properties option.
The format of this option is a comma-separated string of properties prefixed with app.<task definition name>.<property>.
Properties are passed to TaskLauncher as application properties.
It is up to an implementation to choose how those are passed into an actual task application.
If the property is prefixed with deployer instead of app, it is passed to TaskLauncher as a deployment property and its meaning may be specific to the TaskLauncher implementation. The following example shows how to pass in application properties:

You can also set the JAVA_OPTS values as the global property for all the tasks by using
SPRING_CLOUD_DEPLOYER_CLOUDFOUNDRY_TASK_JAVA_OPTS

57.4. Viewing Task Logs

The CF CLI is the way to interact with tasks on PCF,
including viewing the logs. In order to view the logs as a task is executing, you can use the
following command, where mytask is the name of the task you are executing:

57.7. Destroying a Task

Destroying the task application from SCDF removes the task definition from the task repository. The following listing (which includes output) shows how to destroy a task named mytask and verify that it has been removed from the task list:

57.8. Deleting a Task From Cloud Foundry

Currently, Spring Cloud Data Flow does not delete tasks deployed on a Cloud
Foundry instance once they have been pushed. The only way to do this now is through the
CLI on a Cloud Foundry instance, version 1.9 or above.
This is done in two steps:

Obtain a list of the apps by using the cf apps command.

Identify the task application to be deleted and run the cf delete <task-name>
command.

The task destroy <task-name> deletes only the definition and not the task
deployed on Cloud Foundry.

Dashboard

This section describes how to use the dashboard of Spring Cloud Data Flow.

58. Introduction

Spring Cloud Data Flow provides a browser-based GUI called the dashboard to manage the following information:

Apps: The Apps tab lists all available applications and provides the controls to register/unregister them.

Runtime: The Runtime tab provides the list of all running applications.

For example, if Spring Cloud Data Flow is running locally, the dashboard is available at http://localhost:9393/dashboard.

If you have enabled https, then the dashboard will be located at https://localhost:9393/dashboard.
If you have enabled security, a login form is available at http://localhost:9393/dashboard/#/login.

The default Dashboard server port is 9393.

The following image shows the opening page of the Spring Cloud Data Flow dashboard:

Figure 13. The Spring Cloud Data Flow Dashboard

59. Apps

The Apps section of the dashboard lists all the available applications and provides the controls to register and unregister them (if applicable).
It is possible to import a number of applications at once by using the Bulk Import Applications action.

The following image shows a typical list of available apps within the dashboard:

Figure 14. List of Available Applications

59.1. Bulk Import of Applications

The Bulk Import Applications page provides numerous options for defining and importing a set of applications all at once.
For bulk import, the application definitions are expected to be expressed in a properties style, as follows:

At the top of the bulk import page, a URI can be specified that points to a properties file stored elsewhere, it should contain properties formatted as shown in the previous example.
Alternatively, by using the textbox labeled “Apps as Properties”, you can directly list each property string. Finally, if the properties are stored in a local file, the “Select Properties File” option opens a local file browser to select the file.
After setting your definitions through one of these routes, click Import.

The following image shows the Bulk Import Applications page:

Figure 15. Bulk Import Applications

60. Runtime

The Runtime section of the Dashboard application shows the list of all running applications.
For each runtime app, the state of the deployment and the number of deployed instances is shown.
A list of the used deployment properties is available by clicking on the App Id.

The following image shows an example of the Runtime tab in use:

Figure 16. List of Running Applications

61. Streams

The Streams tab has two child tabs: Definitions and Create Stream. The following topics describe how to work with each one:

61.1. Working with Stream Definitions

The Streams section of the Dashboard includes the Definitions tab that provides a listing of Stream definitions.
There you have the option to deploy or undeploy those stream definitions.
Additionally, you can remove the definition by clicking on Destroy.
Each row includes an arrow on the left, which you can click to see a visual representation of the definition.
Hovering over the boxes in the visual representation shows more details about the apps, including any options passed to them.

In the following screenshot, the timer stream has been expanded to show the visual representation:

Figure 17. List of Stream Definitions

If you click the details button, the view changes to show a visual representation of that stream and any related streams.
In the preceding example, if you click details for the timer stream, the view changes to the following view, which clearly shows the relationship between the three streams (two of them are tapping into the timer stream):

Figure 18. Stream Details Page

61.2. Creating a Stream

The Streams section of the Dashboard includes the Create Stream tab, which makes available the Spring Flo designer: a canvas application that offers an interactive graphical interface for creating data pipelines.

In this tab, you can:

Create, manage, and visualize stream pipelines using DSL, a graphical canvas, or both

Write pipelines via DSL with content-assist and auto-complete

Use auto-adjustment and grid-layout capabilities in the GUI for simpler and interactive organization of pipelines

You should watch this screencast that highlights some of the "Flo for Spring Cloud Data Flow" capabilities.
The Spring Flo wiki includes more detailed content on core Flo capabilities.

The following image shows the Flo designer in use:

Figure 19. Flo for Spring Cloud Data Flow

61.3. Deploying a Stream

The stream deploy page includes tabs that provide different ways to setup the deployment properties and deploy the stream.
The following screenshots show the stream deploy page for foobar (time | log).

You can define deployments properties using:

Form builder tab: a builder which help you to define deployment properties (deployer, application properties…​)

Free text tab: a free textarea (key/value pairs)

You can switch between the both views, the form builder provides a more stronger validation of the inputs.

Figure 20. The following image shows the form builder

Figure 21. The following image shows the same properties in the free text

61.4. Creating Fan-In/Fan-Out Streams

In chapter Fan-in and Fan-out you learned how we can support fan-in and fan-out use cases using named destinations.
The UI provides dedicated support for named destinations as well:

Figure 22. Flo for Spring Cloud Data Flow

In this example we have data from an HTTP Source and a JDBC Source that is being sent to the
sharedData channel which represents a Fan-in use case.
On the other end we have a Cassandra Sink and a File Sink subscribed to the sharedData channel which represents a Fan-out use case.

61.5. Creating a Tap Stream

Creating Taps using the Dashboard is straightforward.
Let’s say you have stream consisting of an HTTP Source and a File Sink and you would like to tap into the stream
to also send data to a JDBC Sink.
In order to create the tap stream simply connect the output connector of the HTTP Source to the JDBC Sink.
The connection will be displayed as a dotted line, indicating that you created a tap stream.

Figure 23. Creating a Tap Stream

The primary stream (HTTP Source to File Sink) will be automatically named, in case you did not provide a name for the stream, yet.
When creating tap streams, the primary stream must always be explicitly named.
In the picture above, the primary stream was named HTTP_INGEST.

Using the Dashboard, you can also switch the primary stream to become the secondary tap stream.

Figure 24. Change Primary Stream to Secondary Tap Stream

Simply hover over the existing primary stream, the line between HTTP Source and File Sink.
Several control icons will appear, and by clicking on the icon labeled Switch to/from tap,
you change the primary stream into a tap stream.
Do the same for the tap stream and switch it to a primary stream.

Figure 25. End Result of Switching the Primary Stream

When interacting directly with named destinations,
there can be "n" combinations (Inputs/Outputs). This allows you to create complex topologies involving a
wide variety of data sources and destinations.

62. Tasks

62.1. Apps

Each app encapsulates a unit of work into a reusable component.
Within the Data Flow runtime environment, apps let users create definitions for streams as well as tasks.
Consequently, the Apps tab within the Tasks section lets users create task definitions.

You can also use this tab to create Batch Jobs.

The following image shows a typical list of task apps:

Figure 26. List of Task Apps

On this screen, you can perform the following actions:

View details, such as the task app options.

Create a task definition from the respective app.

62.1.1. View Task App Details

On this page you can view the details of a selected task app, including the list of available options (properties) for that app.

62.1.2. Create a Task Definition

At a minimum, you must provide a name for the new definition.
You also have the option to specify various properties that are used during the deployment of the app.

Each parameter is included only if the Include checkbox is selected.

62.2. Definitions

This page lists the Data Flow task definitions and provides actions to launch or destroy those tasks.
It also provides a shortcut operation to define one or more tasks with simple textual input, indicated by
the Bulk Define Tasks button.

The following image shows the Definitions page:

Figure 27. List of Task Definitions

62.2.1. Creating Composed Task Definitions

The dashboard includes the Create Composed Task tab, which provides an interactive graphical interface for creating composed tasks.

In this tab, you can:

Create and visualize composed tasks using DSL, a graphical canvas, or both.

Use auto-adjustment and grid-layout capabilities in the GUI for simpler and interactive organization of the composed task.

On the Create Composed Task screen, you can define one or more task parameters by entering both the parameter key and the parameter value.

Task parameters are not typed.

The following image shows the composed task designer:

Figure 28. Composed Task Designer

62.2.2. Launching Tasks

Once the task definition has been created, the tasks can be launched through the dashboard.
To do so, click the Definitions tab and select the task you want to launch by pressing Launch.

62.3. Executions

The Executions tab shows the current running and completed tasks.

The following image shows the Executions tab:

Figure 29. List of Task Executions

62.4. Execution Detail

For each task execution on the Executions page, a user can retrieve detailed information about a specific execution by clicking the information icon located to the right of the task execution.

On this screen the user can view not only the information from the Task Executions page but also:

Job Execution Ids links (Clicking the Job Execution Id will take you to the Job Execution Details for that Job Execution Id.)

Task Execution Duration

Task Execution Exit Message

63. Jobs

The Jobs section of the Dashboard lets you inspect batch jobs.
The main section of the screen provides a list of job executions.
Batch jobs are tasks that each execute one or more batch jobs.
Each job execution has a reference to the task execution ID (in the Task Id column).

The list of Job Executions also shows the state of the underlying Job Definition.
Thus, if the underlying definition has been deleted, “No definition found” appears in the Status column.

You can take the following actions for each job:

Restart (for failed jobs).

Stop (for running jobs).

View execution details.

Note: Clicking the stop button actually sends a stop request to the running job, which may not immediately stop.

The following image shows the Jobs page:

Figure 30. List of Job Executions

63.1. Job Execution Details

After having launched a batch job, the Job Execution Details page will show information about the job.

The following image shows the Job Execution Details page:

Figure 31. Job Execution Details

The Job Execution Details page contains a list of the executed steps.
You can further drill into the details of each step’s execution by clicking the magnifying glass icon.

63.2. Step Execution Details

The Step Execution Details page provides information about an individual step within a job.

The following image shows the Step Execution Details page:

Figure 32. Step Execution Details

On the top of the page, you can see a progress indicator the respective step, with the option to refresh the indicator.
A link is provided to view the step execution history.

For exceptions, the Exit Description field contains additional error information.
However, this field can have a maximum of 2500 characters.
Therefore, in the case of long exception stack traces, trimming of error messages may occur.
When that happens, refer to the server log files for further details.

63.3. Step Execution Progress

On this screen, you can see a progress bar indicator in regards to the execution
of the current step. Under the Step Execution History, you can also view various
metrics associated with the selected step, such as duration, read counts, write
counts, and others.

64. Scheduling

64.1. Creating or deleting a Schedule from the Task Definition’s page

From the Task Definitions page a user can create or delete a schedule for a specific task definition.

Figure 33. Task Definitions with Schedule controls

On this screen you can perform the following actions:

The user can click the clock icon and this will take you to the Schedule Creation screen.

The user can click the clock icon with the x to the upper right to delete the schedule(s) associated with the task definition.

64.2. Creating a Schedule

Figure 34. Create Schedule for Task Execution

Once the user clicks the clock icon on the Task Definition screen, Spring Cloud Data Flow will take the user to the Schedule Creation screen.
On this screen a user can establish the schedule name, the cron expression as well as establish the properties and arguments to be used when the task is launched by this schedule.

64.3. Listing Available Schedules

Figure 35. List Available Schedules

On this screen you can perform the following actions:

Delete a schedule

Get details for a schedule

65. Analytics

The Analytics page of the Dashboard provides the following data visualization capabilities for the various analytics applications available in Spring Cloud Data Flow:

Counters

Field-Value Counters

Aggregate Counters

For example, if you create a stream with a Counter application, you can create the corresponding graph from within the Dashboard tab.
To do so:

Under Metric Type, select Counters from the select box.

Under Stream, select tweetcount.

Under Visualization, select the desired chart option, Bar Chart.

Using the icons to the right, you can add additional charts to the Dashboard, re-arange the order of created dashboards, or remove data visualizations.

66. Auditing

The Auditing page of the Dashboard gives you access to recorded audit events. Currently audit event
are recorded for:

Streams

Create

Delete

Deploy

Undeploy

Tasks

Create

Delete

Launch

Scheduling of Tasks

Create Schedule

Delete Schedule

Figure 36. List Overview of Audit Records

By clicking on the Show Details icon, you can obtain further details regarding
the auditing details:

Figure 37. List Details of an Audit Record

Generally, auditing provides the following information:

When was the record created?

Username that triggered the audit event (if security is enabled)

Audit operation (Schedule, Stresm, Task)

Performed action (Create, Delete, Deploy, Rollback, Undeploy, Update)

Correlation Id, e.g. Stream/Task name

Audit Data

The written value of the property Audit Data depends on the performed Audit Operation and the ActionType.
For example, when a Schedule is being created, the name of the task definition,
task definition properties, deployment properties, as well as command line arguments are written
to the persistence store.

Sensitive information is sanitized prior to saving the Audit Record, in an best-effort-manner.
Any of the following keys are being detected and its sensitive values are
masked:

Appendix A: Data Flow Template

As described in the previous chapter, Spring Cloud Data Flow’s functionality is completely exposed through REST endpoints.
While you can use those endpoints directly, Spring Cloud Data Flow also provides a Java-based API, which makes using those REST endpoints even easier.

The central entry point is the DataFlowTemplate class in the org.springframework.cloud.dataflow.rest.client package.

This class implements the DataFlowOperations interface and delegates to the following sub-templates that provide the specific functionality for each feature-set:

Interface

Description

StreamOperations

REST client for stream operations

CounterOperations

REST client for counter operations

FieldValueCounterOperations

REST client for field value counter operations

AggregateCounterOperations

REST client for aggregate counter operations

TaskOperations

REST client for task operations

JobOperations

REST client for job operations

AppRegistryOperations

REST client for app registry operations

CompletionOperations

REST client for completion operations

RuntimeOperations

REST Client for runtime operations

When the DataFlowTemplate is being initialized, the sub-templates can be discovered through the REST relations, which are provided by HATEOAS.[1]

If a resource cannot be resolved, the respective sub-template results
in NULL. A common cause is that Spring Cloud Data Flow offers for specific
sets of features to be enabled/disabled when launching. For more information, see “Feature Toggles”.

A.1. Using the Data Flow Template

When you use the Data Flow Template, the only needed Data Flow dependency is the
Spring Cloud Data Flow Rest Client, as shown in the following Maven snippet:

With that dependency, you get the DataFlowTemplate class as well as all the dependencies needed to make calls to a Spring Cloud Data Flow server.

When instantiating the DataFlowTemplate, you also pass in a RestTemplate.
Please be aware that the needed RestTemplate requires some additional configuration to be valid in the context of the DataFlowTemplate.
When declaring a RestTemplate as a bean, the following configuration suffices:

Appendix B: Spring XD to SCDF

This appendix describes how to migrate from Spring XD to Spring Cloud Data Flow, along with some tips and tricks that may be helpful.

B.1. Terminology Changes

The following table describes the changes in terminology from Spring XD to Spring Cloud Data Flow:

Old

New

XD-Admin

Server (implementations: local, Cloud Foundry, and Kubernetes)

XD-Container

N/A

Modules

Applications

Admin UI

Dashboard

Message Bus

Binders

Batch / Job

Task

B.2. Modules to Applications

If you have custom Spring XD modules, you need refactor them to use Spring Cloud Stream and Spring Cloud Task annotations.
As part of that work, you need to update dependencies and build them as normal Spring Boot applications.

B.2.1. Custom Applications

As you convert custom applications, keep the following information in mind:

Spring XD’s stream and batch modules are refactored into the Spring Cloud Stream and Spring Cloud Task application-starters, respectively.
These applications can be used as the reference while refactoring Spring XD modules.

Alternatively, if you want to patch any of the out-of-the-box stream applications, you can follow the procedure described here.

B.2.2. Application Registration

As you register your applications, keep the following information in mind:

Custom Stream/Task applications can be registered as Spring Boot uber-jar for Cloud Foundry or local implementations. They can also be registerd as a docker image for Local, Cloud Foundry, or Kuberenetes implementations. Other than Maven and docker resolution, you can also resolve application artifacts from http(s) and file coordinates.

Unlike Spring XD, you do not have to upload the application bits while registering custom applications anymore.
Instead, you need to register the application coordinates that are hosted in the Maven repository or by other means as discussed in the previous bullet.

By default, none of the out-of-the-box applications are preloaded. It is intentionally designed to provide the flexibility to register apps as you find appropriate for the given use-case requirement.

Depending on the binder choice, you can manually add the appropriate binder dependency to build applications specific to that binder-type.
Alternatively, you can follow the Spring Initializrprocedure to create an application with binder embedded in it.

B.2.3. Application Properties

As you modify your applications' properties, keep the following information in mind:

Counter-sink:

The peripheral redis is not required in Spring Cloud Data Flow.
If you intend to use the counter-sink, then redis is required, and you need to have your own running redis cluster.

field-value-counter-sink:

The peripheral redis is not required in Spring Cloud Data Flow.
If you intend to use the field-value-counter-sink, then redis becomes required, and you need to have your own running redis cluster.

Aggregate-counter-sink:

The peripheral redis is not required in Spring Cloud Data Flow.
If you intend to use the aggregate-counter-sink, then redis becomes required, and you need to have your own running redis cluster.

B.3. Message Bus to Binders

B.3.1. Message Bus

Similar to Spring XD, Spring Cloud Data Flow includes an abstraction that you can use to extend the binder interface.
By default, we take the opinionated view of Apache Kafka and RabbitMQ as the production-ready binders.
They are available as GA releases.

B.3.2. Binders

Selecting a binder requires providing the right binder dependency in the classpath.
If you choose Kafka as the binder, you need to register stream applications that are pre-built with Kafka binder in it.
If you to create a custom application with Kafka binder, you need add the following dependency in the classpath:

Spring Cloud Stream supports Apache Kafka and RabbitMQ.
All binder implementations are maintained and managed in their individual repositories.

Every Stream/Task application can be built with the binder implementation of your choice.
All the out-of-the-box applications are pre-built for both Kafka and Rabbit and are readily available for use as Maven artifacts (Spring Cloud Stream or Spring Cloud Task) or as Docker images (Spring Cloud Stream or Spring Cloud Task).
Changing the binder requires selecting the right binder dependency.
Alternatively, you can download the pre-built application from this version of Spring Initializr with the desired “binder-starter” dependency.

B.3.3. Named Channels

Fundamentally, all the messaging channels are backed by pub/sub semantics.
Unlike Spring XD, the messaging channels are backed only by topics or topic-exchange and there is no representation of queues in the new architecture.

${xd.module.index} is no longer supported. Instead, you can directly interact with named destinations.

stream.index changes to :<stream-name>.<label/app-name>

For example, ticktock.0 changes to :ticktock.time.

“topic/queue” prefixes are not required to interact with named-channels.

For example, topic:mytopic changes to :mytopic.

For example, stream create stream1 --definition ":foo > log".

B.3.4. Directed Graphs

If you build non-linear streams, you can take advantage of named destinations to build directed graphs.

B.4. Batch to Tasks

A Task, by definition, is any application that does not run forever, and they end at some point.
Tasks include Spring Batch jobs.
Task applications can be used for on-demand use cases, such as database migration, machine learning, scheduled operations, and others.
With Spring Cloud Task, you can build Spring Batch jobs as microservice applications.

Spring Batch jobs from Spring XD are being refactored to Spring Boot applications, also known as Spring Cloud Task applications.

Unlike Spring XD, these tasks do not require explicit deployment. Instead, a task is ready to be launched directly once the definition is declared.

B.5. Shell and DSL Command Changes

The following table shows the changes to shell and DSL commands:

Old Command

New Command

module upload

app register / app import

module list

app list

module info

app info

admin config server

dataflow config server

job create

task create

job launch

task launch

job list

task list

job status

task status

job display

task display

job destroy

task destroy

job execution list

task execution list

runtime modules

runtime apps

B.6. REST API Changes

The following table shows the changes to the REST API:

Old API

New API

/modules

/apps

/runtime/modules

/runtime/apps

/runtime/modules/{moduleId}

/runtime/apps/{appId}

/jobs/definitions

/task/definitions

/jobs/deployments

/task/deployments

B.7. UI (including Flo)

Apps (a new view): Lists all the registered applications that are available for use.
This view includes details such as the URI and the properties supported by each application.
You can also register/unregister applications from this view.

Runtime (was Container): Container changes to Runtime. The notion of xd-container is gone, replaced by out-of-the-box applications running as autonomous Spring Boot applications.
The Runtime tab displays the applications running in the runtime platforms (implementations: Local, Cloud Foundry, or Kubernetes). You can click on each application to review relevant details, such
as where it is running, what resources it uses, and other details.

Spring Flo is now an OSS product. Flo for
Spring Cloud Data Flow’s “Create Stream” is now the designer-tab in the Dashboard.

Tasks (a new view):

The “Modules” sub-tab is renamed to “Apps”.

The “Definitions” sub-tab lists all the task definitions, including Spring Batch jobs that are orchestrated as tasks.

The “Executions” sub-tab lists all the task execution details in a fashion similar to the listing of Spring XD’s Job executions.

B.8.1. ZooKeeper

B.8.2. RDBMS

Spring Cloud Data Flow uses an RDBMS instead of Redis for stream/task definitions, application registration, and for job repositories.
The default configuration uses an embedded H2 instance, but Oracle, DB2, SqlServer, MySQL/MariaDB, PostgreSQL, H2, and HSQLDB databases are supported.
To use Oracle, DB2, and SqlServer, you need to create your own Data Flow Server by using Spring Initializr and add the appropriate JDBC driver dependency.

B.8.3. Redis

Running a Redis cluster is only required for analytics functionality.
Specifically, when you use the counter-sink, field-value-counter-sink, or aggregate-counter-sink applications, you also need to have a running instance of Redis cluster.

B.8.4. Cluster Topology

Spring XD’s xd-admin and xd-container server components are replaced by stream and task applications that are themselves running as autonomous Spring Boot applications.
The applications run natively on various platforms, including Cloud Foundry and Kubernetes.
You can develop, test, deploy, scale up or down, and interact with (Spring Boot) applications individually, and they can evolve in isolation.

B.9. Central Configuration

To support centralized and consistent management of an application’s configuration properties, Spring Cloud Config client libraries have been included in the Spring Cloud Data Flow server as well as the Spring Cloud Stream applications provided by the Spring Cloud Stream App Starters. You can also pass common application properties to all streams when the Data Flow Server starts.

B.10. Distribution

Spring Cloud Data Flow is a Spring Boot application. Depending on the platform of your choice, you can download the respective release uber jar and deploy or push it to the runtime platform (Cloud Foundry or Kubernetes). For example, if you run Spring Cloud Data Flow on Cloud Foundry, you can download the Cloud Foundry server implementation and do a cf push, as explained in the Cloud Foundry Reference Guide.

B.11. Hadoop Distribution Compatibility

The hdfs-sink application builds upon Spring Hadoop 2.4.0 release, so this application is compatible
with the following Hadoop distributions:

Cloudera: cdh5

Pivotal Hadoop: phd30

Hortonworks Hadoop: hdp24

Hortonworks Hadoop: hdp23

Vanilla Hadoop: hadoop26

Vanilla Hadoop: 2.7.x (default)

B.12. Use Case Comparison

The remainder of this appendix reviews some use cases to show the differences between Spring XD and Spring Cloud Data Flow.

B.12.1. Use Case #1: Ticktock

This use case assumes that you have already downloaded both the XD and the SCDF distributions.

Review results in the xd-singlenode server console as well as the Jobs tab in the UI
(executions sub-tab should include all step details)

Review results by using the tail command to view the batchtest/stdout_log application logs as well as the Task tab in UI (the executions sub-tab should include all step details)

Appendix C: Building

To build the source, you need to install JDK 1.8.

The build uses the Maven wrapper so that you do not have to install a specific version of Maven.
To enable the tests for Redis, run the server before building.
More information on how to run Redis appears later in this appendix.

The main build command is as follows:

$ ./mvnw clean install

If you like, you can add '-DskipTests' to avoid running the tests.

You can also install Maven (>=3.3.3) yourself and run the mvn command in place of ./mvnw in the examples below.
If you do that, you also might need to add -P spring if your local Maven settings do not contain repository declarations for Spring pre-release artifacts.

You might need to increase the amount of memory available to Maven by setting a MAVEN_OPTS environment variable with a value similar to -Xmx512m -XX:MaxPermSize=128m.
We try to cover this in the .mvn configuration, so, if you find you have to do it to make a build succeed, please raise a ticket to get the settings added to source control.

C.1. Documentation

There is a full profile that generates documentation. You can build only the documentation by using the following command:

C.2. Working with the Code

If you do not have an IDE preference, we recommend that you use Spring Tools Suite or Eclipse when working with the code.
We use the m2eclipse Eclipse plugin for Maven support.
Other IDEs and tools generally also work without issue.

C.2.1. Importing into Eclipse with m2eclipse

We recommend the m2eclipe eclipse plugin when working with Eclipse.
If you do not already have m2eclipse installed, it is available from the Eclipse marketplace.

Unfortunately, m2e does not yet support Maven 3.3.
Consequently, once the projects are imported into Eclipse, you also need to tell m2eclipse to use the .settings.xml file for the projects.
If you do not do this, you may see many different errors related to the POMs in the projects.
To do so:

Open your Eclipse preferences.

Expand the Maven preferences.

Select User Settings.

In the User Settings field, click Browse and navigate to the Spring Cloud project you imported.

Select the .settings.xml file in that project.

Click Apply.

Click OK.

Alternatively, you can copy the repository settings from Spring Cloud’s .settings.xml file into your own ~/.m2/settings.xml.

C.2.2. Importing into Eclipse without m2eclipse

If you prefer not to use m2eclipse, you can generate Eclipse project metadata by using the following command:

$ ./mvnw eclipse:eclipse

The generated Eclipse projects can be imported by selecting Import existing projects
from the File menu.

Appendix D: Contributing

Spring Cloud is released under the non-restrictive Apache 2.0 license and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master.
If you want to contribute even something trivial, please do not hesitate, but follow the guidelines below.

D.1. Sign the Contributor License Agreement

Before we accept a non-trivial patch or pull request, we need you to sign the contributor’s agreement.
Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do.
Active contributors might be asked to join the core team and be given the ability to merge pull requests.

D.2. Code Conventions and Housekeeping

None of the following guidelines is essential for a pull request, but they all help your fellow developers understand and work with your code.
They can also be added after the original pull request but before a merge.

Use the Spring Framework code format conventions. If you use Eclipse, you can import formatter settings by using the eclipse-code-formatter.xml file from the Spring Cloud Build project.
If using IntelliJ, you can use the Eclipse Code Formatter Plugin to import the same file.

Make sure all new .java files have a simple Javadoc class comment with at least an @author tag identifying you, and preferably at least a paragraph describing the class’s purpose.

Add the ASF license header comment to all new .java files (to do so, copy from existing files in the project).

Add yourself as an @author to the .java files that you modify substantially (more than cosmetic changes).

Add some Javadocs and, if you change the namespace, some XSD doc elements.

A few unit tests would help a lot as well. Someone has to do it, and your fellow developers appreciate the effort.

If no one else uses your branch, rebase it against the current master (or other target branch in the main project).

When writing a commit message, follow these conventions.
If you fix an existing issue, add Fixes gh-XXXX (where XXXX is the issue number) at the end of the commit message.