The Spring Cloud Data Flow reference guide is available as html, pdf and epub documents. The latest copy is available at docs.spring.io/spring-cloud-dataflow/docs/current-SNAPSHOT/reference/html/.

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.

Having trouble with Spring Cloud Data Flow, We’d like to help!

	Note
	All of Spring Cloud Data Flow is open source, including the documentation! If you find problems with the docs; or if you just want to improve them, please get involved.

A cloud native programming and operating model for composable data microservices on a structured platform. With Spring Cloud Data Flow, developers can create, orchestrate and refactor data pipelines through single programming model for common use cases such as data ingest, real-time analytics, and data import/export.

Spring Cloud Data Flow is the cloud native redesign of Spring XD – a project that aimed to simplify development of Big Data applications. The integration and batch modules from Spring XD are refactored into Spring Boot data microservices applications that are now autonomous deployment units – thus enabling them to take full advantage of platform capabilities "natively", and they can independently evolve in isolation.

Spring Cloud Data Flow defines best practices for distributed stream and batch microservice design patterns.

The architecture for Spring Cloud Data Flow is separated into a number of distinct components.

You need Java installed (Java 7 or better, we recommend Java 8), and to build, you need to have Maven installed as well.

You also need to have Redis installed and running if you plan on running a local system, or to run the included tests.

In Spring Cloud Data Flow, a basic stream defines the ingestion of event driven data from a source to a sink that passes through any number of processors. Streams are composed of spring-cloud-stream modules and the deployment of stream definitions is done via the Data Flow Server (REST API). The Getting Started section shows you how to start these servers and how to start and use the Spring Cloud Data Flow shell.

A high level DSL is used to create stream definitions. The DSL to define a stream that has an http source and a file sink (with no processors) is shown below

http | file

The DSL mimics a UNIX pipes and filters syntax. Default values for ports and filenames are used in this example but can be overridden using -- options, such as

http --port=8091 | file --dir=/tmp/httpdata/

To create these stream definitions you make an HTTP POST request to the Spring Cloud Data Flow Server. More details can be found in the sections below.

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 via the Spring Cloud Data Flow shell. Start the shell as described in the Getting Started section.

New streams are created by posting stream definitions. The definitions are built from a simple DSL. For example, let’s walk through what happens if we execute the following shell command:

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

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

Then to deploy the stream execute the following shell command (or alternatively add the --deploy flag when creating the stream so that this step is not needed):

dataflow:> stream deploy --name ticktock

The Admin Server resolves time and log to maven coordinates and uses those to launch the time and log applications of the stream. In this simple example, the time source simply sends the current time as a message each second, and the log sink outputs it using the logging framework.

2016-01-13 10:41:15.398  INFO 65275 --- [nio-9393-exec-1] o.s.c.d.a.s.l.OutOfProcessModuleDeployer : deploying module org.springframework.cloud.stream.module:log-sink:jar:exec:1.0.0.BUILD-SNAPSHOT instance 0
   Logs will be in /var/folders/hs/h87zy7z17qs6mcnl4hj8_dp00000gp/T/spring-cloud-data-flow-3652850284472151116/ticktock.log
2016-01-13 10:41:15.433  INFO 65275 --- [nio-9393-exec-1] o.s.c.d.a.s.l.OutOfProcessModuleDeployer : deploying module org.springframework.cloud.stream.module:time-source:jar:exec:1.0.0.BUILD-SNAPSHOT instance 0
   Logs will be in /var/folders/hs/h87zy7z17qs6mcnl4hj8_dp00000gp/T/spring-cloud-data-flow-3652850284472151116/ticktock.time

If you would like to have multiple instances of a module in the stream, you can include a property with the deploy command:

dataflow:> stream deploy --name ticktock --properties "module.time.count=3"

	Important
	See Chapter 15, Module Labels.

You can delete a stream by issuing the stream destroy command from the shell:

dataflow:> stream destroy --name ticktock

Often you will want to stop a stream, but retain the name and definition for future use. In that case you can undeploy the stream by name and issue the deploy command at a later time to restart it.

dataflow:> stream undeploy --name ticktock
dataflow:> stream deploy --name ticktock

Let’s try something a bit more complicated and swap 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 above to

dataflow:> stream create --definition "http | log" --name myhttpstream --deploy

which will produce the following output from the server

2016-01-13 18:42:19.162  INFO 19463 --- [nio-9393-exec-7] o.s.c.d.a.s.l.OutOfProcessModuleDeployer : deploying module org.springframework.cloud.stream.module:log-sink:jar:exec:1.0.0.BUILD-SNAPSHOT instance 0
   Logs will be in /var/folders/hs/h87zy7z17qs6mcnl4hj8_dp00000gp/T/spring-cloud-data-flow-2185888994718649403/myhttpstream.log
2016-01-13 18:42:19.180  INFO 19463 --- [nio-9393-exec-7] o.s.c.d.a.s.l.OutOfProcessModuleDeployer : deploying module org.springframework.cloud.stream.module:http-source:jar:exec:1.0.0.BUILD-SNAPSHOT instance 0
   Logs will be in /var/folders/hs/h87zy7z17qs6mcnl4hj8_dp00000gp/T/spring-cloud-data-flow-2185888994718649403/myhttpstream.http

Note that we don’t see anydefin other output this time until we actually post some data (using shell command). In order to see the randomly assigned port on which the http source is listening, execute:

dataflow:> runtime modules

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, e.g.:

dataflow:> http post --target http://localhost:1234 --data "hello"
dataflow:> http post --target http://localhost:1234 --data "goodbye"

and the stream will then funnel the data from the http source to the output log implemented by the log sink

2016-01-13 21:15:34.825  INFO 54348 --- [hannel-adapter1] log.sink                                 : hello
2016-01-13 21:17:36.544  INFO 54348 --- [hannel-adapter1] log.sink                                 : goodbye

Of course, 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 modules which are provided. You can also define your own modules.

As an example of a simple processing step, we can transform the payload of the HTTP posted data to upper case using the stream definitions

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

To create this stream enter the following command in the shell

dataflow:> stream create --definition "http | transform --expression=payload.toUpperCase() | log" --name mystream --deploy

Posting some data (using shell command)

dataflow:> http post --target http://localhost:1234 --data "hello"

Will result in an uppercased 'hello' in the log

15:18:21,345  WARN ThreadPoolTaskScheduler-1 logger.myprocstream:141 - HELLO

See the Processors section for more information.

In the examples above, we connected a source to a sink using the pipe symbol |. You can also pass parameters to the source and sink configurations. The parameter names will depend on the individual module implementations, but as an example, the http source module exposes a server.port setting which allows you to change the data ingestion port from the default value. To create the stream using port 8000, we would use

dataflow:> stream create --definition "http --server.port=8000 | log" --name myhttpstream

The shell provides tab completion for module parameters and also the shell command module info provides some additional documentation. For more comprehensive documentation on module parameters, please see the Modules chapter.

13.1 Register a Stream App

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

dataflow:>module register --name mysource --type source --uri maven://com.example:mysource:0.0.1-SNAPSHOT

dataflow:>module register --name myprocessor --type processor --uri file:///Users/example/myprocessor-1.2.3.jar

dataflow:>module register --name mysink --type sink --uri http://example.com/mysink-2.0.1.jar

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, this would be a valid properties file:

source.foo=file:///tmp/foo.jar
sink.bar=file:///tmp/bar.jar

Then use the module import command and provide the location of the properties file via --uri:

module import --uri file:///tmp/stream-apps.properties

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 module register or module import, if a stream app is already registered with the provided name and type, it will not be overridden by default. If you would like to override the pre-existing stream app, then include the --force option.

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

If directed graphs are needed instead of the simple linear streams described above, two features are relevant. First, named destinations may be used as a way to combine the output from multiple streams or for multiple consumers to share the output from a single stream. This can be done using the DSL syntax http > mydestination or mydestination > log. To learn more, refer to then section on Named Destinations. Second, you may need to determine the output channel of a stream based on some information that is only known at runtime. To learn about such content-based routing, refer to the Dynamic Router section.

When a stream is comprised of multiple modules 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

Taps can be created at various producer endpoints in a stream. For a stream like this:

stream create --definition "http | step1: transform --expression=payload.toUpperCase() | step2: transform --expression=payload+'!' | log" --name mainstream --deploy

taps can be created at the output of http, step1 and step2.

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

`<stream-name>.<label/app-name>`

To create a tap at the output of http in the stream above, 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

The tap stream DSL looks like this:

stream create --definition ":mainstream.http > counter" --name tap_at_http --deploy

stream create --definition ":mainstream.step1 > jdbc" --name tap_at_step1_transformer --deploy

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

One can connect to a specific destination name located in the broker (Rabbit, Kafka etc.,) either at the source or at the sink position.

The following stream has the destination name at the source position:

stream create --definition ":myDestination > log" --name ingest_from_broker --deploy

This stream receives messages from the destination myDestination located at the broker and connects it to the log app.

The following stream has the destination name at the sink position:

stream create --definition "http > :myDestination" --name ingest_to_broker --deploy

This stream sends the messages from http app to the destination myDestination located at the broker.

From the above streams, notice that the http and log apps are interacting with each other via broker (through the destination myDestination) rather than having a pipe directly between http and log within a single stream.

It is also possible to connect two different destinations (source and sink positions) at the broker in a stream.

stream create --definition ":destination1 > :destination2" --name bridge_destinations --deploy

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

A task executes a process on demand. In this case a task is a Spring Boot application that is annotated with @EnableTask. Hence a user launches a task that performs a certain process, and once complete the task ends. An example of a task would be a 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.

Before we dive deeper into the details of creating Tasks, we need to understand the typical lifecycle for tasks in the context of Spring Cloud Data Flow:

19.1 Register a Task App

Register a Task App with the App Registry using the Spring Cloud Data Flow Shell module register command. You must provide a unique name and a URI that can be resolved to the app artifact. For the type, specify "task". Here are a few examples:

dataflow:>module register --name task1 --type task --uri maven://com.example:mytask:1.0.2

dataflow:>module register --name task2 --type task --uri file:///Users/example/mytask-1.0.2.jar

dataflow:>module register --name task3 --type task --uri http://example.com/mytask-1.0.2.jar

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, this would be a valid properties file:

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

Then use the module import command and provide the location of the properties file via --uri:

module import --uri file:///tmp/task-apps.properties

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 module register or module import, if a task app is already registered with the provided name, it will not be overridden by default. If you would like to override the pre-existing task app, then include the --force option.

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

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

dataflow:>task launch mytask
 Launched task 'mytask'

dataflow:>task destroy mytask
 Destroyed task 'mytask'

Out of the box Spring Cloud Dataflow offers an embedded instance of the H2 database. The H2 is good for development purposes but is not recommended for production use.

<dependencies>
...
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
    </dependency>
...
</dependencies>

export spring_datasource_url=jdbc:postgresql://localhost:5432/mydb
export spring_datasource_username=myuser
export spring_datasource_password=mypass
export spring_datasource_driver-class-name="org.postgresql.Driver"

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: myuser
    password: mypass
    driver-class-name:org.postgresql.Driver

Spring Cloud Data Flow provides a browser-based GUI which currently has 6 sections:

Upon starting Spring Cloud Data Flow, the Dashboard is available at:

http://<adminHost>:<adminPort>/admin-ui

For example: http://localhost:9393/admin-ui

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

Note: The default Dashboard server port is 9393

Figure 21.1. The Spring Cloud Data Flow Dashboard

The Apps section of the Dashboard lists all the available applications and provides the control to register/unregister them (if applicable). By clicking on the magnifying glass, you will get a listing of available definition properties.

Figure 22.1. List of Available Applications

The Runtime section of the Dashboard application shows the Spring Cloud Data Flow cluster view with the list of all running applications. For each runtime module 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 module id.

Figure 23.1. List of Running Applications

The Streams section of the Dashboard provides 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.

Figure 24.1. List of Stream Definitions

The Tasks section of the Dashboard currently has three tabs:

25.1 Modules

Modules encapsulate a unit of work into a reusable component. Within the Dataflow runtime environment Modules allow users to create definitions for Streams as well as Tasks. Consequently, the Modules tab within the Tasks section allows users to create Task definitions.

Note: You will also use this tab to create Batch Jobs.

Figure 25.1. List of Task Modules

On this screen you can perform the following actions:

• View details such as the task module options.
• Create a Task Definition from the respective Module.

25.1.1 Create a Task Definition from a selected Job Module

On this screen you can create a new Task Definition. As a minimum you must provide a name for the new definition. You will also have the option to specify various parameters that are used during the deployment of the definition.

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

25.1.2 View Task Module Details

On this page you can view the details of a selected task module. The pages lists the available options (properties) of the modules.

25.2 Definitions

This page lists the Dataflow Task definitions and provides actions to launch or destroy those tasks.

Figure 25.2. List of Task Definitions

25.2.1 Launching Tasks

Once the task definition is created, they can be launched through the Dashboard as well. Navigate to the Definitions tab. Select the Task you want to launch by pressing Launch.

On the following screen, you can define one or more Task parameters by entering:

• Parameter Key
• Parameter Value

Task parameters are not typed.

25.3 Executions

Figure 25.3. List of Task Executions

The Jobs section of the Dashboard allows you to inspect Batch Jobs. The main section of the screen provides a list of Job Executions. Batch Jobs are Tasks that were executing one or more Batch Job. As such each Job Execution has a back reference to the Task Execution Id (Task Id).

In case of a failed job, you can also restart the task. When dealing with long-running Batch Jobs, you can also request to stop it.

Figure 26.1. List of Job Executions

26.1 List job executions

This page lists the Batch Job Executions and provides the option to restart or stop a specific job execution, provided the operation is available. Furthermore, you have the option to view the Job execution details.

The list of Job Executions also shows the state of the underlying Job Definition. Thus, if the underlying definition has been deleted, deleted will be shown.

26.1.1 Job execution details

Figure 26.2. Job Execution Details

The Job Execution Details screen also contains a list of the executed steps. You can further drill into the Step Execution Details by clicking onto the magnifying glass.

26.1.2 Step execution details

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

The Step Execution details screen provides a complete list of all Step Execution Context key/value pairs.

	Important
	In case of exceptions, the Exit Description field will contain additional error information. Please be aware, though, that this field can only have a maximum of 2500 characters. Therefore, in case of long exception stacktraces, trimming of error messages may occur. In that case, please refer to the server log files for further details.

26.1.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 etc.

Figure 26.3. Step Execution History

The Analytics section of the Dashboard provided data visualization capabilities for the various analytics modules available in Spring Cloud Data Flow:

For example, if you have created the springtweets stream and the corresponding counter in the Counter chapter, you can now easily create the corresponding graph from within the Dashboard tab:

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.