Finish doc organization for core and schema-registry
This commit is contained in:
Oleg Zhurakousky
@@ -11,18 +11,43 @@
|
||||
** xref:spring-cloud-stream/programming-model.adoc[]
|
||||
*** xref:spring-cloud-stream/destination-binders.adoc[]
|
||||
*** xref:spring-cloud-stream/bindings.adoc[]
|
||||
*** xref:spring-cloud-stream/binding_visualization_control.adoc[]
|
||||
*** xref:spring-cloud-stream/producing-and-consuming-messages.adoc[]
|
||||
*** xref:spring-cloud-stream/event-routing.adoc[]
|
||||
*** xref:spring-cloud-stream/post-processing-after-sending-message.adoc[]
|
||||
*** xref:spring-cloud-stream/overview-error-handling.adoc[]
|
||||
** xref:spring-cloud-stream/binders.adoc[]
|
||||
*** xref:spring-cloud-stream/overview-binder-api.adoc[A pluggable Binder SPI]
|
||||
*** xref:spring-cloud-stream/binder-detection.adoc[]
|
||||
*** xref:spring-cloud-stream/multiple-binders.adoc[]
|
||||
*** xref:spring-cloud-stream/multiple-systems.adoc[]
|
||||
*** xref:spring-cloud-stream/binder-customizer.adoc[]
|
||||
** xref:spring-cloud-stream/configuration-options.adoc[]
|
||||
*** xref:spring-cloud-stream/binding-service-properties.adoc[]
|
||||
*** xref:spring-cloud-stream/binding-properties.adoc[]
|
||||
** xref:spring-cloud-stream/content-type.adoc[]
|
||||
*** xref:spring-cloud-stream/mechanics.adoc[]
|
||||
*** xref:spring-cloud-stream/provided-messageconverters.adoc[]
|
||||
*** xref:spring-cloud-stream/overview-user-defined-message-converters.adoc[]
|
||||
** xref:spring-cloud-stream/application-communication.adoc[]
|
||||
*** xref:spring-cloud-stream/overview-connecting-multiple-application-instances.adoc[Connecting Multiple Application Instances]
|
||||
*** xref:spring-cloud-stream/overview-instance-index-instance-count.adoc[Instance Index and Instance Count]
|
||||
** xref:spring-cloud-stream/overview-partitioning.adoc[Partitioning]
|
||||
** xref:spring-cloud-stream/spring_integration_test_binder.adoc[]
|
||||
** xref:spring-cloud-stream/health-indicator.adoc[]
|
||||
** xref:spring-cloud-stream/samples.adoc[]
|
||||
|
||||
* Binders
|
||||
** Apache Kafka
|
||||
*** Kafka Binder
|
||||
**** xref:kafka/kafka_dlq.adoc[]
|
||||
*** Kafka Stream Binder
|
||||
*** Reactive Kafka Binder
|
||||
** RabbitMQ
|
||||
** Apache Pulsar
|
||||
** https://github.com/SolaceProducts/solace-spring-cloud/tree/master/solace-spring-cloud-starters/solace-spring-cloud-stream-starter#spring-cloud-stream-binder-for-solace-pubsub[Solace]
|
||||
** https://github.com/spring-cloud/spring-cloud-stream-binder-aws-kinesis/blob/main/spring-cloud-stream-binder-kinesis-docs/src/main/asciidoc/overview.adoc[Amazon Kinesis]
|
||||
* xref:schema-registry/spring-cloud-stream-schema-registry.adoc[]
|
||||
|
||||
|
||||
#** xref:spring-cloud-stream/overview-application-model.adoc[]
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[inter-application-communication]]
|
||||
= Inter-Application Communication
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
Spring Cloud Stream enables communication between applications. Inter-application communication is a complex issue spanning several concerns, as described in the following topics:
|
||||
@@ -256,21 +256,3 @@ public interface ProducerMessageHandlerCustomizer<H extends MessageHandler> {
|
||||
|
||||
As you can see it gives you access to an actual instance of producing `MessageHandler` which you can configure as you wish.
|
||||
All you need to do is provide implementation of this strategy and configure it as a `@Bean`.
|
||||
|
||||
|
||||
[[content-type-management]]
|
||||
== Content Type Negotiation
|
||||
|
||||
Data transformation is one of the core features of any message-driven microservice architecture. Given that, in Spring Cloud Stream, such data
|
||||
is represented as a Spring `Message`, a message may have to be transformed to a desired shape or size before reaching its destination. This is required for two reasons:
|
||||
|
||||
. To convert the contents of the incoming message to match the signature of the application-provided handler.
|
||||
|
||||
. To convert the contents of the outgoing message to the wire format.
|
||||
|
||||
The wire format is typically `byte[]` (that is true for the Kafka and Rabbit binders), but it is governed by the binder implementation.
|
||||
|
||||
In Spring Cloud Stream, message transformation is accomplished with an `org.springframework.messaging.converter.MessageConverter`.
|
||||
|
||||
NOTE: As a supplement to the details to follow, you may also want to read the following https://spring.io/blog/2018/02/26/spring-cloud-stream-2-0-content-type-negotiation-and-transformation[blog post].
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
[[configuration-options]]
|
||||
= Configuration Options
|
||||
|
||||
Spring Cloud Stream supports general configuration options as well as configuration for bindings and binders.
|
||||
Some binders let additional binding properties support middleware-specific features.
|
||||
|
||||
Configuration options can be provided to Spring Cloud Stream applications through any mechanism supported by Spring Boot.
|
||||
This includes application arguments, environment variables, and YAML or .properties files.
|
||||
@@ -0,0 +1,16 @@
|
||||
[[content-type-management]]
|
||||
= Content Type Negotiation
|
||||
|
||||
Data transformation is one of the core features of any message-driven microservice architecture. Given that, in Spring Cloud Stream, such data
|
||||
is represented as a Spring `Message`, a message may have to be transformed to a desired shape or size before reaching its destination. This is required for two reasons:
|
||||
|
||||
. To convert the contents of the incoming message to match the signature of the application-provided handler.
|
||||
|
||||
. To convert the contents of the outgoing message to the wire format.
|
||||
|
||||
The wire format is typically `byte[]` (that is true for the Kafka and Rabbit binders), but it is governed by the binder implementation.
|
||||
|
||||
In Spring Cloud Stream, message transformation is accomplished with an `org.springframework.messaging.converter.MessageConverter`.
|
||||
|
||||
NOTE: As a supplement to the details to follow, you may also want to read the following https://spring.io/blog/2018/02/26/spring-cloud-stream-2-0-content-type-negotiation-and-transformation[blog post].
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
[[health-indicator]]
|
||||
= Health Indicator
|
||||
|
||||
Spring Cloud Stream provides a health indicator for binders.
|
||||
It is registered under the name `binders` and can be enabled or disabled by setting the `management.health.binders.enabled` property.
|
||||
|
||||
To enable health check you first need to enable both "web" and "actuator" by including its dependencies (see xref:spring-cloud-stream/binding_visualization_control.adoc[Binding visualization and control])
|
||||
|
||||
If `management.health.binders.enabled` is not set explicitly by the application, then `management.health.defaults.enabled` is matched as `true` and the binder health indicators are enabled.
|
||||
If you want to disable health indicator completely, then you have to set `management.health.binders.enabled` to `false`.
|
||||
|
||||
You can use Spring Boot actuator health endpoint to access the health indicator - `/actuator/health`.
|
||||
By default, you will only receive the top level application status when you hit the above endpoint.
|
||||
In order to receive the full details from the binder specific health indicators, you need to include the property `management.endpoint.health.show-details` with the value `ALWAYS` in your application.
|
||||
|
||||
Health indicators are binder-specific and certain binder implementations may not necessarily provide a health indicator.
|
||||
|
||||
If you want to completely disable all health indicators available out of the box and instead provide your own health indicators,
|
||||
you can do so by setting property `management.health.binders.enabled` to `false` and then provide your own `HealthIndicator` beans in your application.
|
||||
In this case, the health indicator infrastructure from Spring Boot will still pick up these custom beans.
|
||||
Even if you are not disabling the binder health indicators, you can still enhance the health checks by providing your own `HealthIndicator` beans in addition to the out of the box health checks.
|
||||
|
||||
When you have multiple binders in the same application, health indicators are enabled by default unless the application turns them off by setting `management.health.binders.enabled` to `false`.
|
||||
In this case, if the user wants to disable health check for a subset of the binders, then that should be done by setting `management.health.binders.enabled` to `false` in the multi binder configurations's environment.
|
||||
See xref:spring-cloud-stream/multiple-systems.adoc[Connecting to Multiple Systems] for details on how environment specific properties can be provided.
|
||||
|
||||
If there are multiple binders present in the classpath but not all of them are used in the application, this may cause some issues in the context of health indicators.
|
||||
There may be implementation specific details as to how the health checks are performed. For example, a Kafka binder may decide the status as `DOWN` if there are no destinations registered by the binder.
|
||||
|
||||
Lets take a concrete situation. Imagine you have both Kafka and Kafka Streams binders present in the classpath, but only use the Kafka Streams binder in the application code, i.e. only provide bindings using the Kafka Streams binder.
|
||||
Since Kafka binder is not used and it has specific checks to see if any destinations are registered, the binder health check will fail.
|
||||
The top level application health check status will be reported as `DOWN`.
|
||||
In this situation, you can simply remove the dependency for kafka binder from your application since you are not using it.
|
||||
@@ -244,13 +244,3 @@ Finally, you must define your binder in a `META-INF/spring.binders` file on the
|
||||
myFileBinder:\
|
||||
com.example.springcloudstreamcustombinder.config.FileMessageBinderConfiguration
|
||||
----
|
||||
|
||||
[[configuration-options]]
|
||||
== Configuration Options
|
||||
|
||||
Spring Cloud Stream supports general configuration options as well as configuration for bindings and binders.
|
||||
Some binders let additional binding properties support middleware-specific features.
|
||||
|
||||
Configuration options can be provided to Spring Cloud Stream applications through any mechanism supported by Spring Boot.
|
||||
This includes application arguments, environment variables, and YAML or .properties files.
|
||||
|
||||
|
||||
@@ -41,13 +41,3 @@ public class MyCustomMessageConverter extends AbstractMessageConverter {
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
[[inter-application-communication]]
|
||||
== Inter-Application Communication
|
||||
|
||||
Spring Cloud Stream enables communication between applications. Inter-application communication is a complex issue spanning several concerns, as described in the following topics:
|
||||
|
||||
* `xref:spring-cloud-stream/overview-connecting-multiple-application-instances.adoc[Connecting Multiple Application Instances]`
|
||||
* `xref:spring-cloud-stream/overview-instance-index-instance-count.adoc[Instance Index and Instance Count]`
|
||||
* `xref:spring-cloud-stream/overview-partitioning.adoc[Partitioning]`
|
||||
|
||||
|
||||
4
docs/modules/ROOT/pages/spring-cloud-stream/samples.adoc
Normal file
4
docs/modules/ROOT/pages/spring-cloud-stream/samples.adoc
Normal file
@@ -0,0 +1,4 @@
|
||||
[[samples]]
|
||||
= Samples
|
||||
|
||||
For Spring Cloud Stream samples, see the https://github.com/spring-cloud/spring-cloud-stream-samples[spring-cloud-stream-samples] repository on GitHub.
|
||||
@@ -1,12 +1,18 @@
|
||||
[[testing]]
|
||||
= Testing
|
||||
|
||||
Spring Cloud Stream provides support for testing your microservice applications without connecting to a messaging system.
|
||||
|
||||
|
||||
[[spring_integration_test_binder]]
|
||||
= Spring Integration Test Binder
|
||||
== Spring Integration Test Binder
|
||||
|
||||
Spring Cloud Stream comes with a test binder which you can use for testing the various application components without requiring an actual real-world binder implementation or a message broker.
|
||||
|
||||
This test binder acts as a bridge between _unit_ and _integration_ testing and is based on https://spring.io/projects/spring-integration[Spring Integration] framework as an in-JVM message broker essentially giving you the best of both worlds - a real binder without the networking.
|
||||
|
||||
[[test-binder-configuration]]
|
||||
== Test Binder configuration
|
||||
=== Test Binder configuration
|
||||
To enable Spring Integration test binder, all you need is to add it as a dependency.
|
||||
|
||||
***Add required dependencies***
|
||||
@@ -30,7 +36,7 @@ testImplementation("org.springframework.cloud:spring-cloud-stream-test-binder")
|
||||
----
|
||||
|
||||
[[test-binder-usage]]
|
||||
== Test Binder usage
|
||||
=== Test Binder usage
|
||||
|
||||
Now you can test your microservice as a simple unit test
|
||||
|
||||
@@ -173,7 +179,7 @@ public void testMultipleFunctions() {
|
||||
|
||||
|
||||
[[test-binder-and-pollablemessagesource]]
|
||||
== Test Binder and PollableMessageSource
|
||||
=== Test Binder and PollableMessageSource
|
||||
Spring Integration Test Binder also allows you to write tests when working with `PollableMessageSource` (see <<Using Polled Consumers>> for more details).
|
||||
|
||||
The important thing that needs to be understood though is that polling is not event-driven, and that `PollableMessageSource` is a strategy which exposes operation to produce (poll for) a Message (singular).
|
||||
@@ -264,42 +270,3 @@ When the test binder is present on the test classpath, Spring Cloud Stream will
|
||||
In other words, you cannot mix both the test binder and a regular middleware binder for testing purposes in the same module.
|
||||
After testing the application with the test binder, if you want to continue doing further integration tests using the actual middleware binder, it is recommended to add those tests that use the actual binder in a separate module so that those tests can make the proper connection to the actual middleware rather than relying on the in-memory channels provided by the test binder.
|
||||
|
||||
[[health-indicator]]
|
||||
== Health Indicator
|
||||
|
||||
Spring Cloud Stream provides a health indicator for binders.
|
||||
It is registered under the name `binders` and can be enabled or disabled by setting the `management.health.binders.enabled` property.
|
||||
|
||||
To enable health check you first need to enable both "web" and "actuator" by including its dependencies (see xref:spring-cloud-stream/binding_visualization_control.adoc[Binding visualization and control])
|
||||
|
||||
If `management.health.binders.enabled` is not set explicitly by the application, then `management.health.defaults.enabled` is matched as `true` and the binder health indicators are enabled.
|
||||
If you want to disable health indicator completely, then you have to set `management.health.binders.enabled` to `false`.
|
||||
|
||||
You can use Spring Boot actuator health endpoint to access the health indicator - `/actuator/health`.
|
||||
By default, you will only receive the top level application status when you hit the above endpoint.
|
||||
In order to receive the full details from the binder specific health indicators, you need to include the property `management.endpoint.health.show-details` with the value `ALWAYS` in your application.
|
||||
|
||||
Health indicators are binder-specific and certain binder implementations may not necessarily provide a health indicator.
|
||||
|
||||
If you want to completely disable all health indicators available out of the box and instead provide your own health indicators,
|
||||
you can do so by setting property `management.health.binders.enabled` to `false` and then provide your own `HealthIndicator` beans in your application.
|
||||
In this case, the health indicator infrastructure from Spring Boot will still pick up these custom beans.
|
||||
Even if you are not disabling the binder health indicators, you can still enhance the health checks by providing your own `HealthIndicator` beans in addition to the out of the box health checks.
|
||||
|
||||
When you have multiple binders in the same application, health indicators are enabled by default unless the application turns them off by setting `management.health.binders.enabled` to `false`.
|
||||
In this case, if the user wants to disable health check for a subset of the binders, then that should be done by setting `management.health.binders.enabled` to `false` in the multi binder configurations's environment.
|
||||
See xref:spring-cloud-stream/multiple-systems.adoc[Connecting to Multiple Systems] for details on how environment specific properties can be provided.
|
||||
|
||||
If there are multiple binders present in the classpath but not all of them are used in the application, this may cause some issues in the context of health indicators.
|
||||
There may be implementation specific details as to how the health checks are performed. For example, a Kafka binder may decide the status as `DOWN` if there are no destinations registered by the binder.
|
||||
|
||||
Lets take a concrete situation. Imagine you have both Kafka and Kafka Streams binders present in the classpath, but only use the Kafka Streams binder in the application code, i.e. only provide bindings using the Kafka Streams binder.
|
||||
Since Kafka binder is not used and it has specific checks to see if any destinations are registered, the binder health check will fail.
|
||||
The top level application health check status will be reported as `DOWN`.
|
||||
In this situation, you can simply remove the dependency for kafka binder from your application since you are not using it.
|
||||
|
||||
[[samples]]
|
||||
== Samples
|
||||
|
||||
For Spring Cloud Stream samples, see the https://github.com/spring-cloud/spring-cloud-stream-samples[spring-cloud-stream-samples] repository on GitHub.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user