Adjusted docs to benefit from recent s-c-build improvements

This commit is contained in:
Oleg Zhurakousky
2019-08-12 19:03:07 +02:00
parent 935ea12263
commit 080b708de1
10 changed files with 115 additions and 353 deletions

View File

@@ -15,337 +15,50 @@
<properties>
<docs.main>spring-cloud-function</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<spring-doc-resources.version>0.1.1.RELEASE</spring-doc-resources.version>
<spring-asciidoctor-extensions.version>0.1.0.RELEASE
</spring-asciidoctor-extensions.version>
<asciidoctorj-pdf.version>1.5.0-alpha.16</asciidoctorj-pdf.version>
<adapters.path>${main.basedir}/spring-cloud-function-adapters</adapters.path>
<maven.plugin.plugin.version>3.4</maven.plugin.plugin.version>
</properties>
<build>
<plugins>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>2.8.2</version>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>docs</id>
<build>
<plugins>
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>${maven-dependency-plugin.version}</version>
<inherited>false</inherited>
<executions>
<execution>
<id>unpack-docs</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.springframework.cloud
</groupId>
<artifactId>spring-cloud-build-docs
</artifactId>
<version>${spring-cloud-build.version}
</version>
<classifier>sources</classifier>
<type>jar</type>
<overWrite>false</overWrite>
<outputDirectory>${docs.resources.dir}
</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
<execution>
<id>unpack-docs-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>io.spring.docresources</groupId>
<artifactId>spring-doc-resources</artifactId>
<version>${spring-doc-resources.version}</version>
<type>zip</type>
<overWrite>true</overWrite>
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-asciidoc-resources</id>
<phase>generate-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
<resources>
<resource>
<directory>src/main/asciidoc</directory>
<filtering>false</filtering>
<excludes>
<exclude>ghpages.sh</exclude>
</excludes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor-maven-plugin.version}</version>
<inherited>false</inherited>
<dependencies>
<dependency>
<groupId>io.spring.asciidoctor</groupId>
<artifactId>spring-asciidoctor-extensions</artifactId>
<version>${spring-asciidoctor-extensions.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj-pdf.version}</version>
</dependency>
</dependencies>
<configuration>
<sourceDirectory>${project.build.directory}/refdocs/</sourceDirectory>
<attributes>
<spring-cloud-function-version>${project.version}</spring-cloud-function-version>
<docs-url>https://cloud.spring.io/</docs-url>
<docs-version></docs-version>
<!-- <docs-url>https://cloud.spring.io/spring-cloud-static/</docs-url> -->
<!-- <docs-version>2.1.0.RC1/</docs-version> -->
</attributes>
</configuration>
<executions>
<execution>
<id>generate-html-documentation</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<doctype>book</doctype>
<attributes>
// these attributes are required to use the doc resources
<docinfo>shared</docinfo>
<stylesdir>css/</stylesdir>
<stylesheet>spring.css</stylesheet>
<linkcss>true</linkcss>
<icons>font</icons>
<highlightjsdir>js/highlight</highlightjsdir>
<highlightjs-theme>atom-one-dark-reasonable</highlightjs-theme>
<allow-uri-read>true</allow-uri-read>
<nofooter />
<toc>left</toc>
<toc-levels>4</toc-levels>
<spring-cloud-version>${project.version}</spring-cloud-version>
<sectlinks>true</sectlinks>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-docbook</id>
<phase>none</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
<execution>
<id>generate-index</id>
<phase>none</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>${maven-antrun-plugin.version}</version>
<dependencies>
<dependency>
<groupId>ant-contrib</groupId>
<artifactId>ant-contrib</artifactId>
<version>1.0b3</version>
<exclusions>
<exclusion>
<groupId>ant</groupId>
<artifactId>ant</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-nodeps</artifactId>
<version>1.8.1</version>
</dependency>
<dependency>
<groupId>org.tigris.antelope</groupId>
<artifactId>antelopetasks</artifactId>
<version>3.2.10</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.17</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>1.5.8</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>readme</id>
<phase>process-resources</phase>
<goals>
<goal>run</goal>
</goals>
<!-- <configuration> -->
<!-- <target> -->
<!-- <java classname="org.jruby.Main" failonerror="yes"> -->
<!-- <arg -->
<!-- value="${docs.resources.dir}/ruby/generate_readme.sh" /> -->
<!-- <arg value="-o" /> -->
<!-- <arg value="${main.basedir}/README.adoc" /> -->
<!-- </java> -->
<!-- <java classname="org.jruby.Main" failonerror="yes"> -->
<!-- <arg -->
<!-- value="${docs.resources.dir}/ruby/generate_readme.sh" /> -->
<!-- <arg value="-o" /> -->
<!-- <arg -->
<!-- value="${adapters.path}/spring-cloud-function-adapter-aws/README.adoc" /> -->
<!-- <arg -->
<!-- value="${basedir}/src/main/asciidoc/adapters/aws-readme.adoc" /> -->
<!-- </java> -->
<!-- <java classname="org.jruby.Main" failonerror="yes"> -->
<!-- <arg -->
<!-- value="${docs.resources.dir}/ruby/generate_readme.sh" /> -->
<!-- <arg value="-o" /> -->
<!-- <arg -->
<!-- value="${adapters.path}/spring-cloud-function-adapter-azure/README.adoc" /> -->
<!-- <arg -->
<!-- value="${basedir}/src/main/asciidoc/adapters/azure-readme.adoc" /> -->
<!-- </java> -->
<!-- <java classname="org.jruby.Main" failonerror="yes"> -->
<!-- <arg -->
<!-- value="${docs.resources.dir}/ruby/generate_readme.sh" /> -->
<!-- <arg value="-o" /> -->
<!-- <arg -->
<!-- value="${adapters.path}/spring-cloud-function-adapter-openwhisk/README.adoc" /> -->
<!-- <arg -->
<!-- value="${basedir}/src/main/asciidoc/adapters/openwhisk-readme.adoc" /> -->
<!-- </java> -->
<!-- </target> -->
<!-- </configuration> -->
</execution>
<execution>
<id>assert-no-unresolved-links</id>
<phase>prepare-package</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<target>
<fileset id="unresolved.file"
dir="${basedir}/target/generated-docs/" includes="**/*.html">
<contains text="Unresolved" />
</fileset>
<fail message="[Unresolved] Found...failing">
<condition>
<resourcecount when="greater" count="0"
refid="unresolved.file" />
</condition>
</fail>
</target>
</configuration>
</execution>
<execution>
<id>setup-maven-properties</id>
<phase>validate</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<exportAntProperties>true</exportAntProperties>
<target>
<taskdef
resource="net/sf/antcontrib/antcontrib.properties" />
<taskdef name="stringutil"
classname="ise.antelope.tasks.StringUtilTask" />
<var name="version-type" value="${project.version}" />
<propertyregex property="version-type"
override="true" input="${version-type}" regexp=".*\.(.*)"
replace="\1" />
<propertyregex property="version-type"
override="true" input="${version-type}" regexp="(M)\d+"
replace="MILESTONE" />
<propertyregex property="version-type"
override="true" input="${version-type}" regexp="(RC)\d+"
replace="MILESTONE" />
<propertyregex property="version-type"
override="true" input="${version-type}" regexp="BUILD-(.*)"
replace="SNAPSHOT" />
<stringutil string="${version-type}"
property="spring-cloud-repo">
<lowercase />
</stringutil>
<var name="github-tag" value="v${project.version}" />
<propertyregex property="github-tag"
override="true" input="${github-tag}" regexp=".*SNAPSHOT"
replace="master" />
</target>
</configuration>
</execution>
<execution>
<id>copy-css</id>
<phase>none</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
<execution>
<id>generate-documentation-index</id>
<phase>none</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
<execution>
<id>copy-generated-html</id>
<phase>none</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<inherited>false</inherited>
</plugin>
</plugins>
</build>

View File

@@ -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

View File

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

View File

@@ -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:

View File

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

View File

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

View File

@@ -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

View File

@@ -1 +0,0 @@
spring-cloud-function.adoc

View 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

View File

@@ -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[]

View File

@@ -0,0 +1,42 @@
/*
* Copyright 2012-2019 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.cloud.function.deployer;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.context.annotation.Import;
/**
* Annotation to be used on a Spring Boot application if it wants to deploy a jar file
* containing a function definition.
* @author Dave Syer
*
* @deprecated since 3.0. No longer required. Deployer will kick in simply by including
* spring-cloud-function-deployer dependency
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(FunctionDeployerConfiguration.class)
@Deprecated
public @interface EnableFunctionDeployer {
}