From a4a19aadf0da05a033729abf8541fdf311bb4ad5 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Mon, 4 Jun 2018 15:05:46 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- ...ulti__building_and_running_a_function.html | 4 +- .../multi__deploying_a_packaged_function.html | 2 +- multi/multi__dynamic_compilation.html | 14 +- ...alog_and_flexible_function_signatures.html | 4 +- .../multi__serverless_platform_adapters.html | 6 +- ...ti__standalone_streaming_applications.html | 2 +- multi/multi__standalone_web_applications.html | 4 +- multi/multi_spring-cloud-function.html | 2 +- single/spring-cloud-function.html | 50 +++--- spring-cloud-function.xml | 149 ++++++++++-------- 10 files changed, 130 insertions(+), 107 deletions(-) diff --git a/multi/multi__building_and_running_a_function.html b/multi/multi__building_and_running_a_function.html index 726dfeada..ca077a837 100644 --- a/multi/multi__building_and_running_a_function.html +++ b/multi/multi__building_and_running_a_function.html @@ -1,6 +1,6 @@ - 3. Building and Running a Function
3. Building and Running a Function
Prev   Next

3. Building and Running a Function

The sample @SpringBootApplication above has a function that can be + 3. Building and Running a Function

3. Building and Running a Function
Prev   Next

3. Building and Running a Function

The sample @SpringBootApplication above has a function that can be decorated at runtime by Spring Cloud Function to be an HTTP endpoint, or a Stream processor, for instance with RabbitMQ, Apache Kafka or JMS.

The @Beans can be Function, Consumer or Supplier (all from @@ -16,4 +16,4 @@ POJO) JSON. TBD: support for Flux<Message<Pojo>&g Pojo types (Fluxes implied and implemented by the framework).

Functions can be grouped together in a single application, or deployed one-per-jar. It’s up to the developer to choose. An app with multiple functions can be deployed multiple times in different "personalities", -exposing different functions over different physical transports.

Prev   Next
2. Getting Started Home 4. Dynamic Compilation
\ No newline at end of file +exposing different functions over different physical transports.

Prev   Next
2. Getting Started Home 4. Function Catalog and Flexible Function Signatures
\ No newline at end of file diff --git a/multi/multi__deploying_a_packaged_function.html b/multi/multi__deploying_a_packaged_function.html index b54584179..32a805e89 100644 --- a/multi/multi__deploying_a_packaged_function.html +++ b/multi/multi__deploying_a_packaged_function.html @@ -1,3 +1,3 @@ - 8. Deploying a Packaged Function
8. Deploying a Packaged Function
Prev   Next

8. Deploying a Packaged Function

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 Riff Java function invoker uses this library).

The standard entry point of the API is the Spring configuration annotation @EnableFunctionDeployer. If that is used in a Spring Boot application 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 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).

Prev   Next
7. Standalone Streaming Applications Home 9. Serverless Platform Adapters
\ No newline at end of file + 7. Deploying a Packaged Function
7. Deploying a Packaged Function
Prev   Next

7. Deploying a Packaged Function

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 Riff Java function invoker uses this library).

The standard entry point of the API is the Spring configuration annotation @EnableFunctionDeployer. If that is used in a Spring Boot application 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 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).

Prev   Next
6. Standalone Streaming Applications Home 8. Dynamic Compilation
\ No newline at end of file diff --git a/multi/multi__dynamic_compilation.html b/multi/multi__dynamic_compilation.html index 364dce615..64c4aafb6 100644 --- a/multi/multi__dynamic_compilation.html +++ b/multi/multi__dynamic_compilation.html @@ -1,13 +1,13 @@ - 4. Dynamic Compilation
4. Dynamic Compilation
Prev   Next

4. Dynamic Compilation

There is a sample app that uses the function compiler to create a + 8. Dynamic Compilation

8. Dynamic Compilation
Prev   Next

8. Dynamic Compilation

There is a sample app that uses the function compiler to create a function from a configuration property. The vanilla "function-sample" -also has that feature. And there are some examples that you can run to +also has that feature. And there are some scripts that you can run to see the compilation happening at run time. To run these examples, -change into the scripts directory:

cd scripts

Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server).

4.1 Start the Function Registry Service:

./function-registry.sh

4.2 Register a Function:

./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())"

4.3 Run a REST Microservice using that Function:

./web.sh -f uppercase -p 9000
-curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo

4.4 Register a Supplier:

./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")"

4.5 Run a REST Microservice using that Supplier:

./web.sh -s words -p 9001
-curl -H "Accept: application/json" localhost:9001/words

4.6 Register a Consumer:

./registerConsumer.sh -n print -t String -f "System.out::println"

4.7 Run a REST Microservice using that Consumer:

./web.sh -c print -p 9002
-curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print

4.8 Run Stream Processing Microservices:

First register a streaming words supplier:

./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)"

Then start the source (supplier), processor (function), and sink (consumer) apps +change into the scripts directory:

cd scripts

Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server).

Start the Function Registry Service:

./function-registry.sh

Register a Function:

./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())"

Run a REST Microservice using that Function:

./web.sh -f uppercase -p 9000
+curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo

Register a Supplier:

./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")"

Run a REST Microservice using that Supplier:

./web.sh -s words -p 9001
+curl -H "Accept: application/json" localhost:9001/words

Register a Consumer:

./registerConsumer.sh -n print -t String -f "System.out::println"

Run a REST Microservice using that Consumer:

./web.sh -c print -p 9002
+curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print

Run Stream Processing Microservices:

First register a streaming words supplier:

./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)"

Then start the source (supplier), processor (function), and sink (consumer) apps (in reverse order):

./stream.sh -p 9103 -i uppercaseWords -c print
 ./stream.sh -p 9102 -i words -f uppercase -o uppercaseWords
 ./stream.sh -p 9101 -s wordstream -o words

The output will appear in the console of the sink app (one message per second, converted to uppercase):

MESSAGE-0
@@ -20,4 +20,4 @@ MESSAGE-6
 MESSAGE-7
 MESSAGE-8
 MESSAGE-9
-...
Prev   Next
3. Building and Running a Function Home 5. Function Catalog and Flexible Function Signatures
\ No newline at end of file +...
Prev   Next
7. Deploying a Packaged Function Home 9. Serverless Platform Adapters
\ No newline at end of file diff --git a/multi/multi__function_catalog_and_flexible_function_signatures.html b/multi/multi__function_catalog_and_flexible_function_signatures.html index 61b7387ea..97987f529 100644 --- a/multi/multi__function_catalog_and_flexible_function_signatures.html +++ b/multi/multi__function_catalog_and_flexible_function_signatures.html @@ -1,6 +1,6 @@ - 5. Function Catalog and Flexible Function Signatures
5. Function Catalog and Flexible Function Signatures
Prev   Next

5. Function Catalog and Flexible Function Signatures

One of the main features of Spring Cloud Function is to adapt and + 4. Function Catalog and Flexible Function Signatures

4. Function Catalog and Flexible Function Signatures
Prev   Next

4. Function Catalog and Flexible Function Signatures

One of the main features of Spring Cloud Function is to adapt and support a range of type signatures for user-defined functions. So users can supply a bean of type Function<String,String>, for instance, and the FunctionCatalog will wrap it into a @@ -23,4 +23,4 @@ resource). It can even contain a Consumer<Flux<>& as a Function, but it cannot contain a Consumer<T> and a Function<T,S> with the same name when T is not a Publisher because the consumer would be converted to a Function and only one -of them can be registered.

Prev   Next
4. Dynamic Compilation Home 6. Standalone Web Applications
\ No newline at end of file +of them can be registered.

Prev   Next
3. Building and Running a Function Home 5. Standalone Web Applications
\ No newline at end of file diff --git a/multi/multi__serverless_platform_adapters.html b/multi/multi__serverless_platform_adapters.html index 429b98714..502e7ca49 100644 --- a/multi/multi__serverless_platform_adapters.html +++ b/multi/multi__serverless_platform_adapters.html @@ -1,6 +1,6 @@ - 9. Serverless Platform Adapters
9. Serverless Platform Adapters
Prev   

9. Serverless Platform Adapters

As well as being able to run as a standalone process, a Spring Cloud + 9. Serverless Platform Adapters

9. Serverless Platform Adapters
Prev   

9. Serverless Platform Adapters

As well as being able to run as a standalone process, a Spring Cloud Function application can be adapted to run one of the existing serverless platforms. In the project there are adapters for AWS @@ -14,7 +14,7 @@ has its own Spring Cloud Function adapter. And Java Function Invoker acts natively is an adapter for Spring Cloud Function jars.

9.1 AWS Lambda

The AWS adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.

9.1.1 Introduction

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).

9.1.2 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 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 aws classifier for deploying in Lambda, and one executable (thin) jar that includes spring-cloud-function-web at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file manifest, using the Start-Class attribute (which will be added for you by the Spring Boot tooling if you use the starter parent). If there is no Start-Class in your manifest you can use an environment variable MAIN_CLASS when you deploy the function to AWS.

9.1.3 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).

./mvnw -U clean package

Using the AWS command line tools it looks like this:

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-1.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

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:

{
   "value": "test"
-}

9.2 Azure Functions

The 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 Spring Cloud Function Azure adapter trades the convenience of these annotations for portability of the function implementations. Instead of using the annotations you have to write some JSON by hand (at least for now) to guide the platform to call the right methods in the adapter.

The adapter has a generic http request handler that you can use. +}

9.1.4 Platfom Specific Features

HTTP and API Gateway

AWS has some platform-specific data types, including batching of messages, which is much more efficient than processing each one individually. To make use of these types you can write a function that depends on those types. Or you can rely on Spring to extract the data from the AWS types and convert it to a Spring Message. To do this you tell AWS that the function is of a specific generic handler type (depending on the AWS service) and provide a bean of type Function<Message<S>,Message<T>>, where S and T are your business data types. If there is more than one bean of type Function you may also need to configure the Spring Boot property function.name to be the name of the target bean (e.g. use FUNCTION_NAME as an environment variable).

The supported AWS services and generic handler types are listed below:

ServiceAWS TypesGeneric Handler 

API Gateway

APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent

org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler

 

Kinesis

KinesisEvent

org.springframework.cloud.function.adapter.aws.SpringBootKinesisEventHandler

 

For example, to deploy behind an API Gateway, use --handler org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler in your AWS command line (in via the UI) and define a @Bean of type Function<Message<Foo>,Message<Bar>> where Foo and Bar are POJO types (the data will be marshalled and unmarshalled by AWS using Jackson).

9.2 Azure Functions

The 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 Spring Cloud Function Azure adapter trades the convenience of these annotations for portability of the function implementations. Instead of using the annotations you have to write some JSON by hand (at least for now) to guide the platform to call the right methods in the adapter.

The adapter has a generic http request handler that you can use. There is a AzureSpringBootRequestHandler which you must extend, and provide the input and output types as type parameters (enabling Azure 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. The functions are extracted from the Spring Cloud FunctionCatalog.

9.2.1 Notes on JAR Layout

You don’t need the Spring Cloud Function Web at runtime in Azure, so you need to exclude this before you create the JAR you deploy to Azure. A function application on Azure 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 here). @@ -55,4 +55,4 @@ ENTRYPOINT [ "java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "runner. EXPOSE 8080

[Note]Note

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 ENTRYPOINT above and add --spring.main.sources=com.example.SampleApplication.

Build the Docker image:

docker build -t [username/appname] .

Push the Docker image:

docker push [username/appname]

Use the OpenWhisk CLI (e.g. after vagrant ssh) to create the action:

wsk action create example --docker [username/appname]

Invoke the action:

wsk action invoke example --result --param payload foo
 {
     "result": "FOO"
-}
Prev   
8. Deploying a Packaged Function Home 
\ No newline at end of file +}
Prev   
8. Dynamic Compilation Home 
\ No newline at end of file diff --git a/multi/multi__standalone_streaming_applications.html b/multi/multi__standalone_streaming_applications.html index a29d6d34f..cfc31249b 100644 --- a/multi/multi__standalone_streaming_applications.html +++ b/multi/multi__standalone_streaming_applications.html @@ -1,3 +1,3 @@ - 7. Standalone Streaming Applications
7. Standalone Streaming Applications
Prev   Next

7. Standalone Streaming Applications

To send or receive messages from a broker (such as RabbitMQ or Kafka) you can use the spring-cloud-function-stream adapter. Add the adapter to your classpath along with the appropriate binder from Spring Cloud Stream. The adapter will bind to the message broker as a Processor (input and output streams) unless the user explicitly disables one or the other using spring.cloud.function.stream.{source,sink}.enabled=false.

An incoming message is routed to a function (or consumer). If there is only one, then the choice is obvious. If there are multiple functions that can accept an incoming message, the message is inspected to see if there is a stream_routekey header containing the name of a function. Routing headers or function names can be composed using a comma- or pipe-separated name. The header is also added to outgoing messages from a supplier. Messages with no route key can be routed exclusively to a function or consumer by specifying spring.cloud.function.stream.{processor,sink}.name. If a single function cannot be identified to process an incoming message there will be an error, unless you set spring.cloud.function.stream.shared=true, in which case such messages will be sent to all compatible functions. A single supplier can be chosen for output messages from a supplier (if more than one is available) using the spring.cloud.function.stream.source.name.

[Note]Note

some binders will fail on startup if the message broker is not available and the function catalog contains suppliers that immediately produce messages when accessed. You can switch off the automatic publishing from suppliers on startup using the spring.cloud.function.strean.supplier.enabled=false flag.

Prev   Next
6. Standalone Web Applications Home 8. Deploying a Packaged Function
\ No newline at end of file + 6. Standalone Streaming Applications
6. Standalone Streaming Applications
Prev   Next

6. Standalone Streaming Applications

To send or receive messages from a broker (such as RabbitMQ or Kafka) you can use the spring-cloud-function-stream adapter. Add the adapter to your classpath along with the appropriate binder from Spring Cloud Stream. The adapter will bind to the message broker as a Processor (input and output streams) unless the user explicitly disables one or the other using spring.cloud.function.stream.{source,sink}.enabled=false.

An incoming message is routed to a function (or consumer). If there is only one, then the choice is obvious. If there are multiple functions that can accept an incoming message, the message is inspected to see if there is a stream_routekey header containing the name of a function. Routing headers or function names can be composed using a comma- or pipe-separated name. The header is also added to outgoing messages from a supplier. Messages with no route key can be routed exclusively to a function or consumer by specifying spring.cloud.function.stream.{processor,sink}.name. If a single function cannot be identified to process an incoming message there will be an error, unless you set spring.cloud.function.stream.shared=true, in which case such messages will be sent to all compatible functions. A single supplier can be chosen for output messages from a supplier (if more than one is available) using the spring.cloud.function.stream.source.name.

[Note]Note

some binders will fail on startup if the message broker is not available and the function catalog contains suppliers that immediately produce messages when accessed. You can switch off the automatic publishing from suppliers on startup using the spring.cloud.function.strean.supplier.enabled=false flag.

Prev   Next
5. Standalone Web Applications Home 7. Deploying a Packaged Function
\ No newline at end of file diff --git a/multi/multi__standalone_web_applications.html b/multi/multi__standalone_web_applications.html index 65d14d571..18fd54931 100644 --- a/multi/multi__standalone_web_applications.html +++ b/multi/multi__standalone_web_applications.html @@ -1,6 +1,6 @@ - 6. Standalone Web Applications
6. Standalone Web Applications
Prev   Next

6. Standalone Web Applications

The spring-cloud-function-web module has autoconfiguration that + 5. Standalone Web Applications

5. Standalone Web Applications
Prev   Next

5. Standalone Web Applications

The spring-cloud-function-web module has autoconfiguration that activates when it is included in a Spring Boot web application (with MVC support). There is also a spring-cloud-starter-function-web to collect all the optional dependnecies in case you just want a simple @@ -8,4 +8,4 @@ getting started experience.

With the web configurations activated your app endpoint (on "/" by default, but configurable with spring.cloud.function.web.path) that can be used to access the functions in the application context. The supported content types are -plain text and JSON.

MethodPathRequestResponseStatus

GET

/{supplier}

-

Items from the named supplier

200 OK

POST

/{consumer}

JSON object or text

Mirrors input and pushes request body into consumer

202 Accepted

POST

/{consumer}

JSON array or text with new lines

Mirrors input and pushes body into consumer one by one

202 Accepted

POST

/{function}

JSON object or text

The result of applying the named function

200 OK

POST

/{function}

JSON array or text with new lines

The result of applying the named function

200 OK

GET

/{function}/{item}

-

Convert the item into an object and return the result of applying the function

200 OK

As the table above shows the behaviour of the endpoint depends on the method and also the type of incoming request data. When the incoming data is single valued, and the target function is declared as obviously single valued (i.e. not returning a collection or Flux), then the response will also contain a single value. For multi-valued responses the client can ask for a server-sent event stream by sending `Accept: text/event-stream". If there is only one function (consumer etc.) then the name in the path is optional. Composite functions can be addressed using pipes or commas to separate function names (pipes are legal in URL paths, but a bit awkward to type on the command line).

Functions and consumers that are declared with input and output in Message<?> will see the request headers on the input messages, and the output message headers will be converted to HTTP headers.

When POSTing text the response format might be different with Spring Boot 2.0 and older versions, depending on the content negotiation (provide content type and accpt headers for the best results).

Prev   Next
5. Function Catalog and Flexible Function Signatures Home 7. Standalone Streaming Applications
\ No newline at end of file +plain text and JSON.

MethodPathRequestResponseStatus

GET

/{supplier}

-

Items from the named supplier

200 OK

POST

/{consumer}

JSON object or text

Mirrors input and pushes request body into consumer

202 Accepted

POST

/{consumer}

JSON array or text with new lines

Mirrors input and pushes body into consumer one by one

202 Accepted

POST

/{function}

JSON object or text

The result of applying the named function

200 OK

POST

/{function}

JSON array or text with new lines

The result of applying the named function

200 OK

GET

/{function}/{item}

-

Convert the item into an object and return the result of applying the function

200 OK

As the table above shows the behaviour of the endpoint depends on the method and also the type of incoming request data. When the incoming data is single valued, and the target function is declared as obviously single valued (i.e. not returning a collection or Flux), then the response will also contain a single value. For multi-valued responses the client can ask for a server-sent event stream by sending `Accept: text/event-stream". If there is only one function (consumer etc.) then the name in the path is optional. Composite functions can be addressed using pipes or commas to separate function names (pipes are legal in URL paths, but a bit awkward to type on the command line).

Functions and consumers that are declared with input and output in Message<?> will see the request headers on the input messages, and the output message headers will be converted to HTTP headers.

When POSTing text the response format might be different with Spring Boot 2.0 and older versions, depending on the content negotiation (provide content type and accpt headers for the best results).

Prev   Next
4. Function Catalog and Flexible Function Signatures Home 6. Standalone Streaming Applications
\ No newline at end of file diff --git a/multi/multi_spring-cloud-function.html b/multi/multi_spring-cloud-function.html index 685ddfc27..0a9cb8cb5 100644 --- a/multi/multi_spring-cloud-function.html +++ b/multi/multi_spring-cloud-function.html @@ -1,3 +1,3 @@ - Spring Cloud Function
Spring Cloud Function
   Next

Spring Cloud Function

Table of Contents

1. Introduction
2. Getting Started
3. Building and Running a Function
4. Dynamic Compilation
4.1. Start the Function Registry Service:
4.2. Register a Function:
4.3. Run a REST Microservice using that Function:
4.4. Register a Supplier:
4.5. Run a REST Microservice using that Supplier:
4.6. Register a Consumer:
4.7. Run a REST Microservice using that Consumer:
4.8. Run Stream Processing Microservices:
5. Function Catalog and Flexible Function Signatures
6. Standalone Web Applications
7. Standalone Streaming Applications
8. Deploying a Packaged Function
9. Serverless Platform Adapters
9.1. AWS Lambda
9.1.1. Introduction
9.1.2. Notes on JAR Layout
9.1.3. Upload
9.2. Azure Functions
9.2.1. Notes on JAR Layout
9.2.2. JSON Configuration
9.2.3. Build
9.2.4. Running the sample
9.3. Apache Openwhisk
9.3.1. Quick Start
   Next
   
\ No newline at end of file + Spring Cloud Function
Spring Cloud Function
   Next

Spring Cloud Function

Table of Contents

1. Introduction
2. Getting Started
3. Building and Running a Function
4. Function Catalog and Flexible Function Signatures
5. Standalone Web Applications
6. Standalone Streaming Applications
7. Deploying a Packaged Function
8. Dynamic Compilation
9. Serverless Platform Adapters
9.1. AWS Lambda
9.1.1. Introduction
9.1.2. Notes on JAR Layout
9.1.3. Upload
9.1.4. Platfom Specific Features
HTTP and API Gateway
9.2. Azure Functions
9.2.1. Notes on JAR Layout
9.2.2. JSON Configuration
9.2.3. Build
9.2.4. Running the sample
9.3. Apache Openwhisk
9.3.1. Quick Start
   Next
   
\ No newline at end of file diff --git a/single/spring-cloud-function.html b/single/spring-cloud-function.html index a4502f2d5..7f48e853a 100644 --- a/single/spring-cloud-function.html +++ b/single/spring-cloud-function.html @@ -1,6 +1,6 @@ - Spring Cloud Function

Spring Cloud Function

Table of Contents

1. Introduction
2. Getting Started
3. Building and Running a Function
4. Dynamic Compilation
4.1. Start the Function Registry Service:
4.2. Register a Function:
4.3. Run a REST Microservice using that Function:
4.4. Register a Supplier:
4.5. Run a REST Microservice using that Supplier:
4.6. Register a Consumer:
4.7. Run a REST Microservice using that Consumer:
4.8. Run Stream Processing Microservices:
5. Function Catalog and Flexible Function Signatures
6. Standalone Web Applications
7. Standalone Streaming Applications
8. Deploying a Packaged Function
9. Serverless Platform Adapters
9.1. AWS Lambda
9.1.1. Introduction
9.1.2. Notes on JAR Layout
9.1.3. Upload
9.2. Azure Functions
9.2.1. Notes on JAR Layout
9.2.2. JSON Configuration
9.2.3. Build
9.2.4. Running the sample
9.3. Apache Openwhisk
9.3.1. Quick Start

Mark Fisher, Dave Syer

1. Introduction

Spring Cloud Function is a project with the following high-level goals:

  • Promote the implementation of business logic via functions.
  • Decouple the development lifecycle of business logic from any specific runtime target so that the same code can run as a web endpoint, a stream processor, or a task.
  • Support a uniform programming model across serverless providers, as well as the ability to run standalone (locally or in a PaaS).
  • Enable Spring Boot features (auto-configuration, dependency injection, metrics) on serverless providers.

It abstracts away all of the transport details and + Spring Cloud Function

Spring Cloud Function

Table of Contents

1. Introduction
2. Getting Started
3. Building and Running a Function
4. Function Catalog and Flexible Function Signatures
5. Standalone Web Applications
6. Standalone Streaming Applications
7. Deploying a Packaged Function
8. Dynamic Compilation
9. Serverless Platform Adapters
9.1. AWS Lambda
9.1.1. Introduction
9.1.2. Notes on JAR Layout
9.1.3. Upload
9.1.4. Platfom Specific Features
HTTP and API Gateway
9.2. Azure Functions
9.2.1. Notes on JAR Layout
9.2.2. JSON Configuration
9.2.3. Build
9.2.4. Running the sample
9.3. Apache Openwhisk
9.3.1. Quick Start

Mark Fisher, Dave Syer

1. Introduction

Spring Cloud Function is a project with the following high-level goals:

  • Promote the implementation of business logic via functions.
  • Decouple the development lifecycle of business logic from any specific runtime target so that the same code can run as a web endpoint, a stream processor, or a task.
  • Support a uniform programming model across serverless providers, as well as the ability to run standalone (locally or in a PaaS).
  • Enable Spring Boot features (auto-configuration, dependency injection, metrics) on serverless providers.

It abstracts away all of the transport details and infrastructure, allowing the developer to keep all the familiar tools and processes, and focus firmly on business logic.

Here’s a complete, executable, testable Spring Boot application (implementing a simple string manipulation):

@SpringBootApplication
@@ -46,27 +46,7 @@ POJO) JSON. TBD: support for Flux<Message<Pojo>&g
 Pojo types (Fluxes implied and implemented by the framework).
Functions can be grouped together in a single application, or deployed
 one-per-jar. It’s up to the developer to choose. An app with multiple
 functions can be deployed multiple times in different "personalities",
-exposing different functions over different physical transports.

4. Dynamic Compilation

There is a sample app that uses the function compiler to create a -function from a configuration property. The vanilla "function-sample" -also has that feature. And there are some examples that you can run to -see the compilation happening at run time. To run these examples, -change into the scripts directory:

cd scripts

Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server).

4.1 Start the Function Registry Service:

./function-registry.sh

4.2 Register a Function:

./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())"

4.3 Run a REST Microservice using that Function:

./web.sh -f uppercase -p 9000
-curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo

4.4 Register a Supplier:

./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")"

4.5 Run a REST Microservice using that Supplier:

./web.sh -s words -p 9001
-curl -H "Accept: application/json" localhost:9001/words

4.6 Register a Consumer:

./registerConsumer.sh -n print -t String -f "System.out::println"

4.7 Run a REST Microservice using that Consumer:

./web.sh -c print -p 9002
-curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print

4.8 Run Stream Processing Microservices:

First register a streaming words supplier:

./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)"

Then start the source (supplier), processor (function), and sink (consumer) apps -(in reverse order):

./stream.sh -p 9103 -i uppercaseWords -c print
-./stream.sh -p 9102 -i words -f uppercase -o uppercaseWords
-./stream.sh -p 9101 -s wordstream -o words

The output will appear in the console of the sink app (one message per second, converted to uppercase):

MESSAGE-0
-MESSAGE-1
-MESSAGE-2
-MESSAGE-3
-MESSAGE-4
-MESSAGE-5
-MESSAGE-6
-MESSAGE-7
-MESSAGE-8
-MESSAGE-9
-...

5. Function Catalog and Flexible Function Signatures

One of the main features of Spring Cloud Function is to adapt and +exposing different functions over different physical transports.

4. Function Catalog and Flexible Function Signatures

One of the main features of Spring Cloud Function is to adapt and support a range of type signatures for user-defined functions. So users can supply a bean of type Function<String,String>, for instance, and the FunctionCatalog will wrap it into a @@ -89,7 +69,7 @@ resource). It can even contain a Consumer<Flux<>& as a Function, but it cannot contain a Consumer<T> and a Function<T,S> with the same name when T is not a Publisher because the consumer would be converted to a Function and only one -of them can be registered.

6. Standalone Web Applications

The spring-cloud-function-web module has autoconfiguration that +of them can be registered.

5. Standalone Web Applications

The spring-cloud-function-web module has autoconfiguration that activates when it is included in a Spring Boot web application (with MVC support). There is also a spring-cloud-starter-function-web to collect all the optional dependnecies in case you just want a simple @@ -97,7 +77,27 @@ getting started experience.

With the web configurations activated your app endpoint (on "/" by default, but configurable with spring.cloud.function.web.path) that can be used to access the functions in the application context. The supported content types are -plain text and JSON.

MethodPathRequestResponseStatus

GET

/{supplier}

-

Items from the named supplier

200 OK

POST

/{consumer}

JSON object or text

Mirrors input and pushes request body into consumer

202 Accepted

POST

/{consumer}

JSON array or text with new lines

Mirrors input and pushes body into consumer one by one

202 Accepted

POST

/{function}

JSON object or text

The result of applying the named function

200 OK

POST

/{function}

JSON array or text with new lines

The result of applying the named function

200 OK

GET

/{function}/{item}

-

Convert the item into an object and return the result of applying the function

200 OK

As the table above shows the behaviour of the endpoint depends on the method and also the type of incoming request data. When the incoming data is single valued, and the target function is declared as obviously single valued (i.e. not returning a collection or Flux), then the response will also contain a single value. For multi-valued responses the client can ask for a server-sent event stream by sending `Accept: text/event-stream". If there is only one function (consumer etc.) then the name in the path is optional. Composite functions can be addressed using pipes or commas to separate function names (pipes are legal in URL paths, but a bit awkward to type on the command line).

Functions and consumers that are declared with input and output in Message<?> will see the request headers on the input messages, and the output message headers will be converted to HTTP headers.

When POSTing text the response format might be different with Spring Boot 2.0 and older versions, depending on the content negotiation (provide content type and accpt headers for the best results).

7. Standalone Streaming Applications

To send or receive messages from a broker (such as RabbitMQ or Kafka) you can use the spring-cloud-function-stream adapter. Add the adapter to your classpath along with the appropriate binder from Spring Cloud Stream. The adapter will bind to the message broker as a Processor (input and output streams) unless the user explicitly disables one or the other using spring.cloud.function.stream.{source,sink}.enabled=false.

An incoming message is routed to a function (or consumer). If there is only one, then the choice is obvious. If there are multiple functions that can accept an incoming message, the message is inspected to see if there is a stream_routekey header containing the name of a function. Routing headers or function names can be composed using a comma- or pipe-separated name. The header is also added to outgoing messages from a supplier. Messages with no route key can be routed exclusively to a function or consumer by specifying spring.cloud.function.stream.{processor,sink}.name. If a single function cannot be identified to process an incoming message there will be an error, unless you set spring.cloud.function.stream.shared=true, in which case such messages will be sent to all compatible functions. A single supplier can be chosen for output messages from a supplier (if more than one is available) using the spring.cloud.function.stream.source.name.

[Note]Note

some binders will fail on startup if the message broker is not available and the function catalog contains suppliers that immediately produce messages when accessed. You can switch off the automatic publishing from suppliers on startup using the spring.cloud.function.strean.supplier.enabled=false flag.

8. Deploying a Packaged Function

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 Riff Java function invoker uses this library).

The standard entry point of the API is the Spring configuration annotation @EnableFunctionDeployer. If that is used in a Spring Boot application 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 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).

9. Serverless Platform Adapters

As well as being able to run as a standalone process, a Spring Cloud +plain text and JSON.

MethodPathRequestResponseStatus

GET

/{supplier}

-

Items from the named supplier

200 OK

POST

/{consumer}

JSON object or text

Mirrors input and pushes request body into consumer

202 Accepted

POST

/{consumer}

JSON array or text with new lines

Mirrors input and pushes body into consumer one by one

202 Accepted

POST

/{function}

JSON object or text

The result of applying the named function

200 OK

POST

/{function}

JSON array or text with new lines

The result of applying the named function

200 OK

GET

/{function}/{item}

-

Convert the item into an object and return the result of applying the function

200 OK

As the table above shows the behaviour of the endpoint depends on the method and also the type of incoming request data. When the incoming data is single valued, and the target function is declared as obviously single valued (i.e. not returning a collection or Flux), then the response will also contain a single value. For multi-valued responses the client can ask for a server-sent event stream by sending `Accept: text/event-stream". If there is only one function (consumer etc.) then the name in the path is optional. Composite functions can be addressed using pipes or commas to separate function names (pipes are legal in URL paths, but a bit awkward to type on the command line).

Functions and consumers that are declared with input and output in Message<?> will see the request headers on the input messages, and the output message headers will be converted to HTTP headers.

When POSTing text the response format might be different with Spring Boot 2.0 and older versions, depending on the content negotiation (provide content type and accpt headers for the best results).

6. Standalone Streaming Applications

To send or receive messages from a broker (such as RabbitMQ or Kafka) you can use the spring-cloud-function-stream adapter. Add the adapter to your classpath along with the appropriate binder from Spring Cloud Stream. The adapter will bind to the message broker as a Processor (input and output streams) unless the user explicitly disables one or the other using spring.cloud.function.stream.{source,sink}.enabled=false.

An incoming message is routed to a function (or consumer). If there is only one, then the choice is obvious. If there are multiple functions that can accept an incoming message, the message is inspected to see if there is a stream_routekey header containing the name of a function. Routing headers or function names can be composed using a comma- or pipe-separated name. The header is also added to outgoing messages from a supplier. Messages with no route key can be routed exclusively to a function or consumer by specifying spring.cloud.function.stream.{processor,sink}.name. If a single function cannot be identified to process an incoming message there will be an error, unless you set spring.cloud.function.stream.shared=true, in which case such messages will be sent to all compatible functions. A single supplier can be chosen for output messages from a supplier (if more than one is available) using the spring.cloud.function.stream.source.name.

[Note]Note

some binders will fail on startup if the message broker is not available and the function catalog contains suppliers that immediately produce messages when accessed. You can switch off the automatic publishing from suppliers on startup using the spring.cloud.function.strean.supplier.enabled=false flag.

7. Deploying a Packaged Function

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 Riff Java function invoker uses this library).

The standard entry point of the API is the Spring configuration annotation @EnableFunctionDeployer. If that is used in a Spring Boot application 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 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).

8. Dynamic Compilation

There is a sample app that uses the function compiler to create a +function from a configuration property. The vanilla "function-sample" +also has that feature. And there are some scripts that you can run to +see the compilation happening at run time. To run these examples, +change into the scripts directory:

cd scripts

Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server).

Start the Function Registry Service:

./function-registry.sh

Register a Function:

./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())"

Run a REST Microservice using that Function:

./web.sh -f uppercase -p 9000
+curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo

Register a Supplier:

./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")"

Run a REST Microservice using that Supplier:

./web.sh -s words -p 9001
+curl -H "Accept: application/json" localhost:9001/words

Register a Consumer:

./registerConsumer.sh -n print -t String -f "System.out::println"

Run a REST Microservice using that Consumer:

./web.sh -c print -p 9002
+curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print

Run Stream Processing Microservices:

First register a streaming words supplier:

./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)"

Then start the source (supplier), processor (function), and sink (consumer) apps +(in reverse order):

./stream.sh -p 9103 -i uppercaseWords -c print
+./stream.sh -p 9102 -i words -f uppercase -o uppercaseWords
+./stream.sh -p 9101 -s wordstream -o words

The output will appear in the console of the sink app (one message per second, converted to uppercase):

MESSAGE-0
+MESSAGE-1
+MESSAGE-2
+MESSAGE-3
+MESSAGE-4
+MESSAGE-5
+MESSAGE-6
+MESSAGE-7
+MESSAGE-8
+MESSAGE-9
+...

9. Serverless Platform Adapters

As well as being able to run as a standalone process, a Spring Cloud Function application can be adapted to run one of the existing serverless platforms. In the project there are adapters for AWS @@ -111,7 +111,7 @@ has its own Spring Cloud Function adapter. And Java Function Invoker acts natively is an adapter for Spring Cloud Function jars.

9.1 AWS Lambda

The AWS adapter takes a Spring Cloud Function app and converts it to a form that can run in AWS Lambda.

9.1.1 Introduction

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).

9.1.2 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 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 aws classifier for deploying in Lambda, and one executable (thin) jar that includes spring-cloud-function-web at runtime. Spring Cloud Function will try and locate a "main class" for you from the JAR file manifest, using the Start-Class attribute (which will be added for you by the Spring Boot tooling if you use the starter parent). If there is no Start-Class in your manifest you can use an environment variable MAIN_CLASS when you deploy the function to AWS.

9.1.3 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).

./mvnw -U clean package

Using the AWS command line tools it looks like this:

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-1.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

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:

{
   "value": "test"
-}

9.2 Azure Functions

The 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 Spring Cloud Function Azure adapter trades the convenience of these annotations for portability of the function implementations. Instead of using the annotations you have to write some JSON by hand (at least for now) to guide the platform to call the right methods in the adapter.

The adapter has a generic http request handler that you can use. +}

9.1.4 Platfom Specific Features

HTTP and API Gateway

AWS has some platform-specific data types, including batching of messages, which is much more efficient than processing each one individually. To make use of these types you can write a function that depends on those types. Or you can rely on Spring to extract the data from the AWS types and convert it to a Spring Message. To do this you tell AWS that the function is of a specific generic handler type (depending on the AWS service) and provide a bean of type Function<Message<S>,Message<T>>, where S and T are your business data types. If there is more than one bean of type Function you may also need to configure the Spring Boot property function.name to be the name of the target bean (e.g. use FUNCTION_NAME as an environment variable).

The supported AWS services and generic handler types are listed below:

ServiceAWS TypesGeneric Handler 

API Gateway

APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent

org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler

 

Kinesis

KinesisEvent

org.springframework.cloud.function.adapter.aws.SpringBootKinesisEventHandler

 

For example, to deploy behind an API Gateway, use --handler org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler in your AWS command line (in via the UI) and define a @Bean of type Function<Message<Foo>,Message<Bar>> where Foo and Bar are POJO types (the data will be marshalled and unmarshalled by AWS using Jackson).

9.2 Azure Functions

The 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 Spring Cloud Function Azure adapter trades the convenience of these annotations for portability of the function implementations. Instead of using the annotations you have to write some JSON by hand (at least for now) to guide the platform to call the right methods in the adapter.

The adapter has a generic http request handler that you can use. There is a AzureSpringBootRequestHandler which you must extend, and provide the input and output types as type parameters (enabling Azure 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. The functions are extracted from the Spring Cloud FunctionCatalog.

9.2.1 Notes on JAR Layout

You don’t need the Spring Cloud Function Web at runtime in Azure, so you need to exclude this before you create the JAR you deploy to Azure. A function application on Azure 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 here). diff --git a/spring-cloud-function.xml b/spring-cloud-function.xml index 655839b3e..61a5801a0 100644 --- a/spring-cloud-function.xml +++ b/spring-cloud-function.xml @@ -117,69 +117,6 @@ one-per-jar. It’s up to the developer to choose. An app with multiple functions can be deployed multiple times in different "personalities", exposing different functions over different physical transports. - -Dynamic Compilation -There is a sample app that uses the function compiler to create a -function from a configuration property. The vanilla "function-sample" -also has that feature. And there are some examples that you can run to -see the compilation happening at run time. To run these examples, -change into the scripts directory: -cd scripts -Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server). -

-Start the Function Registry Service: -./function-registry.sh -
-
-Register a Function: -./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())" -
-
-Run a REST Microservice using that Function: -./web.sh -f uppercase -p 9000 -curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo -
-
-Register a Supplier: -./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")" -
-
-Run a REST Microservice using that Supplier: -./web.sh -s words -p 9001 -curl -H "Accept: application/json" localhost:9001/words -
-
-Register a Consumer: -./registerConsumer.sh -n print -t String -f "System.out::println" -
-
-Run a REST Microservice using that Consumer: -./web.sh -c print -p 9002 -curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print -
-
-Run Stream Processing Microservices: -First register a streaming words supplier: -./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)" -Then start the source (supplier), processor (function), and sink (consumer) apps -(in reverse order): -./stream.sh -p 9103 -i uppercaseWords -c print -./stream.sh -p 9102 -i words -f uppercase -o uppercaseWords -./stream.sh -p 9101 -s wordstream -o words -The output will appear in the console of the sink app (one message per second, converted to uppercase): -MESSAGE-0 -MESSAGE-1 -MESSAGE-2 -MESSAGE-3 -MESSAGE-4 -MESSAGE-5 -MESSAGE-6 -MESSAGE-7 -MESSAGE-8 -MESSAGE-9 -... -
- Function Catalog and Flexible Function Signatures One of the main features of Spring Cloud Function is to adapt and @@ -357,6 +294,53 @@ plain text and JSON. 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 Riff Java function invoker uses this library). The standard entry point of the API is the Spring configuration annotation @EnableFunctionDeployer. If that is used in a Spring Boot application 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 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). + +Dynamic Compilation +There is a sample app that uses the function compiler to create a +function from a configuration property. The vanilla "function-sample" +also has that feature. And there are some scripts that you can run to +see the compilation happening at run time. To run these examples, +change into the scripts directory: +cd scripts +Also, start a RabbitMQ server locally (e.g. execute rabbitmq-server). +Start the Function Registry Service: +./function-registry.sh +Register a Function: +./registerFunction.sh -n uppercase -f "f->f.map(s->s.toString().toUpperCase())" +Run a REST Microservice using that Function: +./web.sh -f uppercase -p 9000 +curl -H "Content-Type: text/plain" -H "Accept: text/plain" localhost:9000/uppercase -d foo +Register a Supplier: +./registerSupplier.sh -n words -f "()->Flux.just(\"foo\",\"bar\")" +Run a REST Microservice using that Supplier: +./web.sh -s words -p 9001 +curl -H "Accept: application/json" localhost:9001/words +Register a Consumer: +./registerConsumer.sh -n print -t String -f "System.out::println" +Run a REST Microservice using that Consumer: +./web.sh -c print -p 9002 +curl -X POST -H "Content-Type: text/plain" -d foo localhost:9002/print +Run Stream Processing Microservices: +First register a streaming words supplier: +./registerSupplier.sh -n wordstream -f "()->Flux.interval(Duration.ofMillis(1000)).map(i->\"message-\"+i)" +Then start the source (supplier), processor (function), and sink (consumer) apps +(in reverse order): +./stream.sh -p 9103 -i uppercaseWords -c print +./stream.sh -p 9102 -i words -f uppercase -o uppercaseWords +./stream.sh -p 9101 -s wordstream -o words +The output will appear in the console of the sink app (one message per second, converted to uppercase): +MESSAGE-0 +MESSAGE-1 +MESSAGE-2 +MESSAGE-3 +MESSAGE-4 +MESSAGE-5 +MESSAGE-6 +MESSAGE-7 +MESSAGE-8 +MESSAGE-9 +... + Serverless Platform Adapters As well as being able to run as a standalone process, a Spring Cloud @@ -395,6 +379,45 @@ Invoker acts natively is an adapter for Spring Cloud Function jars. +
+Platfom Specific Features +
+HTTP and API Gateway +AWS has some platform-specific data types, including batching of messages, which is much more efficient than processing each one individually. To make use of these types you can write a function that depends on those types. Or you can rely on Spring to extract the data from the AWS types and convert it to a Spring Message. To do this you tell AWS that the function is of a specific generic handler type (depending on the AWS service) and provide a bean of type Function<Message<S>,Message<T>>, where S and T are your business data types. If there is more than one bean of type Function you may also need to configure the Spring Boot property function.name to be the name of the target bean (e.g. use FUNCTION_NAME as an environment variable). +The supported AWS services and generic handler types are listed below: + + + + + + + + +Service +AWS Types +Generic Handler + + + + + +API Gateway +APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent +org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler + + + +Kinesis +KinesisEvent +org.springframework.cloud.function.adapter.aws.SpringBootKinesisEventHandler + + + + + +For example, to deploy behind an API Gateway, use --handler org.springframework.cloud.function.adapter.aws.SpringBootApiGatewayRequestHandler in your AWS command line (in via the UI) and define a @Bean of type Function<Message<Foo>,Message<Bar>> where Foo and Bar are POJO types (the data will be marshalled and unmarshalled by AWS using Jackson). +
+
Azure Functions