SpringCloud/spring-cloud-function
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from master to gh-pages

Browse Source
This commit is contained in:
buildmaster
2019-05-07 08:54:25 +00:00
parent 6faa9c8abe
commit 73920be32c
8 changed files with 93 additions and 680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
aws-intro.html
View File

@@ -123,6 +123,40 @@ manifest, using the <code>Start-Class</code> attribute (which will be added for
tooling if you use the starter parent). If there is no <code>Start-Class</code> in your manifest you can
use an environment variable or system property <code>MAIN_CLASS</code> when you deploy the function to AWS.</p>
</div>
<div class="paragraph">
<p>If you are not using the functional bean definitions but relying on Spring Boot&#8217;s auto-configuration,
then additional transformers must be configured as part of the maven-shade-plugin execution.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&lt;plugin&gt;
&lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
&lt;artifactId&gt;maven-shade-plugin&lt;/artifactId&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;configuration&gt;
&lt;createDependencyReducedPom&gt;false&lt;/createDependencyReducedPom&gt;
&lt;shadedArtifactAttached&gt;true&lt;/shadedArtifactAttached&gt;
&lt;shadedClassifierName&gt;aws&lt;/shadedClassifierName&gt;
&lt;transformers&gt;
&lt;transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"&gt;
&lt;resource&gt;META-INF/spring.handlers&lt;/resource&gt;
&lt;/transformer&gt;
&lt;transformer implementation="org.springframework.boot.maven.PropertiesMergingResourceTransformer"&gt;
&lt;resource&gt;META-INF/spring.factories&lt;/resource&gt;
&lt;/transformer&gt;
&lt;transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"&gt;
&lt;resource&gt;META-INF/spring.schemas&lt;/resource&gt;
&lt;/transformer&gt;
&lt;/transformers&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">

105
aws-readme.html
View File

@@ -5,7 +5,7 @@
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.7.1">
<title>Notes on JAR Layout</title>
<title>Untitled</title>
<link rel="stylesheet" href="css/spring.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
@@ -83,20 +83,8 @@ $(addBlockSwitches);
</script>
</head>
<body class="book toc2 toc-left">
<body class="book">
<div id="header">
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_notes_on_jar_layout">Notes on JAR Layout</a></li>
<li><a href="#_upload">Upload</a></li>
<li><a href="#_type_conversion">Type Conversion</a>
<ul class="sectlevel3">
<li><a href="#_raw_input">Raw Input</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
@@ -105,94 +93,7 @@ $(addBlockSwitches);
<p>This project provides an adapter layer for a Spring Cloud Function application onto AWS Lambda. You can write an app with a single <code>@Bean</code> of type <code>Function</code>, <code>Consumer</code> or <code>Supplier</code> and it will be deployable in AWS if you get the JAR file laid out right. The best way to make it work is to include <code>spring-cloud-function-context</code> as a dependency, but not the higher level adapters (e.g. <code>spring-cloud-function-stream</code>).</p>
</div>
<div class="paragraph">
<p>The adapter has a couple of generic request handlers that you can use. The most generic is <code>SpringBootStreamHandler</code>, which uses a Jackson <code>ObjectMapper</code> provided by Spring Boot to serialize and deserialize the objects in the function. There is also a <code>SpringBootRequestHandler</code> which you can extend, and provide the input and output types as type parameters (enabling AWS to inspect the class and do the JSON conversions itself).</p>
</div>
<div class="paragraph">
<p>If your app has more than one <code>@Bean</code> of type <code>Function</code> etc. then you can choose the one to use by configuring <code>function.name</code> (e.g. as <code>FUNCTION_NAME</code> environment variable in AWS). The functions are extracted from the Spring Cloud <code>FunctionCatalog</code> (searching first for <code>Function</code> then <code>Consumer</code> and finally <code>Supplier</code>).</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_notes_on_jar_layout"><a class="link" href="#_notes_on_jar_layout">Notes on JAR Layout</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>You don&#8217;t need the Spring Cloud Function Web or Stream adapter at runtime in Lambda, so you might
need to exclude those before you create the JAR you send to AWS. A Lambda application has to be
shaded, but a Spring Boot standalone application does not, so you can run the same app using 2
separate jars (as per the sample). The sample app creates 2 jar files, one with an <code>aws</code>
classifier for deploying in Lambda, and one executable (thin) jar that includes <code>spring-cloud-function-web</code>
at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file
manifest, using the <code>Start-Class</code> attribute (which will be added for you by the Spring Boot
tooling if you use the starter parent). If there is no <code>Start-Class</code> in your manifest you can
use an environment variable or system property <code>MAIN_CLASS</code> when you deploy the function to AWS.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_upload"><a class="link" href="#_upload">Upload</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Build the sample under <code>spring-cloud-function-samples/function-sample-aws</code> and upload the <code>-aws</code> jar file to Lambda. The handler can be <code>example.Handler</code> or <code>org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler</code> (FQN of the class, <em>not</em> a method reference, although Lambda does accept method references).</p>
</div>
<div class="listingblock">
<div class="content">
<pre>./mvnw -U clean package</pre>
</div>
</div>
<div class="paragraph">
<p>Using the AWS command line tools it looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>aws lambda create-function --function-name Uppercase --role arn:aws:iam::[USERID]:role/service-role/[ROLE] --zip-file fileb://function-sample-aws/target/function-sample-aws-2.0.0.BUILD-SNAPSHOT-aws.jar --handler org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler --description "Spring Cloud Function Adapter Example" --runtime java8 --region us-east-1 --timeout 30 --memory-size 1024 --publish</pre>
</div>
</div>
<div class="paragraph">
<p>The input type for the function in the AWS sample is a Foo with a single property called "value". So you would need this to test it:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
"value": "test"
}</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The AWS sample app is written in the "functional" style (as an <code>ApplicationContextInitializer</code>). This is much faster on startup in Lambda than the traditional <code>@Bean</code> style, so if you don&#8217;t need <code>@Beans</code> (or <code>@EnableAutoConfiguration</code>) it&#8217;s a good choice. Warm starts are not affected.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_type_conversion"><a class="link" href="#_type_conversion">Type Conversion</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud Function will attempt to transparently handle type conversion between the raw
input stream and types declared by your function.</p>
</div>
<div class="paragraph">
<p>For example, if your function signature is as such <code>Function&lt;Foo, Bar&gt;</code> we will attempt to convert
incoming stream event to an instance of <code>Foo</code>.</p>
</div>
<div class="paragraph">
<p>In the event type is not known or can not be determined (e.g., <code>Function&lt;?, ?&gt;</code>) we will attempt to
convert an incoming stream event to a generic <code>Map</code>.</p>
</div>
<div class="sect3">
<h4 id="_raw_input"><a class="link" href="#_raw_input">Raw Input</a></h4>
<div class="paragraph">
<p>There are times when you may want to have access to a raw input. In this case all you need is to declare your
function signature to accept <code>InputStream</code>. For example, <code>Function&lt;InputStream, ?&gt;</code>. In this case
we will not attempt any conversion and will pass the raw input directly to a function.</p>
</div>
<p>Unresolved directive in aws-readme.adoc - include::aws-intro.adoc[]</p>
</div>
</div>
</div>

104
aws.html
View File

@@ -89,15 +89,8 @@ $(addBlockSwitches);
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_introduction">Introduction</a></li>
<li><a href="#_notes_on_jar_layout">Notes on JAR Layout</a></li>
<li><a href="#_upload">Upload</a></li>
<li><a href="#_type_conversion">Type Conversion</a>
<ul class="sectlevel3">
<li><a href="#_raw_input">Raw Input</a></li>
</ul>
</li>
<li><a href="#_functional_bean_definitions">Functional Bean Definitions</a></li>
<li><a href="#_platfom_specific_features">Platfom Specific Features</a>
<li><a href="#_platform_specific_features">Platform Specific Features</a>
<ul class="sectlevel2">
<li><a href="#_http_and_api_gateway">HTTP and API Gateway</a></li>
</ul>
@@ -113,7 +106,7 @@ $(addBlockSwitches);
<p><strong>2.1.0.BUILD-SNAPSHOT</strong></p>
</div>
<div id="index-link" class="paragraph">
<p><a href="https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html" class="bare">https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html</a></p>
<p><a href="https://cloud.spring.io/spring-cloud-function/home.html" class="bare">https://cloud.spring.io/spring-cloud-function/home.html</a></p>
</div>
<div class="paragraph">
<p>The <a href="https://aws.amazon.com/">AWS</a> adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.</p>
@@ -124,94 +117,7 @@ $(addBlockSwitches);
<h2 id="_introduction"><a class="link" href="#_introduction">Introduction</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The adapter has a couple of generic request handlers that you can use. The most generic is <code>SpringBootStreamHandler</code>, which uses a Jackson <code>ObjectMapper</code> provided by Spring Boot to serialize and deserialize the objects in the function. There is also a <code>SpringBootRequestHandler</code> which you can extend, and provide the input and output types as type parameters (enabling AWS to inspect the class and do the JSON conversions itself).</p>
</div>
<div class="paragraph">
<p>If your app has more than one <code>@Bean</code> of type <code>Function</code> etc. then you can choose the one to use by configuring <code>function.name</code> (e.g. as <code>FUNCTION_NAME</code> environment variable in AWS). The functions are extracted from the Spring Cloud <code>FunctionCatalog</code> (searching first for <code>Function</code> then <code>Consumer</code> and finally <code>Supplier</code>).</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_notes_on_jar_layout"><a class="link" href="#_notes_on_jar_layout">Notes on JAR Layout</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>You don&#8217;t need the Spring Cloud Function Web or Stream adapter at runtime in Lambda, so you might
need to exclude those before you create the JAR you send to AWS. A Lambda application has to be
shaded, but a Spring Boot standalone application does not, so you can run the same app using 2
separate jars (as per the sample). The sample app creates 2 jar files, one with an <code>aws</code>
classifier for deploying in Lambda, and one executable (thin) jar that includes <code>spring-cloud-function-web</code>
at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file
manifest, using the <code>Start-Class</code> attribute (which will be added for you by the Spring Boot
tooling if you use the starter parent). If there is no <code>Start-Class</code> in your manifest you can
use an environment variable or system property <code>MAIN_CLASS</code> when you deploy the function to AWS.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_upload"><a class="link" href="#_upload">Upload</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Build the sample under <code>spring-cloud-function-samples/function-sample-aws</code> and upload the <code>-aws</code> jar file to Lambda. The handler can be <code>example.Handler</code> or <code>org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler</code> (FQN of the class, <em>not</em> a method reference, although Lambda does accept method references).</p>
</div>
<div class="listingblock">
<div class="content">
<pre>./mvnw -U clean package</pre>
</div>
</div>
<div class="paragraph">
<p>Using the AWS command line tools it looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>aws lambda create-function --function-name Uppercase --role arn:aws:iam::[USERID]:role/service-role/[ROLE] --zip-file fileb://function-sample-aws/target/function-sample-aws-2.0.0.BUILD-SNAPSHOT-aws.jar --handler org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler --description "Spring Cloud Function Adapter Example" --runtime java8 --region us-east-1 --timeout 30 --memory-size 1024 --publish</pre>
</div>
</div>
<div class="paragraph">
<p>The input type for the function in the AWS sample is a Foo with a single property called "value". So you would need this to test it:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
"value": "test"
}</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The AWS sample app is written in the "functional" style (as an <code>ApplicationContextInitializer</code>). This is much faster on startup in Lambda than the traditional <code>@Bean</code> style, so if you don&#8217;t need <code>@Beans</code> (or <code>@EnableAutoConfiguration</code>) it&#8217;s a good choice. Warm starts are not affected.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_type_conversion"><a class="link" href="#_type_conversion">Type Conversion</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud Function will attempt to transparently handle type conversion between the raw
input stream and types declared by your function.</p>
</div>
<div class="paragraph">
<p>For example, if your function signature is as such <code>Function&lt;Foo, Bar&gt;</code> we will attempt to convert
incoming stream event to an instance of <code>Foo</code>.</p>
</div>
<div class="paragraph">
<p>In the event type is not known or can not be determined (e.g., <code>Function&lt;?, ?&gt;</code>) we will attempt to
convert an incoming stream event to a generic <code>Map</code>.</p>
</div>
<div class="sect3">
<h4 id="_raw_input"><a class="link" href="#_raw_input">Raw Input</a></h4>
<div class="paragraph">
<p>There are times when you may want to have access to a raw input. In this case all you need is to declare your
function signature to accept <code>InputStream</code>. For example, <code>Function&lt;InputStream, ?&gt;</code>. In this case
we will not attempt any conversion and will pass the raw input directly to a function.</p>
</div>
<p>Unresolved directive in aws.adoc - include::aws-intro.adoc[]</p>
</div>
</div>
</div>
@@ -220,7 +126,7 @@ we will not attempt any conversion and will pass the raw input directly to a fun
<div class="sectionbody">
<div class="paragraph">
<p>Your functions will start much quicker if you can use functional bean definitions instead of <code>@Bean</code>. To do this make your main class
an <code>ApplicationContextInitalizer&lt;GenericApplicationContext&gt;</code> and use the <code>registerBean()</code> methods in <code>GenericApplicationContext</code> to
an <code>ApplicationContextInitializer&lt;GenericApplicationContext&gt;</code> and use the <code>registerBean()</code> methods in <code>GenericApplicationContext</code> to
create all the beans you need. You function need sto be registered as a bean of type <code>FunctionRegistration</code> so that the input and
output types can be accessed by the framework. There is an example in github (the AWS sample is written in this style). It would
look something like this:</p>
@@ -251,7 +157,7 @@ public class FuncApplication implements ApplicationContextInitializer&lt;Generic
</div>
</div>
<div class="sect1">
<h2 id="_platfom_specific_features"><a class="link" href="#_platfom_specific_features">Platfom Specific Features</a></h2>
<h2 id="_platform_specific_features"><a class="link" href="#_platform_specific_features">Platform Specific Features</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_http_and_api_gateway"><a class="link" href="#_http_and_api_gateway">HTTP and API Gateway</a></h3>

125
azure-readme.html
View File

@@ -5,7 +5,7 @@
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.7.1">
<title>Accessing Azure ExecutionContext</title>
<title>Sample Function</title>
<link rel="stylesheet" href="css/spring.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
@@ -87,11 +87,7 @@ $(addBlockSwitches);
<div id="header">
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel2">
<li><a href="#_accessing_azure_executioncontext">Accessing Azure ExecutionContext</a></li>
<li><a href="#_notes_on_jar_layout">Notes on JAR Layout</a></li>
<li><a href="#_build">Build</a></li>
<li><a href="#_running_the_sample">Running the sample</a></li>
<ul class="sectlevel1">
<li><a href="#_sample_function">Sample Function</a></li>
</ul>
</div>
@@ -104,122 +100,7 @@ $(addBlockSwitches);
You can write an app with a single <code>@Bean</code> of type <code>Function</code> and it will be deployable in Azure if you get the JAR file laid out right.</p>
</div>
<div class="paragraph">
<p>This project provides an adapter layer for a Spring Cloud Function application onto Azure.
You can write an app with a single <code>@Bean</code> of type <code>Function</code> and it will be deployable in Azure if you get the JAR file laid out right.</p>
</div>
<div class="paragraph">
<p>There is an <code>AzureSpringBootRequestHandler</code> which you must extend, and provide the input and output types as annotated method parameters (enabling Azure to inspect the class and create JSON bindings). The base class has two useful methods (<code>handleRequest</code> and <code>handleOutput</code>) to which you can delegate the actual function call, so mostly the function will only ever have one line.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class FooHandler extends AzureSpringBootRequestHandler&lt;Foo, Bar&gt; {
@FunctionName("uppercase")
public Bar execute(
@HttpTrigger(name = "req", methods = { HttpMethod.GET,
HttpMethod.POST }, authLevel = AuthorizationLevel.ANONYMOUS)
Foo foo,
ExecutionContext context) {
return handleRequest(foo, context);
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This Azure handler will delegate to a <code>Function&lt;Foo,Bar&gt;</code> bean (or a <code>Function&lt;Publisher&lt;Foo&gt;,Publisher&lt;Bar&gt;&gt;</code>). Some Azure triggers (e.g. <code>@CosmosDBTrigger</code>) result in a input type of <code>List</code> and in that case you can bind to <code>List</code> in the Azure handler, or <code>String</code> (the raw JSON). The <code>List</code> input delegates to a <code>Function</code> with input type <code>Map&lt;String,Object&gt;</code>, or <code>Publisher</code> or <code>List</code> of the same type. The output of the <code>Function</code> can be a <code>List</code> (one-for-one) or a single value (aggregation), and the output binding in the Azure declaration should match.</p>
</div>
<div class="paragraph">
<p>If your app has more than one <code>@Bean</code> of type <code>Function</code> etc. then you can choose the one to use by configuring <code>function.name</code>. Or if you make the <code>@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>FunctionCatalog</code> so the default function names are the same as the bean names.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_accessing_azure_executioncontext"><a class="link" href="#_accessing_azure_executioncontext">Accessing Azure ExecutionContext</a></h3>
<div class="paragraph">
<p>Some time there is a need to access the target execution context provided by Azure runtime in the form of <code>com.microsoft.azure.functions.ExecutionContext</code>.
For example one of such needs is logging, so it can appear in the Azure console.</p>
</div>
<div class="paragraph">
<p>For that purpose Spring Cloud Function will register <code>ExecutionContext</code> as bean in the Application context, so it could be injected into your function.
For example</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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());
};
}</code></pre>
</div>
</div>
<div class="paragraph">
<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>targetExecutionContext</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_notes_on_jar_layout"><a class="link" href="#_notes_on_jar_layout">Notes on JAR Layout</a></h3>
<div class="paragraph">
<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 <strong>not</strong> be included.</p>
</div>
</div>
<div class="sect1">
<h2 id="_build"><a class="link" href="#_build">Build</a></h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre>./mvnw -U clean package</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_running_the_sample"><a class="link" href="#_running_the_sample">Running the sample</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can run the sample locally, just like the other Spring Cloud Function samples:</p>
</div>
<hr>
<hr>
<div class="paragraph">
<p>and <code>curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'</code>.</p>
</div>
<div class="paragraph">
<p>You will need the <code>az</code> CLI app (see <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven" class="bare">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>
</div>
<div class="listingblock">
<div class="content">
<pre>$ az login
$ mvn azure-functions:deploy</pre>
</div>
</div>
<div class="paragraph">
<p>On another terminal try this: <code>curl <a href="https://&lt;azure-function-url-from-the-log&gt;/api/uppercase" class="bare">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>
</div>
<div class="paragraph">
<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>
</div>
<div class="listingblock">
<div class="content">
<pre>{
"value": "foobar"
}</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The Azure sample app is written in the "non-functional" style (using <code>@Bean</code>). The functional style (with just <code>Function</code> or <code>ApplicationContextInitializer</code>) is much faster on startup in Azure than the traditional <code>@Bean</code> style, so if you don&#8217;t need <code>@Beans</code> (or <code>@EnableAutoConfiguration</code>) it&#8217;s a good choice. Warm starts are not affected.
</td>
</tr>
</table>
<p>Unresolved directive in azure-readme.adoc - include::azure-intro.adoc[]</p>
</div>
</div>
</div>

132
azure.html
View File

@@ -5,7 +5,7 @@
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.7.1">
<title>Accessing Azure ExecutionContext</title>
<title>Untitled</title>
<link rel="stylesheet" href="css/spring.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
@@ -83,17 +83,8 @@ $(addBlockSwitches);
</script>
</head>
<body class="book toc2 toc-left">
<body class="book">
<div id="header">
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel2">
<li><a href="#_accessing_azure_executioncontext">Accessing Azure ExecutionContext</a></li>
<li><a href="#_notes_on_jar_layout">Notes on JAR Layout</a></li>
<li><a href="#_build">Build</a></li>
<li><a href="#_running_the_sample">Running the sample</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
@@ -102,128 +93,13 @@ $(addBlockSwitches);
<p><strong>2.1.0.BUILD-SNAPSHOT</strong></p>
</div>
<div id="index-link" class="paragraph">
<p><a href="https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html" class="bare">https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html</a></p>
<p><a href="https://cloud.spring.io/spring-cloud-function/home.html" class="bare">https://cloud.spring.io/spring-cloud-function/home.html</a></p>
</div>
<div class="paragraph">
<p>The <a href="https://azure.microsoft.com">Azure</a> adapter bootstraps a Spring Cloud Function context and channels function calls from the Azure framework into the user functions, using Spring Boot configuration where necessary. Azure Functions has quite a unique, but invasive programming model, involving annotations in user code that are specific to the platform. The easiest way to use it with Spring Cloud is to extend a base class and write a method in it with the <code>@FunctionName</code> annotation which delegates to a base class method.</p>
</div>
<div class="paragraph">
<p>This project provides an adapter layer for a Spring Cloud Function application onto Azure.
You can write an app with a single <code>@Bean</code> of type <code>Function</code> and it will be deployable in Azure if you get the JAR file laid out right.</p>
</div>
<div class="paragraph">
<p>There is an <code>AzureSpringBootRequestHandler</code> which you must extend, and provide the input and output types as annotated method parameters (enabling Azure to inspect the class and create JSON bindings). The base class has two useful methods (<code>handleRequest</code> and <code>handleOutput</code>) to which you can delegate the actual function call, so mostly the function will only ever have one line.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class FooHandler extends AzureSpringBootRequestHandler&lt;Foo, Bar&gt; {
@FunctionName("uppercase")
public Bar execute(
@HttpTrigger(name = "req", methods = { HttpMethod.GET,
HttpMethod.POST }, authLevel = AuthorizationLevel.ANONYMOUS)
Foo foo,
ExecutionContext context) {
return handleRequest(foo, context);
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This Azure handler will delegate to a <code>Function&lt;Foo,Bar&gt;</code> bean (or a <code>Function&lt;Publisher&lt;Foo&gt;,Publisher&lt;Bar&gt;&gt;</code>). Some Azure triggers (e.g. <code>@CosmosDBTrigger</code>) result in a input type of <code>List</code> and in that case you can bind to <code>List</code> in the Azure handler, or <code>String</code> (the raw JSON). The <code>List</code> input delegates to a <code>Function</code> with input type <code>Map&lt;String,Object&gt;</code>, or <code>Publisher</code> or <code>List</code> of the same type. The output of the <code>Function</code> can be a <code>List</code> (one-for-one) or a single value (aggregation), and the output binding in the Azure declaration should match.</p>
</div>
<div class="paragraph">
<p>If your app has more than one <code>@Bean</code> of type <code>Function</code> etc. then you can choose the one to use by configuring <code>function.name</code>. Or if you make the <code>@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>FunctionCatalog</code> so the default function names are the same as the bean names.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_accessing_azure_executioncontext"><a class="link" href="#_accessing_azure_executioncontext">Accessing Azure ExecutionContext</a></h3>
<div class="paragraph">
<p>Some time there is a need to access the target execution context provided by Azure runtime in the form of <code>com.microsoft.azure.functions.ExecutionContext</code>.
For example one of such needs is logging, so it can appear in the Azure console.</p>
</div>
<div class="paragraph">
<p>For that purpose Spring Cloud Function will register <code>ExecutionContext</code> as bean in the Application context, so it could be injected into your function.
For example</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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());
};
}</code></pre>
</div>
</div>
<div class="paragraph">
<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>targetExecutionContext</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_notes_on_jar_layout"><a class="link" href="#_notes_on_jar_layout">Notes on JAR Layout</a></h3>
<div class="paragraph">
<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 <strong>not</strong> be included.</p>
</div>
</div>
<div class="sect1">
<h2 id="_build"><a class="link" href="#_build">Build</a></h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre>./mvnw -U clean package</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_running_the_sample"><a class="link" href="#_running_the_sample">Running the sample</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can run the sample locally, just like the other Spring Cloud Function samples:</p>
</div>
<hr>
<hr>
<div class="paragraph">
<p>and <code>curl -H "Content-Type: text/plain" localhost:8080/function -d '{"value": "hello foobar"}'</code>.</p>
</div>
<div class="paragraph">
<p>You will need the <code>az</code> CLI app (see <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven" class="bare">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>
</div>
<div class="listingblock">
<div class="content">
<pre>$ az login
$ mvn azure-functions:deploy</pre>
</div>
</div>
<div class="paragraph">
<p>On another terminal try this: <code>curl <a href="https://&lt;azure-function-url-from-the-log&gt;/api/uppercase" class="bare">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>
</div>
<div class="paragraph">
<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>
</div>
<div class="listingblock">
<div class="content">
<pre>{
"value": "foobar"
}</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The Azure sample app is written in the "non-functional" style (using <code>@Bean</code>). The functional style (with just <code>Function</code> or <code>ApplicationContextInitializer</code>) is much faster on startup in Azure than the traditional <code>@Bean</code> style, so if you don&#8217;t need <code>@Beans</code> (or <code>@EnableAutoConfiguration</code>) it&#8217;s a good choice. Warm starts are not affected.
</td>
</tr>
</table>
<p>Unresolved directive in azure.adoc - include::azure-intro.adoc[]</p>
</div>
</div>
</div>

114
openwhisk-readme.html
View File

@@ -98,119 +98,7 @@ $(addBlockSwitches);
<h2 id="_quick_start"><a class="link" href="#_quick_start">Quick Start</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Implement a POF (be sure to use the <code>functions</code> package):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>package functions;
import java.util.function.Function;
public class Uppercase implements Function&lt;String, String&gt; {
public String apply(String input) {
return input.toUpperCase();
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Install it into your local Maven repository:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>./mvnw clean install</code></pre>
</div>
</div>
<div class="paragraph">
<p>Create a <code>function.properties</code> file that provides its Maven coordinates. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>dependencies.function: com.example:pof:0.0.1-SNAPSHOT</code></pre>
</div>
</div>
<div class="paragraph">
<p>Copy the openwhisk runner JAR to the working directory (same directory as the properties file):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>cp spring-cloud-function-adapters/spring-cloud-function-adapter-openwhisk/target/spring-cloud-function-adapter-openwhisk-2.0.0.BUILD-SNAPSHOT.jar runner.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>Generate a m2 repo from the <code>--thin.dryrun</code> of the runner JAR with the above properties file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>java -jar -Dthin.root=m2 runner.jar --thin.name=function --thin.dryrun</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the following Dockerfile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>FROM openjdk:8-jdk-alpine
VOLUME /tmp
COPY m2 /m2
ADD runner.jar .
ADD function.properties .
ENV JAVA_OPTS=""
ENTRYPOINT [ "java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "runner.jar", "--thin.root=/m2", "--thin.name=function", "--function.name=uppercase"]
EXPOSE 8080</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
you could use a Spring Cloud Function app, instead of just a jar with a POF in it, in which case you would have to change the way the app runs in the container so that it picks up the main class as a source file. For example, you could change the <code>ENTRYPOINT</code> above and add <code>--spring.main.sources=com.example.SampleApplication</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Build the Docker image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>docker build -t [username/appname] .</code></pre>
</div>
</div>
<div class="paragraph">
<p>Push the Docker image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>docker push [username/appname]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the OpenWhisk CLI (e.g. after <code>vagrant ssh</code>) to create the action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>wsk action create example --docker [username/appname]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Invoke the action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>wsk action invoke example --result --param payload foo
{
"result": "FOO"
}</code></pre>
</div>
<p>Unresolved directive in openwhisk-readme.adoc - include::openwhisk-quick-start.adoc[]</p>
</div>
</div>
</div>

116
openwhisk.html
View File

@@ -99,7 +99,7 @@ $(addBlockSwitches);
<p><strong>2.1.0.BUILD-SNAPSHOT</strong></p>
</div>
<div id="index-link" class="paragraph">
<p><a href="https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html" class="bare">https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html</a></p>
<p><a href="https://cloud.spring.io/spring-cloud-function/home.html" class="bare">https://cloud.spring.io/spring-cloud-function/home.html</a></p>
</div>
<div class="paragraph">
<p>The <a href="https://openwhisk.apache.org/">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>
@@ -110,119 +110,7 @@ $(addBlockSwitches);
<h2 id="_quick_start"><a class="link" href="#_quick_start">Quick Start</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Implement a POF (be sure to use the <code>functions</code> package):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>package functions;
import java.util.function.Function;
public class Uppercase implements Function&lt;String, String&gt; {
public String apply(String input) {
return input.toUpperCase();
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Install it into your local Maven repository:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>./mvnw clean install</code></pre>
</div>
</div>
<div class="paragraph">
<p>Create a <code>function.properties</code> file that provides its Maven coordinates. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>dependencies.function: com.example:pof:0.0.1-SNAPSHOT</code></pre>
</div>
</div>
<div class="paragraph">
<p>Copy the openwhisk runner JAR to the working directory (same directory as the properties file):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>cp spring-cloud-function-adapters/spring-cloud-function-adapter-openwhisk/target/spring-cloud-function-adapter-openwhisk-2.0.0.BUILD-SNAPSHOT.jar runner.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>Generate a m2 repo from the <code>--thin.dryrun</code> of the runner JAR with the above properties file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>java -jar -Dthin.root=m2 runner.jar --thin.name=function --thin.dryrun</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the following Dockerfile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>FROM openjdk:8-jdk-alpine
VOLUME /tmp
COPY m2 /m2
ADD runner.jar .
ADD function.properties .
ENV JAVA_OPTS=""
ENTRYPOINT [ "java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "runner.jar", "--thin.root=/m2", "--thin.name=function", "--function.name=uppercase"]
EXPOSE 8080</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
you could use a Spring Cloud Function app, instead of just a jar with a POF in it, in which case you would have to change the way the app runs in the container so that it picks up the main class as a source file. For example, you could change the <code>ENTRYPOINT</code> above and add <code>--spring.main.sources=com.example.SampleApplication</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Build the Docker image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>docker build -t [username/appname] .</code></pre>
</div>
</div>
<div class="paragraph">
<p>Push the Docker image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>docker push [username/appname]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the OpenWhisk CLI (e.g. after <code>vagrant ssh</code>) to create the action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>wsk action create example --docker [username/appname]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Invoke the action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>wsk action invoke example --result --param payload foo
{
"result": "FOO"
}</code></pre>
</div>
<p>Unresolved directive in openwhisk.adoc - include::openwhisk-quick-start.adoc[]</p>
</div>
</div>
</div>

43
spring-cloud-function.html
View File

@@ -95,6 +95,7 @@ $(addBlockSwitches);
<li><a href="#_function_catalog_and_flexible_function_signatures">Function Catalog and Flexible Function Signatures</a>
<ul class="sectlevel2">
<li><a href="#_java_8_function_support">Java 8 function support</a></li>
<li><a href="#_function_routing">Function Routing</a></li>
<li><a href="#_kotlin_lambda_support">Kotlin Lambda support</a></li>
</ul>
</li>
@@ -117,14 +118,14 @@ $(addBlockSwitches);
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Mark Fisher, Dave Syer, Oleg Zhurakousky</p>
<p>Mark Fisher, Dave Syer, Oleg Zhurakousky, Anshul Mehra</p>
</div>
<div class="paragraph">
<p><strong>2.1.0.BUILD-SNAPSHOT</strong></p>
</div>
<hr>
<div id="index-link" class="paragraph">
<p><a href="https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html" class="bare">https://cloud.spring.io/spring-cloud-static/spring-cloud-function/2.1.0.RC1/home.html</a></p>
<p><a href="https://cloud.spring.io/spring-cloud-function/home.html" class="bare">https://cloud.spring.io/spring-cloud-function/home.html</a></p>
</div>
</div>
</div>
@@ -398,6 +399,44 @@ a controlled way.</p>
</div>
</div>
<div class="sect2">
<h3 id="_function_routing"><a class="link" href="#_function_routing">Function Routing</a></h3>
<div class="paragraph">
<p>Since version 2.2 Spring Cloud Function provides routing feature allowing
you to invoke a single function which acts as a router to an actual function you wish to invoke
This feature is very useful in certain FAAS environments where maintaining configurations
for several functions could be cumbersome or exposing more then one function is not possible.</p>
</div>
<div class="paragraph">
<p>You enable this feature via <code>spring.cloud.function.routing.enabled</code> property setting it
to <code>true</code> (default is <code>false</code>).
This enables <code>RoutingFunction</code> under the name <code>router</code> which is loaded in FunctionCatalog.</p>
</div>
<div class="paragraph">
<p>This function has the following signature:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class RoutingFunction implements Function&lt;Publisher&lt;Message&lt;?&gt;&gt;, Publisher&lt;?&gt;&gt;, Consumer&lt;Publisher&lt;Message&lt;?&gt;&gt;&gt; {
. . .
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This allows the above function to act as both <code>Function</code> and <code>Consumer</code>.
As you can see it takes <code>Message&lt;?&gt;</code> as an input argument. This allows you to communicate
the name of the actual function you want to invoke by providing <code>function.name</code> Message header.</p>
</div>
<div class="paragraph">
<p>In specific execution environments/models the adapters are responsible to translate and communicate <code>function.name</code>
via Message header. For example, when using <em>spring-cloud-function-web</em> you can provide <code>function.name</code> as an HTTP
header and the framework will propagate it as well as other HTTP headers as Message headers.</p>
</div>
<div class="paragraph">
<p>Using Message also allows us to benefit from `MessageConverter`s to convert incoming request to the actual input type
of the target function</p>
</div>
</div>
<div class="sect2">
<h3 id="_kotlin_lambda_support"><a class="link" href="#_kotlin_lambda_support">Kotlin Lambda support</a></h3>
<div class="paragraph">
<p>We also provide support for Kotlin lambdas (since v2.0).