<commit_before>= Spring Cloud Function

<NAME>, <NAME>

---

:github: https://github.com/spring-cloud/spring-cloud-function
:githubmaster: {github}/tree/master
:docslink: {githubmaster}/docs/src/main/asciidoc
:nofooter:

== Introduction

include::intro.adoc[]

include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[]

== Getting Started

include::getting-started.adoc[]

== 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
`Function<Flux<String>,Flux<String>>`. Users don't normally have to
care about the `FunctionCatalog` at all, but it is useful to know what
kind of functions are supported in user code.

Generally speaking users can expect that if they write a function for
a plain old Java type (or primitive wrapper), then the function
catalog will wrap it to a `Flux` of the same type. If the user writes
a function using `Message` (from spring-messaging) it will receive and
transmit headers from any adapter that supports key-value metadata
(e.g. HTTP headers). Here are the details.

|===
| User Function | Catalog Registration |

| `Function<S,T>` | `Function<Flux<S>, Flux<T>>` |
| `Function<Message<S>,Message<T>>` | `Function<Flux<Message<S>>, Flux<Message<T>>>` |
| `Function<Flux<S>, Flux<T>>` | `Function<Flux<S>, Flux<T>>` (pass through) |
| `Supplier<T>` | `Supplier<Flux<T>>` |
| `Supplier<Flux<T>>` | `Supplier<Flux<T>>` |
| `Consumer<T>` | `Function<Flux<T>, Mono<Void>>` |
| `Consumer<Message<T>>` | `Function<Flux<Message<T>>, Mono<Void>>` |
| `Consumer<Flux<T>>` | `Consumer<Flux<T>>` |

|===

Consumer is a little bit special because it has a `void` return type,
which implies blocking, at least potentially. Most likely you will not
need to write `Consumer<Flux<?>>`, but if you do need to do that,
remember to subscribe to the input flux. If you declare a `Consumer`
of a non publisher type (which is normal), it will be converted to a
function that returns a publisher, so that it can be subscribed to in
a controlled way.

A function catalog can contain a `Supplier` and a `Function` (or
`Consumer`) with the same name (like a GET and a POST to the same
resource). It can even contain a `Consumer<Flux<>>` with the same name
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.

== 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
getting started experience.

With the web configurations activated your app will have an MVC
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.

|===
| Method | Path | Request | Response | Status

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

== 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: 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.

== 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 https://projectriff.io[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`).<commit_msg>GH-194 Fixed Streaming section of the reference manual<commit_after>= Spring Cloud Function

<NAME>, <NAME>, <NAME>

---

:github: https://github.com/spring-cloud/spring-cloud-function
:githubmaster: {github}/tree/master
:docslink: {githubmaster}/docs/src/main/asciidoc
:nofooter:

== Introduction

include::intro.adoc[]

include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[]

== Getting Started

include::getting-started.adoc[]

== 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
`Function<Flux<String>,Flux<String>>`. Users don't normally have to
care about the `FunctionCatalog` at all, but it is useful to know what
kind of functions are supported in user code.

Generally speaking users can expect that if they write a function for
a plain old Java type (or primitive wrapper), then the function
catalog will wrap it to a `Flux` of the same type. If the user writes
a function using `Message` (from spring-messaging) it will receive and
transmit headers from any adapter that supports key-value metadata
(e.g. HTTP headers). Here are the details.

|===
| User Function | Catalog Registration |

| `Function<S,T>` | `Function<Flux<S>, Flux<T>>` |
| `Function<Message<S>,Message<T>>` | `Function<Flux<Message<S>>, Flux<Message<T>>>` |
| `Function<Flux<S>, Flux<T>>` | `Function<Flux<S>, Flux<T>>` (pass through) |
| `Supplier<T>` | `Supplier<Flux<T>>` |
| `Supplier<Flux<T>>` | `Supplier<Flux<T>>` |
| `Consumer<T>` | `Function<Flux<T>, Mono<Void>>` |
| `Consumer<Message<T>>` | `Function<Flux<Message<T>>, Mono<Void>>` |
| `Consumer<Flux<T>>` | `Consumer<Flux<T>>` |

|===

Consumer is a little bit special because it has a `void` return type,
which implies blocking, at least potentially. Most likely you will not
need to write `Consumer<Flux<?>>`, but if you do need to do that,
remember to subscribe to the input flux. If you declare a `Consumer`
of a non publisher type (which is normal), it will be converted to a
function that returns a publisher, so that it can be subscribed to in
a controlled way.

A function catalog can contain a `Supplier` and a `Function` (or
`Consumer`) with the same name (like a GET and a POST to the same
resource). It can even contain a `Consumer<Flux<>>` with the same name
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.

== 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
getting started experience.

With the web configurations activated your app will have an MVC
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.

|===
| Method | Path | Request | Response | Status

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

== Standalone Streaming Applications

To send or receive messages from a broker (such as RabbitMQ or Kafka) you can leverage `spring-cloud-stream` project and it's integration with Spring Cloud Function.
Please refer to https://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/#_spring_cloud_function[Spring Cloud Function] section of the Spring Cloud Stream reference manual for more details and examples.

== 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 https://projectriff.io[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`).
{'fraction_non_alphanumeric': 0.07361111111111111, 'fraction_numerical': 0.0025966183574879227, 'mean_word_length': 4.572341857335128, 'pattern_counts': {'":': 0, '<': 108, '<?xml version=': 0, '>': 108, 'https://': 7, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5908', 'n_tokens_mistral': 4323, 'n_tokens_neox': 4162, 'n_words': 2362}