Add docs and updates for background function support

rename fuction-sample-gcp to function-sample-gcp-http

refdoc polish

background sample polish

Resolves #525
Update pub/sub bg function to use base64 encoding

spring-cloud-function-samples/function-sample-gcp-background/README.adoc

@@ -0,0 +1,107 @@
+:branch: master
+
+=== Google Cloud Background Functions Sample Application
+
+Google Cloud Functions supports deploying https://cloud.google.com/functions/docs/writing/background[Background Functions] which are invoked indirectly in response to an event, such as a message on a https://cloud.google.com/pubsub[Pub/Sub] topic, a change in a https://cloud.google.com/storage[Cloud Storage] bucket, or a https://firebase.google.com/[Firebase] event.
+
+This sample demonstrates a simple background function which triggers from a Pub/Sub event.
+
+===== Test locally
+
+In a terminal window, run:
+
+----
+mvn function:run
+----
+
+In a separate window, invoke the background function by issuing the `curl` command below.
+
+NOTE: In this sample, we demonstrate a background function which is triggered when a message is https://cloud.google.com/functions/docs/calling/pubsub[published to a specified Cloud Pub/Sub topic].
+The `curl` request simulates sending the message that would be received by your function when a Pub/Sub event occurs.
+
+In order to simulate how Pub/Sub will send you this message, we use a base64-encoded string as the input because Pub/Sub encodes the message data in base64 in the Pub/Sub event.
+See the notes section below for a more information on the Pub/Sub event structure.
+
+----
+curl localhost:8080 -H "Content-Type: application/json" -d '{"data":"aGVsbG8="}'
+----
+
+In the original terminal window where the `mvn function:run` was invoked, you should see a message printed.
+
+----
+Received Pub/Sub message with data: hello
+----
+
+===== Deploy to GCP
+
+As of March 2020, Google Cloud Functions for Java is in Alpha.
+You can get on the https://docs.google.com/forms/d/e/1FAIpQLScC98jGi7CfG0n3UYlj7Xad8XScvZC8-BBOg7Pk3uSZx_2cdQ/viewform[whitelist] to try it out.
+
+The next steps will demonstrate how to deploy your background function to GCP and have it be invoked by a Pub/Sub event.
+
+To complete the next steps, make sure that you have the https://cloud.google.com/sdk/install[Cloud SDK CLI] installed.
+
+1. Create a new Pub/Sub topic. This topic will be used as the trigger for the background function.
++
+----
+gcloud pubsub topics create my-functions-topic
+----
+
+2. In this sample directory, package the application by running:
++
+----
+mvn package
+----
++
+You should see the JAR to deploy in the `target/deploy` directory.
+
+3. Deploy the JAR that you created by running
++
+----
+gcloud alpha functions deploy function-sample-gcp-background \
+--entry-point org.springframework.cloud.function.adapter.gcp.GcfJarLauncher \
+--runtime java11 \
+--trigger-topic my-functions-topic \
+--source target/deploy \
+--memory 512MB
+----
++
+Notice the parameter `--trigger-topic` which topic will trigger the function invocation when new messages are published to it.
+
+4. Invoke the background function by publishing a message to your topic.
++
+----
+gcloud pubsub topics publish my-functions-topic --message="Hello world"
+----
+
+5. To verify that this sample background function was invoked, check the logs of the background function on GCF by running:
++
+----
+gcloud functions logs read function-sample-gcp-background --filter=Received
+----
++
+You should see a log message that looks like below.
+It might take a minute or two for the log to appear.
++
+----
+function-sample-gcp-background-2  h8q1jt46069r  2020-05-19 19:48:27.960  Received Pub/Sub message with data: Hello world
+----
++
+This log output is produced by the sample background function, so this entry in the logs means that the background function was successfully invoked.
+
+===== Notes
+
+One important note about the Pub/Sub background function provided in `BackgroundFunctionMain` is that the `data` field must be decoded from base64 encoding because Pub/Sub will encode the published message in base64 according to the https://cloud.google.com/functions/docs/calling/pubsub#event_structure[PubSubMessage event structure].
+
+[source, java]
+----
+@Bean
+public Consumer<PubSubMessage> pubSubFunction() {
+	return message -> {
+		// The PubSubMessage data field arrives as a base-64 encoded string and must be decoded.
+		// See: https://cloud.google.com/functions/docs/calling/pubsub#event_structure
+		String decodedMessage = new String(Base64.decode(message.getData()), StandardCharsets.UTF_8);
+		System.out.println("Received Pub/Sub message with data: " + decodedMessage);
+	};
+}
+----

spring-cloud-function-samples/function-sample-gcp-background/pom.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+	<modelVersion>4.0.0</modelVersion>
+
+	<groupId>io.spring.sample</groupId>
+	<artifactId>function-sample-gcp-background</artifactId>
+	<version>2.0.0.RELEASE</version>
+	<packaging>jar</packaging>
+
+	<name>function-sample-gcp-background</name>
+
+	<parent>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starter-parent</artifactId>
+		<version>2.3.0.BUILD-SNAPSHOT</version>
+		<relativePath/> <!-- lookup parent from repository -->
+	</parent>
+
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.cloud</groupId>
+			<artifactId>spring-cloud-function-adapter-gcp</artifactId>
+			<version>3.1.0.BUILD-SNAPSHOT</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+				<configuration>
+					<outputDirectory>target/deploy</outputDirectory>
+				</configuration>
+				<dependencies>
+					<dependency>
+						<groupId>org.springframework.cloud</groupId>
+						<artifactId>spring-cloud-function-adapter-gcp</artifactId>
+						<version>3.1.0.BUILD-SNAPSHOT</version>
+					</dependency>
+				</dependencies>
+			</plugin>
+
+			<plugin>
+				<groupId>com.google.cloud.functions</groupId>
+				<artifactId>function-maven-plugin</artifactId>
+				<version>0.9.1</version>
+				<configuration>
+					<functionTarget>org.springframework.cloud.function.adapter.gcp.GcfJarLauncher</functionTarget>
+					<port>8080</port>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+</project>

spring-cloud-function-samples/function-sample-gcp-background/src/main/java/com/example/BackgroundFunctionMain.java

@@ -0,0 +1,31 @@
+package com.example;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.function.Consumer;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+
+@SpringBootApplication
+public class BackgroundFunctionMain {
+
+	public static void main(String[] args) {
+		SpringApplication.run(BackgroundFunctionMain.class, args);
+	}
+
+	/**
+	 * The background function which triggers on an event from Pub/Sub and consumes the Pub/Sub
+	 * event message.
+	 */
+	@Bean
+	public Consumer<PubSubMessage> pubSubFunction() {
+		return message -> {
+			// The PubSubMessage data field arrives as a base-64 encoded string and must be decoded.
+			// See: https://cloud.google.com/functions/docs/calling/pubsub#event_structure
+			String decodedMessage = new String(Base64.getDecoder().decode(message.getData()), StandardCharsets.UTF_8);
+			System.out.println("Received Pub/Sub message with data: " + decodedMessage);
+		};
+	}
+}

spring-cloud-function-samples/function-sample-gcp-background/src/main/java/com/example/PubSubMessage.java

@@ -0,0 +1,56 @@
+package com.example;
+
+import java.util.Map;
+
+/**
+ * A class that can be mapped to the GCF Pub/Sub Message event type. This is for use in
+ * the background functions.
+ *
+ * <p>See the PubSubMessage definition for reference:
+ * https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
+ *
+ * @author Mike Eltsufin
+ */
+public class PubSubMessage {
+
+	private String data;
+
+	private Map<String, String> attributes;
+
+	private String messageId;
+
+	private String publishTime;
+
+	public String getData() {
+		return data;
+	}
+
+	public void setData(String data) {
+		this.data = data;
+	}
+
+	public Map<String, String> getAttributes() {
+		return attributes;
+	}
+
+	public void setAttributes(Map<String, String> attributes) {
+		this.attributes = attributes;
+	}
+
+	public String getMessageId() {
+		return messageId;
+	}
+
+	public void setMessageId(String messageId) {
+		this.messageId = messageId;
+	}
+
+	public String getPublishTime() {
+		return publishTime;
+	}
+
+	public void setPublishTime(String publishTime) {
+		this.publishTime = publishTime;
+	}
+
+}

spring-cloud-function-samples/function-sample-gcp-background/src/main/resources/META-INF/MANIFEST.MF

@@ -0,0 +1 @@
+Main-Class: com.example.BackgroundFunctionMain

spring-cloud-function-samples/function-sample-gcp-http/README.adoc

@@ -34,7 +34,7 @@ Make sure that you have the https://cloud.google.com/sdk/install[Cloud SDK CLI]
 Run the following command from the project root to deploy.
 
 ----
-gcloud alpha functions deploy function-sample-gcp \
+gcloud alpha functions deploy function-sample-gcp-http \
 --entry-point org.springframework.cloud.function.adapter.gcp.GcfJarLauncher \
 --runtime java11 \
 --trigger-http \
@@ -45,5 +45,5 @@ gcloud alpha functions deploy function-sample-gcp \
 Invoke the HTTP function:
 
 ----
-curl https://REGION-PROJECT_ID.cloudfunctions.net/function-sample-gcp -d "hello"
+curl https://REGION-PROJECT_ID.cloudfunctions.net/function-sample-gcp-http -d "hello"
 ----

spring-cloud-function-samples/function-sample-gcp-http/pom.xml

@@ -6,11 +6,11 @@
 	<modelVersion>4.0.0</modelVersion>
 
 	<groupId>io.spring.sample</groupId>
-	<artifactId>function-sample-gcp</artifactId>
+	<artifactId>function-sample-gcp-http</artifactId>
 	<version>2.0.0.RELEASE</version>
 	<packaging>jar</packaging>
 
-	<name>function-sample-gcp</name>
+	<name>function-sample-gcp-http</name>
 
 	<parent>
 		<groupId>org.springframework.boot</groupId>
@@ -77,7 +77,6 @@
 				</configuration>
 			</plugin>
 		</plugins>
-
 	</build>
 
 	<repositories>

spring-cloud-function-samples/pom.xml

@@ -22,7 +22,8 @@
 		<module>function-sample-supplier-exporter</module>
 		<module>function-sample-azure</module>
 		<!--><module>function-sample-spring-integration</module>-->
-		<module>function-sample-gcp</module>
+		<module>function-sample-gcp-http</module>
+		<module>function-sample-gcp-background</module>
 	</modules>
 
 	<build>