diff --git a/docs/src/main/asciidoc/binders.adoc b/docs/src/main/asciidoc/binders.adoc index 4747fac34..d023f380c 100644 --- a/docs/src/main/asciidoc/binders.adoc +++ b/docs/src/main/asciidoc/binders.adoc @@ -3,7 +3,7 @@ [[binders]] == Binder Implementations -The following is the list of available binder implementations +The following binder implementations are available: * https://cloud.spring.io/spring-cloud-stream-binder-rabbit/[RabbitMQ] * https://cloud.spring.io/spring-cloud-stream-binder-kafka/[Apache Kafka] diff --git a/docs/src/main/asciidoc/ghpages.sh b/docs/src/main/asciidoc/ghpages.sh index 2562c7171..375ce6c4a 100755 --- a/docs/src/main/asciidoc/ghpages.sh +++ b/docs/src/main/asciidoc/ghpages.sh @@ -4,7 +4,7 @@ set -e # Set default props like MAVEN_PATH, ROOT_FOLDER etc. function set_default_props() { - # The script should be executed from the root folder + # The script should be run from the root folder ROOT_FOLDER=`pwd` echo "Current folder is ${ROOT_FOLDER}" @@ -65,7 +65,7 @@ function build_docs_if_applicable() { } # Get the name of the `docs.main` property -# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +# Get allowed branches - assumes that a `docs` module is available under `docs` profile function retrieve_doc_properties() { MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ -Dexec.executable="echo" \ @@ -75,14 +75,14 @@ function retrieve_doc_properties() { echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" - WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} - WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + ALLOW_PROPERTY=${ALLOW_PROPERTY:-"docs.allowed.branches"} + ALLOWED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ -Dexec.executable="echo" \ - -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + -Dexec.args="\${${ALLOW_PROPERTY}}" \ org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ -P docs \ -pl docs) - echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" + echo "Extracted '${ALLOW_PROPERTY}' from Maven build [${ALLOWED_BRANCHES_VALUE}]" } # Stash any outstanding changes @@ -148,9 +148,9 @@ function copy_docs_for_current_version() { else echo -e "Current branch is [${CURRENT_BRANCH}]" # https://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin - if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + if [[ ",${ALLOWED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} - echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + echo -e "Branch [${CURRENT_BRANCH}] is allowed! Will copy the current docs to the [${CURRENT_BRANCH}] folder" for f in docs/target/generated-docs/*; do file=${f#docs/target/generated-docs/*} if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then @@ -169,7 +169,7 @@ function copy_docs_for_current_version() { done COMMIT_CHANGES="yes" else - echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + echo -e "Branch [${CURRENT_BRANCH}] is not on the allow list! Check out the Maven [${ALLOW_PROPERTY}] property in [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." fi fi @@ -250,10 +250,10 @@ the script will work in the following manner: - if there's no gh-pages / target for docs module then the script ends - for master branch the generated docs are copied to the root of gh-pages branch -- for any other branch (if that branch is whitelisted) a subfolder with branch name is created +- for any other branch (if that branch is allowed) a subfolder with branch name is created and docs are copied there - if the version switch is passed (-v) then a tag with (v) prefix will be retrieved and a folder - with that version number will be created in the gh-pages branch. WARNING! No whitelist verification will take place + with that version number will be created in the gh-pages branch. WARNING! No allow verification will take place - if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will switch to gh-pages of that repo and copy the generated docs to `docs//` - if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will @@ -327,4 +327,4 @@ build_docs_if_applicable retrieve_doc_properties stash_changes add_docs_from_target -checkout_previous_branch \ No newline at end of file +checkout_previous_branch diff --git a/docs/src/main/asciidoc/spring-cloud-stream.adoc b/docs/src/main/asciidoc/spring-cloud-stream.adoc index 710f81c59..064cec3d4 100644 --- a/docs/src/main/asciidoc/spring-cloud-stream.adoc +++ b/docs/src/main/asciidoc/spring-cloud-stream.adoc @@ -28,11 +28,11 @@ Spring Cloud Stream is a framework for building message-driven microservice appl Spring Cloud Stream builds upon Spring Boot to create standalone, production-grade Spring applications and uses Spring Integration to provide connectivity to message brokers. It provides opinionated configuration of middleware from several vendors, introducing the concepts of persistent publish-subscribe semantics, consumer groups, and partitions. -By simply adding spring-cloud-stream dependencies to the classpath of your application you'll get immediate connectivity -to a message broker exposed via provided spring-cloud-stream binder (more on that later), and you can implement your functional -requirement that will be executed based on the incoming message using simple `java.util.function.Function` +By adding `spring-cloud-stream` dependencies to the classpath of your application, you get immediate connectivity +to a message broker exposed by the provided `spring-cloud-stream` binder (more on that later), and you can implement your functional +requirement, which is run (based on the incoming message) by a `java.util.function.Function`. -Here is a quick example: +The following listing shows a quick example: [source,java] ---- @@ -50,7 +50,7 @@ public class SampleApplication { } ---- -and corresponding test +The following listing shows the corresponding test: [source,java] ---- @@ -580,7 +580,7 @@ the produced Flux without splitting it. ===== Consumer (Reactive) Reactive `Consumer` is a little bit special because it has a void return type, leaving framework with no reference to subscribe to. -Most likely you will not need to write `Consumer>`, and instead write it as a `Function, Mono>` invoking `then` +Most likely you will not need to write `Consumer>`, and instead write it as a `Function, Mono>` invoking `then` operator as the last operator on your stream. For example: @@ -619,8 +619,8 @@ source of the data may be a classic REST endpoint. How do we bridge such source Spring Cloud Stream provides two mechanisms, so let's look at them in more details -Here, for both samples we'll use a standard MVC endpoint method called `delegateToSupplier` bound to the root web context, -delegating incoming requests to stream via two different mechanisms - +Here, for both samples we'll use a standard MVC endpoint method called `delegateToSupplier` bound to the root web context, +delegating incoming requests to stream via two different mechanisms - imperative (via StreamBridge) and reactive (via EmitterProcessor). ====== Using StreamBridge @@ -647,24 +647,24 @@ public class WebSourceApplication { } ---- -Here we autowire a `StreamBridge` bean which allows us to send data to an output binding effectively -bridging non-stream application with spring-cloud-stream. Note that preceding example does not have any -source functions defined (e.g., Supplier bean) leaving the framework with no trigger to create source bindings, which would be typical for cases where +Here we autowire a `StreamBridge` bean which allows us to send data to an output binding effectively +bridging non-stream application with spring-cloud-stream. Note that preceding example does not have any +source functions defined (e.g., Supplier bean) leaving the framework with no trigger to create source bindings, which would be typical for cases where configuration contains function beans. So to trigger the creation of source binding we use `spring.cloud.stream.source` property where you can declare the name of your sources. -The provided name will be used as a trigger to create a source binding. -So in the preceding example the name of the output binding will be `toStream-out-0` which is consistent with the binding naming -convention used by functions (see <>). You can use `;` to signify multiple sources +The provided name will be used as a trigger to create a source binding. +So in the preceding example the name of the output binding will be `toStream-out-0` which is consistent with the binding naming +convention used by functions (see <>). You can use `;` to signify multiple sources (e.g., `--spring.cloud.stream.source=foo;bar`) -Also, note that `streamBridge.send(..)` method takes an `Object` for data. This means you can send POJO or `Message` to it and it -will go through the same routine when sending output as if it was from any Function or Supplier providing the same level +Also, note that `streamBridge.send(..)` method takes an `Object` for data. This means you can send POJO or `Message` to it and it +will go through the same routine when sending output as if it was from any Function or Supplier providing the same level of consistency as with functions. This means the output type conversion, partitioning etc are honored as if it was from the output produced by functions. ====== StreamBridge and Dynamic Destinations -`StreamBridge` can also be used for cases when output destination(s) are not known ahead of time similar to the use cases -described in <> section. +`StreamBridge` can also be used for cases when output destination(s) are not known ahead of time similar to the use cases +described in <> section. Let's look at the example @@ -690,8 +690,8 @@ public class WebSourceApplication { } ---- -As you can see the preceding example is very similar to the previous one with the exception of explicit binding instruction provided via -`spring.cloud.stream.source` property (which is not provided). +As you can see the preceding example is very similar to the previous one with the exception of explicit binding instruction provided via +`spring.cloud.stream.source` property (which is not provided). Here we're sending data to `myDestination` name which does not exist as a binding. Therefore such name will be treated as dynamic destination as described in <> section. @@ -701,8 +701,8 @@ Another approach that can be used to send arbitrary data to the output is using All we need to do is declare a `Supplier>` which returns https://projectreactor.io/docs/core/release/api/reactor/core/publisher/EmitterProcessor.html[EmitterProcessor] from the reactor API (see <> for more details) to effectively provide a -bridge between the actual event source (_foreign source_) and spring-cloud-stream. -All you need to do now is feed the `EmitterProcessor` with data via `EmitterProcessor#onNext(data)` operation. +bridge between the actual event source (_foreign source_) and spring-cloud-stream. +All you need to do now is feed the `EmitterProcessor` with data via `EmitterProcessor#onNext(data)` operation. For example, @@ -1454,7 +1454,7 @@ Applications can do so in one of two ways. The `BinderAwareChannelResolver` is a special bean registered automatically by the framework. You can autowire this bean into your application and use it to resolve output destination at runtime -The 'spring.cloud.stream.dynamicDestinations' property can be used for restricting the dynamic destination names to a known set (whitelisting). +The 'spring.cloud.stream.dynamicDestinations' property can be used for restricting the dynamic destination names to a known set (that is, intentionally allowed values). If this property is not set, any destination can be bound dynamically. The following example demonstrates one of the common scenarios where REST controller uses a path variable to determine target destination: @@ -2413,7 +2413,7 @@ public MessageSourceCustomizer sourceCustomizer() { These properties are exposed via `org.springframework.cloud.stream.binder.ProducerProperties` -The following binding properties are available for output bindings only and must be prefixed with `spring.cloud.stream.bindings..producer.` +The following binding properties are available for output bindings only and must be prefixed with `spring.cloud.stream.bindings..producer.` (for example, `spring.cloud.stream.bindings.func-out-0.producer.partitionKeyExpression=payload.id`). Default values can be set by using the prefix `spring.cloud.stream.default.producer` (for example, `spring.cloud.stream.default.producer.partitionKeyExpression=payload.id`). @@ -2890,7 +2890,7 @@ public void sampleTest() { } ---- -For cases where you have multiple bindings and/or multiple inputs and outputs, or simply want to be explicit about names of +For cases where you have multiple bindings and/or multiple inputs and outputs, or simply want to be explicit about names of the destination you are sending to or receiving from, the `send()` and `receive()` methods of `InputDestination` and `OutputDestination` are overridden to allow you to provide the name of the input and output destination. @@ -3160,4 +3160,3 @@ As it was mentioned earlier Binder abstraction is also one of the extension poin In the https://medium.com/@domenicosibilio/how-to-create-a-spring-cloud-stream-binder-from-scratch-ab8b29ee931b[How to create a Spring Cloud Stream Binder from scratch] post a community member documents in details, with an example, a set of steps necessary to implement a custom binder. The steps are also highlighted in the `<>` section. -