Sync docs from master to gh-pages

multi/multi__serverless_platform_adapters.html

@@ -46,7 +46,15 @@ You can write an app with a single <code class="literal">@Bean</code> of type <c
 			ExecutionContext context) {
 		<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> handleRequest(foo, context);
 	}
-}</pre><p>This Azure handler will delegate to a <code class="literal">Function&lt;Foo,Bar&gt;</code> bean (or a <code class="literal">Function&lt;Publisher&lt;Foo&gt;,Publisher&lt;Bar&gt;&gt;</code>). Some Azure triggers (e.g. <code class="literal">@CosmosDBTrigger</code>) result in a input type of <code class="literal">List</code> and in that case you can bind to <code class="literal">List</code> in the Azure handler, or <code class="literal">String</code> (the raw JSON). The <code class="literal">List</code> input delegates to a <code class="literal">Function</code> with input type <code class="literal">Map&lt;String,Object&gt;</code>, or <code class="literal">Publisher</code> or <code class="literal">List</code> of the same type. The output of the <code class="literal">Function</code> can be a <code class="literal">List</code> (one-for-one) or a single value (aggregation), and the output binding in the Azure declaration should match.</p><p>If your app has more than one <code class="literal">@Bean</code> of type <code class="literal">Function</code> etc. then you can choose the one to use by configuring <code class="literal">function.name</code>. Or if you make the <code class="literal">@FunctionName</code> in the Azure handler method match the function name it should work that way (also for function apps with multiple functions). The functions are extracted from the Spring Cloud <code class="literal">FunctionCatalog</code> so the default function names are the same as the bean names.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_notes_on_jar_layout_2" href="#_notes_on_jar_layout_2"></a>10.2.1&nbsp;Notes on JAR Layout</h3></div></div></div><p>You don&#8217;t need the Spring Cloud Function Web at runtime in Azure, so you can exclude this before you create the JAR you deploy to Azure, but it won&#8217;t be used if you include it so it doesn&#8217;t hurt to leave it in. A function application on Azure is an archive generated by the Maven plugin. The function lives in the JAR file generated by this project. The sample creates it as an executable jar, using the thin layout, so that Azure can find the handler classes. If you prefer you can just use a regular flat JAR file. The dependencies should <span class="strong"><strong>not</strong></span> be included.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_build" href="#_build"></a>10.2.2&nbsp;Build</h3></div></div></div><pre class="screen">./mvnw -U clean package</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_running_the_sample" href="#_running_the_sample"></a>10.2.3&nbsp;Running the sample</h3></div></div></div><p>You can run the sample locally, just like the other Spring Cloud Function samples:</p><p></p><p></p><p>and <code class="literal">curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'</code>.</p><p>You will need the <code class="literal">az</code> CLI app (see <a class="link" href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven" target="_top">https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven</a> for more detail). To deploy the function on Azure runtime:</p><pre class="screen">$ az login
+}</pre><p>This Azure handler will delegate to a <code class="literal">Function&lt;Foo,Bar&gt;</code> bean (or a <code class="literal">Function&lt;Publisher&lt;Foo&gt;,Publisher&lt;Bar&gt;&gt;</code>). Some Azure triggers (e.g. <code class="literal">@CosmosDBTrigger</code>) result in a input type of <code class="literal">List</code> and in that case you can bind to <code class="literal">List</code> in the Azure handler, or <code class="literal">String</code> (the raw JSON). The <code class="literal">List</code> input delegates to a <code class="literal">Function</code> with input type <code class="literal">Map&lt;String,Object&gt;</code>, or <code class="literal">Publisher</code> or <code class="literal">List</code> of the same type. The output of the <code class="literal">Function</code> can be a <code class="literal">List</code> (one-for-one) or a single value (aggregation), and the output binding in the Azure declaration should match.</p><p>If your app has more than one <code class="literal">@Bean</code> of type <code class="literal">Function</code> etc. then you can choose the one to use by configuring <code class="literal">function.name</code>. Or if you make the <code class="literal">@FunctionName</code> in the Azure handler method match the function name it should work that way (also for function apps with multiple functions). The functions are extracted from the Spring Cloud <code class="literal">FunctionCatalog</code> so the default function names are the same as the bean names.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_accessing_azure_executioncontext" href="#_accessing_azure_executioncontext"></a>10.2.1&nbsp;Accessing Azure ExecutionContext</h3></div></div></div><p>Some time there is a need to access the target execution context provided by Azure runtime in the form of <code class="literal">com.microsoft.azure.functions.ExecutionContext</code>.
+For example one of such needs is logging, so it can appear in the Azure console.</p><p>For that purpose Spring Cloud Function will register <code class="literal">ExecutionContext</code> as bean in the Application context, so it could be injected into your function.
+For example</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
+<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Function&lt;Foo, Bar&gt; uppercase(ExecutionContext targetContext) {
+	<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> foo -&gt; {
+		targetContext.getLogger().info(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Invoking 'uppercase' on "</span> + foo.getValue());
+		<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Bar(foo.getValue().toUpperCase());
+	};
+}</pre><p>Normally type-based injection should suffice, however if need to you can also utilise the bean name under which it is registered which is <code class="literal">targetExecutionContext</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_notes_on_jar_layout_2" href="#_notes_on_jar_layout_2"></a>10.2.2&nbsp;Notes on JAR Layout</h3></div></div></div><p>You don&#8217;t need the Spring Cloud Function Web at runtime in Azure, so you can exclude this before you create the JAR you deploy to Azure, but it won&#8217;t be used if you include it so it doesn&#8217;t hurt to leave it in. A function application on Azure is an archive generated by the Maven plugin. The function lives in the JAR file generated by this project. The sample creates it as an executable jar, using the thin layout, so that Azure can find the handler classes. If you prefer you can just use a regular flat JAR file. The dependencies should <span class="strong"><strong>not</strong></span> be included.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_build" href="#_build"></a>10.2.3&nbsp;Build</h3></div></div></div><pre class="screen">./mvnw -U clean package</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_running_the_sample" href="#_running_the_sample"></a>10.2.4&nbsp;Running the sample</h3></div></div></div><p>You can run the sample locally, just like the other Spring Cloud Function samples:</p><p></p><p></p><p>and <code class="literal">curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'</code>.</p><p>You will need the <code class="literal">az</code> CLI app (see <a class="link" href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven" target="_top">https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven</a> for more detail). To deploy the function on Azure runtime:</p><pre class="screen">$ az login
 $ mvn azure-functions:deploy</pre><p>On another terminal try this: <code class="literal">curl <a class="link" href="https://<azure-function-url-from-the-log&gt;/api/uppercase" target="_top">https://&lt;azure-function-url-from-the-log&gt;/api/uppercase</a> -d '{"value": "hello foobar!"}'</code>. Please ensure that you use the right URL for the function above. Alternatively you can test the function in the Azure Dashboard UI (click on the function name, go to the right hand side and click "Test" and to the bottom right, "Run").</p><p>The input type for the function in the Azure sample is a Foo with a single property called "value". So you need this to test it with something like below:</p><pre class="screen">{
   "value": "foobar"
 }</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The Azure sample app is written in the "non-functional" style (using <code class="literal">@Bean</code>). The functional style (with just <code class="literal">Function</code> or <code class="literal">ApplicationContextInitializer</code>) is much faster on startup in Azure than the traditional <code class="literal">@Bean</code> style, so if you don&#8217;t need <code class="literal">@Beans</code> (or <code class="literal">@EnableAutoConfiguration</code>) it&#8217;s a good choice. Warm starts are not affected.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_apache_openwhisk" href="#_apache_openwhisk"></a>10.3&nbsp;Apache Openwhisk</h2></div></div></div><p>The <a class="link" href="https://openwhisk.apache.org/" target="_top">OpenWhisk</a> adapter is in the form of an executable jar that can be used in a a docker image to be deployed to Openwhisk. The platform works in request-response mode, listening on port 8080 on a specific endpoint, so the adapter is a simple Spring MVC application.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_quick_start" href="#_quick_start"></a>10.3.1&nbsp;Quick Start</h3></div></div></div><p>Implement a POF (be sure to use the <code class="literal">functions</code> package):</p><pre class="screen">package functions;

spring-cloud-function.xml

@@ -632,6 +632,21 @@ You can write an app with a single <literal>@Bean</literal> of type <literal>Fun
 }</programlisting>
 <simpara>This Azure handler will delegate to a <literal>Function&lt;Foo,Bar&gt;</literal> bean (or a <literal>Function&lt;Publisher&lt;Foo&gt;,Publisher&lt;Bar&gt;&gt;</literal>). Some Azure triggers (e.g. <literal>@CosmosDBTrigger</literal>) result in a input type of <literal>List</literal> and in that case you can bind to <literal>List</literal> in the Azure handler, or <literal>String</literal> (the raw JSON). The <literal>List</literal> input delegates to a <literal>Function</literal> with input type <literal>Map&lt;String,Object&gt;</literal>, or <literal>Publisher</literal> or <literal>List</literal> of the same type. The output of the <literal>Function</literal> can be a <literal>List</literal> (one-for-one) or a single value (aggregation), and the output binding in the Azure declaration should match.</simpara>
 <simpara>If your app has more than one <literal>@Bean</literal> of type <literal>Function</literal> etc. then you can choose the one to use by configuring <literal>function.name</literal>. Or if you make the <literal>@FunctionName</literal> in the Azure handler method match the function name it should work that way (also for function apps with multiple functions). The functions are extracted from the Spring Cloud <literal>FunctionCatalog</literal> so the default function names are the same as the bean names.</simpara>
+<section xml:id="_accessing_azure_executioncontext">
+<title>Accessing Azure ExecutionContext</title>
+<simpara>Some time there is a need to access the target execution context provided by Azure runtime in the form of <literal>com.microsoft.azure.functions.ExecutionContext</literal>.
+For example one of such needs is logging, so it can appear in the Azure console.</simpara>
+<simpara>For that purpose Spring Cloud Function will register <literal>ExecutionContext</literal> as bean in the Application context, so it could be injected into your function.
+For example</simpara>
+<programlisting language="java" linenumbering="unnumbered">@Bean
+public Function&lt;Foo, Bar&gt; uppercase(ExecutionContext targetContext) {
+	return foo -&gt; {
+		targetContext.getLogger().info("Invoking 'uppercase' on " + foo.getValue());
+		return new Bar(foo.getValue().toUpperCase());
+	};
+}</programlisting>
+<simpara>Normally type-based injection should suffice, however if need to you can also utilise the bean name under which it is registered which is <literal>targetExecutionContext</literal>.</simpara>
+</section>
 <section xml:id="_notes_on_jar_layout_2">
 <title>Notes on JAR Layout</title>
 <simpara>You don&#8217;t need the Spring Cloud Function Web at runtime in Azure, so you can exclude this before you create the JAR you deploy to Azure, but it won&#8217;t be used if you include it so it doesn&#8217;t hurt to leave it in. A function application on Azure is an archive generated by the Maven plugin. The function lives in the JAR file generated by this project. The sample creates it as an executable jar, using the thin layout, so that Azure can find the handler classes. If you prefer you can just use a regular flat JAR file. The dependencies should <emphasis role="strong">not</emphasis> be included.</simpara>