From 080b708de176e93371270910947b0f0a712eed58 Mon Sep 17 00:00:00 2001 From: Oleg Zhurakousky Date: Mon, 12 Aug 2019 19:03:07 +0200 Subject: [PATCH] Adjusted docs to benefit from recent s-c-build improvements --- docs/pom.xml | 319 +----------------- .../src/main/asciidoc/adapters/aws-intro.adoc | 19 +- docs/src/main/asciidoc/adapters/aws.adoc | 3 - .../main/asciidoc/adapters/azure-intro.adoc | 15 +- docs/src/main/asciidoc/adapters/azure.adoc | 3 - .../src/main/asciidoc/adapters/openwhisk.adoc | 3 - docs/src/main/asciidoc/home.adoc | 21 -- docs/src/main/asciidoc/index.adoc | 22 +- .../main/asciidoc/spring-cloud-function.adoc | 21 +- .../deployer/EnableFunctionDeployer.java | 42 +++ 10 files changed, 115 insertions(+), 353 deletions(-) delete mode 100644 docs/src/main/asciidoc/home.adoc mode change 120000 => 100644 docs/src/main/asciidoc/index.adoc create mode 100644 spring-cloud-function-deployer/src/main/java/org/springframework/cloud/function/deployer/EnableFunctionDeployer.java diff --git a/docs/pom.xml b/docs/pom.xml index 56c0fcacd..bd9b3c695 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -15,337 +15,50 @@ spring-cloud-function ${basedir}/.. - 0.1.1.RELEASE - 0.1.0.RELEASE - - 1.5.0-alpha.16 - ${main.basedir}/spring-cloud-function-adapters + 3.4 + + + + maven-deploy-plugin + 2.8.2 + + true + + + + docs + + pl.project13.maven + git-commit-id-plugin + org.apache.maven.plugins maven-dependency-plugin - ${maven-dependency-plugin.version} - false - - - unpack-docs - generate-resources - - unpack - - - - - org.springframework.cloud - - spring-cloud-build-docs - - ${spring-cloud-build.version} - - sources - jar - false - ${docs.resources.dir} - - - - - - - unpack-docs-resources - generate-resources - - unpack - - - - - io.spring.docresources - spring-doc-resources - ${spring-doc-resources.version} - zip - true - ${project.build.directory}/refdocs/ - - - - - org.apache.maven.plugins maven-resources-plugin - - - copy-asciidoc-resources - generate-resources - - copy-resources - - - ${project.build.directory}/refdocs/ - - - src/main/asciidoc - false - - ghpages.sh - - - - - - - org.asciidoctor asciidoctor-maven-plugin ${asciidoctor-maven-plugin.version} - false - - - io.spring.asciidoctor - spring-asciidoctor-extensions - ${spring-asciidoctor-extensions.version} - - - org.asciidoctor - asciidoctorj-pdf - ${asciidoctorj-pdf.version} - - ${project.build.directory}/refdocs/ ${project.version} - https://cloud.spring.io/ - - - - - - generate-html-documentation - prepare-package - - process-asciidoc - - - html5 - highlight.js - book - - // these attributes are required to use the doc resources - shared - css/ - spring.css - true - font - js/highlight - atom-one-dark-reasonable - true - - left - 4 - ${project.version} - true - - - - - generate-docbook - none - - process-asciidoc - - - - generate-index - none - - process-asciidoc - - - - - org.apache.maven.plugins maven-antrun-plugin - ${maven-antrun-plugin.version} - - - ant-contrib - ant-contrib - 1.0b3 - - - ant - ant - - - - - org.apache.ant - ant-nodeps - 1.8.1 - - - org.tigris.antelope - antelopetasks - 3.2.10 - - - org.jruby - jruby-complete - 1.7.17 - - - org.asciidoctor - asciidoctorj - 1.5.8 - - - - - readme - process-resources - - run - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - assert-no-unresolved-links - prepare-package - - run - - - - - - - - - - - - - - - - setup-maven-properties - validate - - run - - - true - - - - - - - - - - - - - - - - - - copy-css - none - - run - - - - generate-documentation-index - none - - run - - - - copy-generated-html - none - - run - - - - - - - - org.codehaus.mojo - build-helper-maven-plugin - false diff --git a/docs/src/main/asciidoc/adapters/aws-intro.adoc b/docs/src/main/asciidoc/adapters/aws-intro.adoc index fdb5f8445..96b18bc41 100644 --- a/docs/src/main/asciidoc/adapters/aws-intro.adoc +++ b/docs/src/main/asciidoc/adapters/aws-intro.adoc @@ -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 ---- -== 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 <>. 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`. In this case diff --git a/docs/src/main/asciidoc/adapters/aws.adoc b/docs/src/main/asciidoc/adapters/aws.adoc index ca70f8a5b..87313101e 100644 --- a/docs/src/main/asciidoc/adapters/aws.adoc +++ b/docs/src/main/asciidoc/adapters/aws.adoc @@ -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. diff --git a/docs/src/main/asciidoc/adapters/azure-intro.adoc b/docs/src/main/asciidoc/adapters/azure-intro.adoc index e5479dae2..c0cad6cde 100644 --- a/docs/src/main/asciidoc/adapters/azure-intro.adoc +++ b/docs/src/main/asciidoc/adapters/azure-intro.adoc @@ -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` bean (or a `Function

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: diff --git a/docs/src/main/asciidoc/adapters/azure.adoc b/docs/src/main/asciidoc/adapters/azure.adoc index efbb65533..4500c751b 100644 --- a/docs/src/main/asciidoc/adapters/azure.adoc +++ b/docs/src/main/asciidoc/adapters/azure.adoc @@ -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. diff --git a/docs/src/main/asciidoc/adapters/openwhisk.adoc b/docs/src/main/asciidoc/adapters/openwhisk.adoc index 2c5d35118..bc9df457d 100644 --- a/docs/src/main/asciidoc/adapters/openwhisk.adoc +++ b/docs/src/main/asciidoc/adapters/openwhisk.adoc @@ -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. diff --git a/docs/src/main/asciidoc/home.adoc b/docs/src/main/asciidoc/home.adoc deleted file mode 100644 index 96aabfa75..000000000 --- a/docs/src/main/asciidoc/home.adoc +++ /dev/null @@ -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 Reference -<> :: AWS Adapter Reference -<> :: Azure Adapter Reference -<> :: Apache OpenWhisk Adapter Reference - - -Relevant Links: - -[horizontal] -https://projectreactor.io/[Reactor] :: Project Reactor -https://projectriff.io/[riff] :: Project riff diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc deleted file mode 120000 index 58aa1344f..000000000 --- a/docs/src/main/asciidoc/index.adoc +++ /dev/null @@ -1 +0,0 @@ -spring-cloud-function.adoc \ No newline at end of file diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc new file mode 100644 index 000000000..96aabfa75 --- /dev/null +++ b/docs/src/main/asciidoc/index.adoc @@ -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 Reference +<> :: AWS Adapter Reference +<> :: Azure Adapter Reference +<> :: Apache OpenWhisk Adapter Reference + + +Relevant Links: + +[horizontal] +https://projectreactor.io/[Reactor] :: Project Reactor +https://projectriff.io/[riff] :: Project riff diff --git a/docs/src/main/asciidoc/spring-cloud-function.adoc b/docs/src/main/asciidoc/spring-cloud-function.adoc index b1ebe0816..5bcff77e9 100644 --- a/docs/src/main/asciidoc/spring-cloud-function.adoc +++ b/docs/src/main/asciidoc/spring-cloud-function.adoc @@ -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 + + org.springframework.cloud + spring-cloud-function-deployer + ${spring.cloud.function.version} + +``` + + +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[] + diff --git a/spring-cloud-function-deployer/src/main/java/org/springframework/cloud/function/deployer/EnableFunctionDeployer.java b/spring-cloud-function-deployer/src/main/java/org/springframework/cloud/function/deployer/EnableFunctionDeployer.java new file mode 100644 index 000000000..233dfc223 --- /dev/null +++ b/spring-cloud-function-deployer/src/main/java/org/springframework/cloud/function/deployer/EnableFunctionDeployer.java @@ -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 { + +}