SpringCloud/spring-cloud-stream
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Migrated to new documentation generation

Browse Source
This commit is contained in:
Marcin Grzejszczak
2020-06-08 18:40:08 +02:00
parent 269656eea4
commit d05bdc3782
3 changed files with 153 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
README.adoc
View File

@@ -4,6 +4,7 @@ Manual changes to this file will be lost when it is generated again.
Edit the files in the src/main/asciidoc/ directory instead.
////
:jdkversion: 1.8
:github-tag: master
:github-repo: spring-cloud/spring-cloud-stream-binder-rabbit
@@ -87,13 +88,13 @@ You can exclude the class by using the `@SpringBootApplication` annotation.
Starting with version 2.0, the `RabbitMessageChannelBinder` sets the `RabbitTemplate.userPublisherConnection` property to `true` so that the non-transactional producers avoid deadlocks on consumers, which can happen if cached connections are blocked because of a https://www.rabbitmq.com/memory.html[memory alarm] on the broker.
NOTE: Currently, a `multiplex` consumer (a single consumer listening to multiple queues) is only supported for message-driven consumers; polled consumers can only retrieve messages from a single queue.
NOTE: Currently, a `multiplex` consumer (a single consumer listening to multiple queues) is only supported for message-driven conssumers; polled consumers can only retrieve messages from a single queue.
== Configuration Options
This section contains settings specific to the RabbitMQ Binder and bound channels.
For general binding configuration options and properties, see the https://github.com/spring-cloud/spring-cloud-stream/blob/master/spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc#configuration-options[Spring Cloud Stream core documentation].
For general binding configuration options and properties, see the https://cloud.spring.io/spring-cloud-static/spring-cloud-stream/current/reference/html/spring-cloud-stream.html#_configuration_options[Spring Cloud Stream core documentation].
[[rabbit-binder-properties]]
=== RabbitMQ Binder Properties
@@ -142,7 +143,6 @@ in the format of `spring.cloud.stream.rabbit.default.<property>=<value>`.
Also, keep in mind that binding specific property will override its equivalent in the default.
acknowledgeMode::
The acknowledge mode.
+
@@ -159,9 +159,14 @@ Whether to automatically declare the DLQ and bind it to the binder DLX.
Default: `false`.
bindingRoutingKey::
The routing key with which to bind the queue to the exchange (if `bindQueue` is `true`).
For partitioned destinations, `-<instanceIndex>` is appended.
Can be multiple keys - see `bindingRoutingKeyDelimiter`.
For partitioned destinations, `-<instanceIndex>` is appended to each key.
+
Default: `#`.
bindingRoutingKeyDelimiter::
When this is not null, 'bindingRoutingKey' is considered to be a list of keys delimited by this value; often a comma is used.
+
Default: `null`.
bindQueue::
Whether to declare the queue and bind it to the destination exchange.
Set it to `false` if you have set up your own infrastructure and have previously created and bound the queue.
@@ -251,6 +256,22 @@ dlqOverflowBehavior::
Action to take when `dlqMaxLength` or `dlqMaxLengthBytes` is exceeded; currently `drop-head` or `reject-publish` but refer to the RabbitMQ documentation.
+
Default: `none`
dlqQuorum.deliveryLimit::
When `quorum.enabled=true`, set a delivery limit after which the message is dropped or dead-lettered.
+
Default: none - broker default will apply.
dlqQuorum.enabled::
When true, create a quorum dead letter queue instead of a classic queue.
+
Default: false
dlqQuorum.initialQuorumSize::
When `quorum.enabled=true`, set the initial quorum size.
+
Default: none - broker default will apply.
dlqSingleActiveConsumer::
Set to true to set the `x-single-active-consumer` queue property to true.
+
Default: `false`
dlqTtl::
Default time to live to apply to the dead letter queue when declared (in milliseconds).
+
@@ -277,6 +298,7 @@ Whether to create an exclusive consumer.
Concurrency should be 1 when this is `true`.
Often used when strict ordering is required but enabling a hot standby instance to take over after a failure.
See `recoveryInterval`, which controls how often a standby instance attempts to consume.
Consider using `singleActiveConsumer` instead when using RabbitMQ 3.8 or later.
+
Default: `false`.
expires::
@@ -357,6 +379,18 @@ Otherwise the queue name is `destination.group`.
This is useful, for example, when using Spring Cloud Stream to consume from an existing RabbitMQ queue.
+
Default: false.
quorum.deliveryLimit::
When `quorum.enabled=true`, set a delivery limit after which the message is dropped or dead-lettered.
+
Default: none - broker default will apply.
quorum.enabled::
When true, create a quorum queue instead of a classic queue.
+
Default: false
quorum.initialQuorumSize::
When `quorum.enabled=true`, set the initial quorum size.
+
Default: none - broker default will apply.
recoveryInterval::
The interval between connection recovery attempts, in milliseconds.
+
@@ -376,7 +410,11 @@ If a dead-letter queue (DLQ) is configured, RabbitMQ routes the failed message (
If set to `true`, the binder republishs failed messages to the DLQ with additional headers, including the exception message and stack trace from the cause of the final failure.
Also see the <<spring-cloud-stream-rabbit-frame-max-headroom, frameMaxHeadroom property>>.
+
Default: true
Default: false
singleActiveConsumer::
Set to true to set the `x-single-active-consumer` queue property to true.
+
Default: `false`
transacted::
Whether to use transacted channels.
+
@@ -397,11 +435,18 @@ To set listener container properties that are not exposed as binder or binding p
The binder and binding properties will be set and then the customizer will be called.
The customizer (`configure()` method) is provided with the queue name as well as the consumer group as arguments.
=== Advanced Queue/Exchange/Binding Configuration
From time to time, the RabbitMQ team add new features that are enabled by setting some argument when declaring, for example, a queue.
Generally, such features are enabled in the binder by adding appropriate properties, but this may not be immediately available in a current version.
Starting with version 3.0.1, you can now add `DeclarableCustomizer` bean(s) to the application context to modify a `Declarable` (`Queue`, `Exchange` or `Binding`) just before the declaration is performed.
This allows you to add arguments that are not currently directly supported by the binder.
[[rabbit-receiving-batch]]
=== Receiving Batched Messages
Normally, if a producer binding has `batch-enabled=true` (see <<rabbit-prod-props>>), or a message is created by a `BatchingRabbitTemplate`, elements of the batch are returned as individual calls to the listener method.
Starting with version 3.0, any such batch can be presented as a `List<?>` to the listener method if `spring.cloud.stream.binding.<name>.consumer.batch-mode` is set to `true`.
Starting with version 3.0, any such batch can be presented as a `List<?>` to the listener method if `spring.cloud.stream.bindings.<name>.consumer.batch-mode` is set to `true`.
[[rabbit-prod-props]]
=== Rabbit Producer Properties
@@ -440,10 +485,16 @@ The batch timeout when batching is enabled.
Default: `5000`.
bindingRoutingKey::
The routing key with which to bind the queue to the exchange (if `bindQueue` is `true`).
Only applies to non-partitioned destinations.
Can be multiple keys - see `bindingRoutingKeyDelimiter`.
For partitioned destinations, `-n` is appended to each key.
Only applies if `requiredGroups` are provided and then only to those groups.
+
Default: `#`.
bindingRoutingKeyDelimiter::
When this is not null, 'bindingRoutingKey' is considered to be a list of keys delimited by this value; often a comma is used.
Only applies if `requiredGroups` are provided and then only to those groups.
+
Default: `null`.
bindQueue::
Whether to declare the queue and bind it to the destination exchange.
Set it to `false` if you have set up your own infrastructure and have previously created and bound the queue.
@@ -551,6 +602,26 @@ Maximum priority of messages in the dead letter queue (0-255)
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: `none`
dlqQuorum.deliveryLimit::
When `quorum.enabled=true`, set a delivery limit after which the message is dropped or dead-lettered.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: none - broker default will apply.
dlqQuorum.enabled::
When true, create a quorum dead letter queue instead of a classic queue.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: false
dlqQuorum.initialQuorumSize::
When `quorum.enabled=true`, set the initial quorum size.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: none - broker default will apply.
dlqSingleActiveConsumer::
Set to true to set the `x-single-active-consumer` queue property to true.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: `false`
dlqTtl::
Default time (in milliseconds) to live to apply to the dead letter queue when declared.
Applies only when `requiredGroups` are provided and then only to those groups.
@@ -616,11 +687,31 @@ This is useful, for example, when using Spring Cloud Stream to consume from an e
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: false.
quorum.deliveryLimit::
When `quorum.enabled=true`, set a delivery limit after which the message is dropped or dead-lettered.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: none - broker default will apply.
quorum.enabled::
When true, create a quorum queue instead of a classic queue.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: false
quorum.initialQuorumSize::
When `quorum.enabled=true`, set the initial quorum size.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: none - broker default will apply.
routingKeyExpression::
A SpEL expression to determine the routing key to use when publishing messages.
For a fixed routing key, use a literal expression, such as `routingKeyExpression='my.routingKey'` in a properties file or `routingKeyExpression: '''my.routingKey'''` in a YAML file.
+
Default: `destination` or `destination-<partition>` for partitioned destinations.
singleActiveConsumer::
Set to true to set the `x-single-active-consumer` queue property to true.
Applies only when `requiredGroups` are provided and then only to those groups.
+
Default: `false`
transacted::
Whether to use transacted channels.
+
@@ -647,8 +738,8 @@ There are a number of rabbit-specific binding properties that allow you to modif
If you have an existing exchange/queue that you wish to use, you can completely disable automatic provisioning as follows, assuming the exchange is named `myExchange` and the queue is named `myQueue`:
* `spring.cloud.stream.binding.<binding name>.destination=myExhange`
* `spring.cloud.stream.binding.<binding name>.group=myQueue`
* `spring.cloud.stream.bindings.<binding name>.destination=myExhange`
* `spring.cloud.stream.bindings.<binding name>.group=myQueue`
* `spring.cloud.stream.rabbit.bindings.<binding name>.consumer.bindQueue=false`
* `spring.cloud.stream.rabbit.bindings.<binding name>.consumer.declareExchange=false`
* `spring.cloud.stream.rabbit.bindings.<binding name>.consumer.queueNameGroupOnly=true`

36
docs/pom.xml
View File

@@ -16,17 +16,18 @@
<docs.main>spring-cloud-stream-binder-rabbit</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<maven.plugin.plugin.version>3.4</maven.plugin.plugin.version>
<configprops.inclusionPattern>.*stream.*</configprops.inclusionPattern>
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
</properties>
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-starter-stream-rabbit</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>2.8.2</version>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
<sourceDirectory>src/main/asciidoc</sourceDirectory>
</build>
<profiles>
<profile>
@@ -38,28 +39,25 @@
<artifactId>git-commit-id-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor-maven-plugin.version}</version>
<configuration>
<sourceDirectory>${project.build.directory}/refdocs/</sourceDirectory>
<attributes>
<spring-cloud-stream-version>${project.version}</spring-cloud-stream-version>
</attributes>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>

36
docs/src/main/asciidoc/_configprops.adoc Normal file
View File

@@ -0,0 +1,36 @@
|===
|Name | Default | Description
|spring.cloud.stream.binders | | Additional per-binder properties (see {@link BinderProperties}) if more then one binder of the same type is used (i.e., connect to multiple instances of RabbitMq). Here you can specify multiple binder configurations, each with different environment settings. For example; spring.cloud.stream.binders.rabbit1.environment. . . , spring.cloud.stream.binders.rabbit2.environment. . .
|spring.cloud.stream.binding-retry-interval | 30 | Retry interval (in seconds) used to schedule binding attempts. Default: 30 sec.
|spring.cloud.stream.bindings | | Additional binding properties (see {@link BinderProperties}) per binding name (e.g., 'input`). For example; This sets the content-type for the 'input' binding of a Sink application: 'spring.cloud.stream.bindings.input.contentType=text/plain'
|spring.cloud.stream.default-binder | | The name of the binder to use by all bindings in the event multiple binders available (e.g., 'rabbit').
|spring.cloud.stream.dynamic-destination-cache-size | 10 | The maximum size of Least Recently Used (LRU) cache of dynamic destinations. Once this size is reached, new destinations will trigger the removal of old destinations. Default: 10
|spring.cloud.stream.dynamic-destinations | [] | A list of destinations that can be bound dynamically. If set, only listed destinations can be bound.
|spring.cloud.stream.function.batch-mode | false |
|spring.cloud.stream.function.bindings | |
|spring.cloud.stream.function.definition | | Definition of functions to bind. If several functions need to be composed into one, use pipes (e.g., 'fooFunc\|barFunc')
|spring.cloud.stream.instance-count | 1 | The number of deployed instances of an application. Default: 1. NOTE: Could also be managed per individual binding "spring.cloud.stream.bindings.foo.consumer.instance-count" where 'foo' is the name of the binding.
|spring.cloud.stream.instance-index | 0 | The instance id of the application: a number from 0 to instanceCount-1. Used for partitioning and with Kafka. NOTE: Could also be managed per individual binding "spring.cloud.stream.bindings.foo.consumer.instance-index" where 'foo' is the name of the binding.
|spring.cloud.stream.instance-index-list | | A list of instance id's from 0 to instanceCount-1. Used for partitioning and with Kafka. NOTE: Could also be managed per individual binding "spring.cloud.stream.bindings.foo.consumer.instance-index-list" where 'foo' is the name of the binding. This setting will override the one set in 'spring.cloud.stream.instance-index'
|spring.cloud.stream.integration.message-handler-not-propagated-headers | | Message header names that will NOT be copied from the inbound message.
|spring.cloud.stream.metrics.export-properties | | List of properties that are going to be appended to each message. This gets populate by onApplicationEvent, once the context refreshes to avoid overhead of doing per message basis.
|spring.cloud.stream.metrics.key | | The name of the metric being emitted. Should be an unique value per application. Defaults to: ${spring.application.name:${vcap.application.name:${spring.config.name:application}}}.
|spring.cloud.stream.metrics.meter-filter | | Pattern to control the 'meters' one wants to capture. By default all 'meters' will be captured. For example, 'spring.integration.*' will only capture metric information for meters whose name starts with 'spring.integration'.
|spring.cloud.stream.metrics.properties | | Application properties that should be added to the metrics payload For example: `spring.application**`.
|spring.cloud.stream.metrics.schedule-interval | 60s | Interval expressed as Duration for scheduling metrics snapshots publishing. Defaults to 60 seconds
|spring.cloud.stream.override-cloud-connectors | false | This property is only applicable when the cloud profile is active and Spring Cloud Connectors are provided with the application. If the property is false (the default), the binder detects a suitable bound service (for example, a RabbitMQ service bound in Cloud Foundry for the RabbitMQ binder) and uses it for creating connections (usually through Spring Cloud Connectors). When set to true, this property instructs binders to completely ignore the bound services and rely on Spring Boot properties (for example, relying on the spring.rabbitmq.* properties provided in the environment for the RabbitMQ binder). The typical usage of this property is to be nested in a customized environment when connecting to multiple systems.
|spring.cloud.stream.poller.cron | | Cron expression value for the Cron Trigger.
|spring.cloud.stream.poller.fixed-delay | 1000 | Fixed delay for default poller.
|spring.cloud.stream.poller.initial-delay | 0 | Initial delay for periodic triggers.
|spring.cloud.stream.poller.max-messages-per-poll | 1 | Maximum messages per poll for the default poller.
|spring.cloud.stream.rabbit.binder.admin-addresses | [] | Urls for management plugins; only needed for queue affinity.
|spring.cloud.stream.rabbit.binder.admin-adresses | |
|spring.cloud.stream.rabbit.binder.compression-level | 0 | Compression level for compressed bindings; see 'java.util.zip.Deflator'.
|spring.cloud.stream.rabbit.binder.connection-name-prefix | | Prefix for connection names from this binder.
|spring.cloud.stream.rabbit.binder.nodes | [] | Cluster member node names; only needed for queue affinity.
|spring.cloud.stream.rabbit.bindings | |
|spring.cloud.stream.sendto.destination | none | The name of the header used to determine the name of the output destination
|spring.cloud.stream.source | | A colon delimited string representing the names of the sources based on which source bindings will be created. This is primarily to support cases where source binding may be required without providing a corresponding Supplier. (e.g., for cases where the actual source of data is outside of scope of spring-cloud-stream - HTTP -> Stream)
|===