Adjusted docs to benefit from recent s-c-build improvements
This commit is contained in:
Oleg Zhurakousky
@@ -1,10 +1,13 @@
|
||||
:branch: 2.1.x
|
||||
=== AWS Lambda
|
||||
|
||||
The https://aws.amazon.com/[AWS] adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.
|
||||
|
||||
|
||||
The adapter has a couple of generic request handlers that you can use. The most generic is `SpringBootStreamHandler`, which uses a Jackson `ObjectMapper` provided by Spring Boot to serialize and deserialize the objects in the function. There is also a `SpringBootRequestHandler` 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).
|
||||
|
||||
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name` (e.g. as `FUNCTION_NAME` environment variable in AWS). The functions are extracted from the Spring Cloud `FunctionCatalog` (searching first for `Function` then `Consumer` and finally `Supplier`).
|
||||
|
||||
== Notes on JAR Layout
|
||||
==== Notes on JAR Layout
|
||||
|
||||
You don'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
|
||||
@@ -50,13 +53,13 @@ then additional transformers must be configured as part of the maven-shade-plugi
|
||||
</plugin>
|
||||
----
|
||||
|
||||
== Build file setup
|
||||
==== Build file setup
|
||||
|
||||
In order to run Spring Cloud Function applications on AWS Lambda, you can leverage Maven or Gradle
|
||||
plugins offered by the cloud platform provider.
|
||||
|
||||
|
||||
=== Maven
|
||||
===== Maven
|
||||
|
||||
In order to use the adapter plugin for Maven, add the plugin dependency to your `pom.xml`
|
||||
file:
|
||||
@@ -94,7 +97,7 @@ You can use theSpring Boot Maven Plugin to generate the <<thin-jar>>.
|
||||
You can find the entire sample `pom.xml` file for deploying Spring Cloud Function
|
||||
applications to AWS Lambda with Maven https://github.com/spring-cloud/spring-cloud-function/blob/{branch}/spring-cloud-function-samples/function-sample-aws/pom.xml[here].
|
||||
|
||||
=== Gradle
|
||||
===== Gradle
|
||||
|
||||
In order to use the adapter plugin for Gradle, add the dependency to your `build.gradle` file:
|
||||
|
||||
@@ -160,7 +163,7 @@ assemble.dependsOn = [thinJar]
|
||||
You can find the entire sample `build.gradle` file for deploying Spring Cloud Function
|
||||
applications to AWS Lambda with Gradle https://github.com/spring-cloud/spring-cloud-function/blob/{branch}/spring-cloud-function-samples/function-sample-aws/build.gradle[here].
|
||||
|
||||
== Upload
|
||||
==== Upload
|
||||
|
||||
Build the sample under `spring-cloud-function-samples/function-sample-aws` and upload the `-aws` jar file to Lambda. The handler can be `example.Handler` or `org.springframework.cloud.function.adapter.aws.SpringBootStreamHandler` (FQN of the class, _not_ a method reference, although Lambda does accept method references).
|
||||
|
||||
@@ -185,7 +188,7 @@ The input type for the function in the AWS sample is a Foo with a single propert
|
||||
NOTE: The AWS sample app is written in the "functional" style (as an `ApplicationContextInitializer`). This is much faster on startup in Lambda than the traditional `@Bean` style, so if you don't need `@Beans` (or `@EnableAutoConfiguration`) it's a good choice. Warm starts are not affected.
|
||||
|
||||
|
||||
== Type Conversion
|
||||
==== Type Conversion
|
||||
|
||||
Spring Cloud Function will attempt to transparently handle type conversion between the raw
|
||||
input stream and types declared by your function.
|
||||
@@ -196,7 +199,7 @@ incoming stream event to an instance of `Foo`.
|
||||
In the event type is not known or can not be determined (e.g., `Function<?, ?>`) we will attempt to
|
||||
convert an incoming stream event to a generic `Map`.
|
||||
|
||||
==== Raw Input
|
||||
====== Raw Input
|
||||
|
||||
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 `InputStream`. For example, `Function<InputStream, ?>`. In this case
|
||||
|
||||
@@ -1,8 +1,5 @@
|
||||
*{spring-cloud-function-version}*
|
||||
|
||||
[#index-link]
|
||||
{docs-url}spring-cloud-function/{docs-version}home.html
|
||||
|
||||
|
||||
The https://aws.amazon.com/[AWS] adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
:branch: 2.1.x
|
||||
=== Microsoft Azure
|
||||
|
||||
The https://azure.microsoft.com[Azure] 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 `@FunctionName` annotation which delegates to a base class method.
|
||||
|
||||
|
||||
This project provides an adapter layer for a Spring Cloud Function application onto Azure.
|
||||
You can write an app with a single `@Bean` of type `Function` and it will be deployable in Azure if you get the JAR file laid out right.
|
||||
@@ -24,7 +27,7 @@ This Azure handler will delegate to a `Function<Foo,Bar>` bean (or a `Function<P
|
||||
|
||||
If your app has more than one `@Bean` of type `Function` etc. then you can choose the one to use by configuring `function.name`. Or if you make the `@FunctionName` 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 `FunctionCatalog` so the default function names are the same as the bean names.
|
||||
|
||||
=== Accessing Azure ExecutionContext
|
||||
==== Accessing Azure ExecutionContext
|
||||
|
||||
Some time there is a need to access the target execution context provided by Azure runtime in the form of `com.microsoft.azure.functions.ExecutionContext`.
|
||||
For example one of such needs is logging, so it can appear in the Azure console.
|
||||
@@ -43,7 +46,7 @@ public Function<Foo, Bar> uppercase(ExecutionContext targetContext) {
|
||||
Normally type-based injection should suffice, however if need to you can also utilise the bean name under which it is registered which is `targetExecutionContext`.
|
||||
|
||||
|
||||
=== Notes on JAR Layout
|
||||
==== Notes on JAR Layout
|
||||
|
||||
You don'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't be used if you include it, so
|
||||
@@ -53,7 +56,7 @@ it doesn't hurt to leave it in. A function application on Azure is an archive ge
|
||||
the handler classes. If you prefer you can just use a regular flat JAR file.
|
||||
The dependencies should *not* be included.
|
||||
|
||||
== Build file setup
|
||||
==== Build file setup
|
||||
|
||||
In order to run Spring Cloud Function applications on Microsoft Azure, you can leverage the Maven
|
||||
plugin offered by the cloud platform provider.
|
||||
@@ -106,13 +109,13 @@ applications to Microsoft Azure with Maven https://github.com/spring-cloud/sprin
|
||||
NOTE: As of yet, only Maven plugin is available. Gradle plugin has not been created by
|
||||
the cloud platform provider.
|
||||
|
||||
== Build
|
||||
==== Build
|
||||
|
||||
----
|
||||
./mvnw -U clean package
|
||||
----
|
||||
|
||||
== Running the sample
|
||||
==== Running the sample
|
||||
|
||||
You can run the sample locally, just like the other Spring Cloud Function samples:
|
||||
|
||||
|
||||
@@ -1,8 +1,5 @@
|
||||
*{spring-cloud-function-version}*
|
||||
|
||||
[#index-link]
|
||||
{docs-url}spring-cloud-function/{docs-version}home.html
|
||||
|
||||
|
||||
The https://azure.microsoft.com[Azure] 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 `@FunctionName` annotation which delegates to a base class method.
|
||||
|
||||
|
||||
@@ -1,8 +1,5 @@
|
||||
*{spring-cloud-function-version}*
|
||||
|
||||
[#index-link]
|
||||
{docs-url}spring-cloud-function/{docs-version}home.html
|
||||
|
||||
|
||||
The https://openwhisk.apache.org/[OpenWhisk] 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.
|
||||
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
= Spring Cloud Function Reference Documentation
|
||||
Mark Fisher, Dave Syer, Oleg Zhurakousky, Anshul Mehra
|
||||
|
||||
*{spring-cloud-function-version}*
|
||||
|
||||
:docinfo: shared
|
||||
|
||||
The reference documentation consists of the following sections:
|
||||
|
||||
[horizontal]
|
||||
<<spring-cloud-function.adoc#,Reference Guide>> :: Spring Cloud Function Reference
|
||||
<<aws.adoc#,AWS Adapter>> :: AWS Adapter Reference
|
||||
<<azure.adoc#, Azure Adapter>> :: Azure Adapter Reference
|
||||
<<openwhisk.adoc#, Apache OpenWhisk Adapter>> :: Apache OpenWhisk Adapter Reference
|
||||
|
||||
|
||||
Relevant Links:
|
||||
|
||||
[horizontal]
|
||||
https://projectreactor.io/[Reactor] :: Project Reactor
|
||||
https://projectriff.io/[riff] :: Project riff
|
||||
@@ -1 +0,0 @@
|
||||
spring-cloud-function.adoc
|
||||
21
docs/src/main/asciidoc/index.adoc
Normal file
21
docs/src/main/asciidoc/index.adoc
Normal file
@@ -0,0 +1,21 @@
|
||||
= Spring Cloud Function Reference Documentation
|
||||
Mark Fisher, Dave Syer, Oleg Zhurakousky, Anshul Mehra
|
||||
|
||||
*{spring-cloud-function-version}*
|
||||
|
||||
:docinfo: shared
|
||||
|
||||
The reference documentation consists of the following sections:
|
||||
|
||||
[horizontal]
|
||||
<<spring-cloud-function.adoc#,Reference Guide>> :: Spring Cloud Function Reference
|
||||
<<aws.adoc#,AWS Adapter>> :: AWS Adapter Reference
|
||||
<<azure.adoc#, Azure Adapter>> :: Azure Adapter Reference
|
||||
<<openwhisk.adoc#, Apache OpenWhisk Adapter>> :: Apache OpenWhisk Adapter Reference
|
||||
|
||||
|
||||
Relevant Links:
|
||||
|
||||
[horizontal]
|
||||
https://projectreactor.io/[Reactor] :: Project Reactor
|
||||
https://projectriff.io/[riff] :: Project riff
|
||||
@@ -11,9 +11,6 @@ Mark Fisher, Dave Syer, Oleg Zhurakousky, Anshul Mehra
|
||||
:docslink: {githubmaster}/docs/src/main/asciidoc
|
||||
:nofooter:
|
||||
|
||||
[#index-link]
|
||||
{docs-url}spring-cloud-function/{docs-version}home.html
|
||||
|
||||
== Introduction
|
||||
|
||||
include::_intro.adoc[]
|
||||
@@ -201,9 +198,20 @@ Please refer to https://docs.spring.io/spring-cloud-stream/docs/current/referenc
|
||||
|
||||
Spring Cloud Function provides a "deployer" library that allows you to launch a jar file (or exploded archive, or set of jar files) with an isolated class loader and expose the functions defined in it. This is quite a powerful tool that would allow you to, for instance, adapt a function to a range of different input-output adapters without changing the target jar file. Serverless platforms often have this kind of feature built in, so you could see it as a building block for a function invoker in such a platform (indeed the https://projectriff.io[Riff] Java function invoker uses this library).
|
||||
|
||||
The standard entry point is to add `spring-cloud-function-deployer` to the classpath, the deployer kicks in and looks for some configuration to tell it where to find the function jar. At a minimum the user has to provide a `spring.cloud.function.location` which is a URL or resource location for the archive containing the functions. It can optionally use a `maven:` prefix to locate the artifact via a dependency lookup (see `FunctionProperties` for complete details). A Spring Boot application is bootstrapped from the jar file, using the `MANIFEST.MF` to locate a start class, so that a standard Spring Boot fat jar works well, for example. If the target jar can be launched successfully then the result is a function registered in the main application's `FunctionCatalog`. The registered function can be applied by code in the main application, even though it was created in an isolated class loader (by deault).
|
||||
The standard entry point is to add `spring-cloud-function-deployer` to the classpath, the deployer kicks in and looks for some configuration to tell it where to find the function jar.
|
||||
|
||||
Here is the example of deploying a JAR which contains an 'uppercase' function and invoking it .
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-function-deployer</artifactId>
|
||||
<version>${spring.cloud.function.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
|
||||
At a minimum the user has to provide a `spring.cloud.function.location` which is a URL or resource location for the archive containing the functions. It can optionally use a `maven:` prefix to locate the artifact via a dependency lookup (see `FunctionProperties` for complete details). A Spring Boot application is bootstrapped from the jar file, using the `MANIFEST.MF` to locate a start class, so that a standard Spring Boot fat jar works well, for example. If the target jar can be launched successfully then the result is a function registered in the main application's `FunctionCatalog`. The registered function can be applied by code in the main application, even though it was created in an isolated class loader (by deault).
|
||||
|
||||
Here is the example of deploying a JAR which contains an 'uppercase' function and invoking it .
|
||||
|
||||
```java
|
||||
@SpringBootApplication
|
||||
@@ -333,3 +341,6 @@ https://projectriff.io[Riff] supports Java functions and its
|
||||
https://github.com/projectriff/java-function-invoker[Java Function
|
||||
Invoker] acts natively is an adapter for Spring Cloud Function jars.
|
||||
|
||||
include::adapters/aws-intro.adoc[]
|
||||
include::adapters/azure-intro.adoc[]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user