Add HTTP Streaming example

README.adoc

@@ -27,7 +27,7 @@ readme's instructions.
 === Examples
 
 // examples: START
-Number of Examples: 62 (0 deprecated)
+Number of Examples: 63 (0 deprecated)
 
 [width="100%",cols="4,2,4",options="header"]
 |===
@@ -96,7 +96,6 @@ Number of Examples: 62 (0 deprecated)
 | link:fhir/readme.adoc[Fhir] (fhir) | Health Care | An example showing how to work with Camel, FHIR and Spring Boot
 
 | link:fhir-auth-tx/readme.adoc[Fhir Auth Tx] (fhir-auth-tx) | Health Care | An example showing how to work with Camel, FHIR Authorization, FHIR Transaction and Spring Boot
-
 
 | link:validator/readme.adoc[Validator Spring Boot] (validator) | Input/Output Type Contract | An example showing how to work with declarative validation and Spring Boot
 
@@ -112,7 +111,6 @@ Number of Examples: 62 (0 deprecated)
 | link:metrics/README.adoc[Metrics] (metrics) | Management and Monitoring | An example showing how to work with Camel and Spring Boot and report metrics to Graphite
 
 | link:observation/README.adoc[Micrometer Observation] (observation) | Management and Monitoring | An example showing how to trace incoming and outgoing messages from Camel with Micrometer Observation
-
 
 | link:opentelemetry/README.adoc[OpenTelemetry] (opentelemetry) | Management and Monitoring | An example showing how to use Camel with OpenTelemetry
 
@@ -139,14 +137,15 @@ Number of Examples: 62 (0 deprecated)
 | link:widget-gadget/README.adoc[Widget Gadget] (widget-gadget) | Messaging | The widget and gadget example from EIP book, running on Spring Boot
 
 | link:reactive-streams/readme.adoc[Reactive Streams] (reactive-streams) | Reactive | An example that shows how Camel can exchange data using reactive streams with Spring Boot reactor
-
 
 | link:http-ssl/README.adoc[Http Ssl] (http-ssl) | Rest | An example showing the Camel HTTP component with Spring Boot and SSL
 
 | link:openapi-contract-first/readme.adoc[Openapi Contract First] (openapi-contract-first) | Rest | Contract First OpenAPI example
 
 | link:platform-http/README.adoc[Platform Http] (platform-http) | Rest | An example showing Camel REST DSL with platform HTTP
 
+| link:http-streaming/README.adoc[Http Streaming] (http-streaming) | Rest | This example shows how to stream large files using platform HTTP component
+
 | link:rest-cxf/README.adoc[Rest Cxf] (rest-cxf) | Rest | An example showing Camel REST using CXF with Spring Boot
 
 | link:rest-openapi/README.adoc[Rest Openapi] (rest-openapi) | Rest | An example showing Camel REST DSL and OpenApi with Spring Boot

http-streaming/README.adoc

@@ -0,0 +1,62 @@
+== Camel Spring Boot Example: HTTP Large File Streaming
+
+
+=== Introduction
+
+This project contains logic to handle large HTTP data streams in download, upload, and proxy scenarios. The aim is to show Camel's ability to process streams without exhausting JVM memory.
+
+=== Use cases
+
+[NOTE]
+====
+Streaming mode opens up many interesting use cases, for example, data transformation on very large data structures, applying selective/discarding rules, split/merging of data, multiplexing data streams, and others.
+====
+
+This example only covers the basics of enabling streaming mode. The two implemented scenarios using Camel in streaming mode are:
+
+- HTTP data downloads
+- HTTP data uploads
+
+Camel may act as the end system responsible to locally/remotely store the data stream. Or it may also act as a proxy system, passing the responsibility downstream.
+
+The critical data handling happens in the numbered 1) and 2) positions illustrated below.
+
+=== Download scenario
+
+image::docs/images/uc-download.png[]
+
+=== Upload scenario
+
+image::docs/images/uc-upload.png[]
+
+
+=== How to run
+
+To demonstrate Camel can handle larger data streams than memory allocated to the JVM, we need to start it with low memory settings.
+
+To run it follow the commands below:
+
+Follow these steps to run the example:
+
+1. Decide which scenario you want to run: `download` or `upload`.
+
+2. Navigate to the corresponding folder and run both the backend and proxy servers with low memory settings (make sure ports 8080 and 9000 are available):
+
+    mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xms200m -Xmx200m"
+
+3. From the `client` directory, send a request using a large data stream.
+(See detailed instructions in `client/Readme.adoc`.)
+
+4. Stop Camel Spring Boot and inspect the result file.
+
+  Camel Spring Boot should process the HTTP byte stream and dump it in a file in the 'client' directory.
+
+=== Help and contributions
+
+If you hit any problem using Camel or have some feedback, then please
+https://camel.apache.org/community/support/[let us know].
+
+We also love contributors, so
+https://camel.apache.org/community/contributing/[get involved] :-)
+
+The Camel riders!

http-streaming/download/backend-server/pom.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>org.apache.camel.springboot.example</groupId>
+		<artifactId>camel-example-spring-boot-http-streaming</artifactId>
+		<version>4.14.0-SNAPSHOT</version>
+		<relativePath>../../pom.xml</relativePath>
+	</parent>
+
+	<artifactId>camel-example-spring-boot-http-streaming-download-server</artifactId>
+	<name>Camel SB Examples :: HTTP Streaming :: Spring Boot server</name>
+	<description>Backend Server using platform-http component</description>
+
+	<properties>
+		<category>Rest</category>
+
+		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+	</properties>
+
+	<dependencies>
+		<!-- Camel -->
+		<dependency>
+			<groupId>org.apache.camel.springboot</groupId>
+			<artifactId>camel-spring-boot-starter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.apache.camel.springboot</groupId>
+			<artifactId>camel-platform-http-starter</artifactId>
+		</dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <version>${spring-boot-version}</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>repackage</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

http-streaming/download/backend-server/src/main/java/org/apache/camel/springboot/example/http/streaming/HttpStreamingCamelServerApplication.java

@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.springboot.example.http.streaming;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class HttpStreamingCamelServerApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(HttpStreamingCamelServerApplication.class, args);
+	}
+}

http-streaming/download/backend-server/src/main/java/org/apache/camel/springboot/example/http/streaming/HttpStreamingCamelServerRouter.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.springboot.example.http.streaming;
+
+import org.apache.camel.builder.RouteBuilder;
+import org.springframework.stereotype.Component;
+
+import java.io.File;
+
+@Component
+public class HttpStreamingCamelServerRouter extends RouteBuilder {
+	@Override
+	public void configure() throws Exception {
+		restConfiguration()
+				.component("platform-http");
+		rest()
+				.get("/test")
+				.to("direct:getRequest");
+
+		from("direct:getRequest")
+				.process(exchange -> {
+					File file = new File("../client/input");
+					exchange.getMessage().setBody(file);
+				})
+				.log("responding with content.");
+	}
+}
+

http-streaming/download/backend-server/src/main/resources/application.properties

@@ -0,0 +1,21 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+camel.main.name=backend-camel-server
+
+# Backend port
+server.port=8080

http-streaming/download/client/Readme.adoc

@@ -0,0 +1,41 @@
+== Introduction
+
+This client sends a download request via HTTP (empty request). The server is expected to send back a large data stream. We want to test the server's ability to handle large data responses.
+
+
+== Prepare the response data
+
+The server will read and stream back the response data.
+In the client folder create a large file by running the following command:
+
+	dd if=/dev/zero of=input bs=4M count=1024
+
+
+The command above creates a 4 Gigabytes (input) file in the `client` directory.
+You can change the parameters `bs` and `count` to configure the data size.
+
+
+== Send a request
+
+Use `curl` to send a request:
+
+	curl -v -o ./output http://localhost:8080/test
+
+If you're using the SpringBoot proxy, use the proxy port:
+
+	curl -v -o ./output http://localhost:9000/test
+
+
+== Inspect the response
+
+If the request was successful, curl should have written the response data locally.
+Check the `output` file size equals the `input` file
+
+
+== Clean the data
+
+When you're done, make sure you perform the following actions:
+
+1) Delete the large sample data file to clean your filesystem.
+
+2) Delete the output file generated by Camel.

http-streaming/download/proxy-server/pom.xml

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>org.apache.camel.springboot.example</groupId>
+		<artifactId>camel-example-spring-boot-http-streaming</artifactId>
+		<version>4.14.0-SNAPSHOT</version>
+		<relativePath>../../pom.xml</relativePath>
+	</parent>
+
+	<artifactId>camel-example-spring-boot-http-streaming-download-proxy-server</artifactId>
+	<name>Camel SB Examples :: HTTP Streaming :: Spring Boot Proxy server</name>
+	<description>Proxy Server using platform-http component</description>
+
+	<properties>
+		<category>Rest</category>
+
+		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+	</properties>
+
+	<dependencies>
+		<!-- Camel -->
+		<dependency>
+			<groupId>org.apache.camel.springboot</groupId>
+			<artifactId>camel-spring-boot-starter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.apache.camel.springboot</groupId>
+			<artifactId>camel-platform-http-starter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.apache.camel.springboot</groupId>
+			<artifactId>camel-http-starter</artifactId>
+		</dependency>
+    </dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+				<version>${spring-boot-version}</version>
+				<executions>
+					<execution>
+						<goals>
+							<goal>repackage</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+</project>