101 lines
23 KiB
HTML
101 lines
23 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>27. Configuration Options</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud.html" title="Spring Cloud"><link rel="up" href="multi__spring_cloud_stream.html" title="Part IV. Spring Cloud Stream"><link rel="prev" href="multi__binders.html" title="26. Binders"><link rel="next" href="multi_contenttypemanagement.html" title="28. Content Type and Transformation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">27. Configuration Options</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__binders.html">Prev</a> </td><th width="60%" align="center">Part IV. Spring Cloud Stream</th><td width="20%" align="right"> <a accesskey="n" href="multi_contenttypemanagement.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_configuration_options" href="#_configuration_options"></a>27. Configuration Options</h2></div></div></div><p>Spring Cloud Stream supports general configuration options as well as configuration for bindings and binders.
|
|
Some binders allow additional binding properties to support middleware-specific features.</p><p>Configuration options can be provided to Spring Cloud Stream applications via any mechanism supported by Spring Boot.
|
|
This includes application arguments, environment variables, and YAML or .properties files.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_cloud_stream_properties" href="#_spring_cloud_stream_properties"></a>27.1 Spring Cloud Stream Properties</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.instanceCount</span></dt><dd><p class="simpara"> The number of deployed instances of an application.
|
|
Must be set for partitioning and if using Kafka.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">spring.cloud.stream.instanceIndex</span></dt><dd> The instance index of the application: a number from <code class="literal">0</code> to <code class="literal">instanceCount</code>-1.
|
|
Used for partitioning and with Kafka.
|
|
Automatically set in Cloud Foundry to match the application’s instance index.</dd><dt><span class="term">spring.cloud.stream.dynamicDestinations</span></dt><dd><p class="simpara"> A list of destinations that can be bound dynamically (for example, in a dynamic routing scenario).
|
|
If set, only listed destinations can be bound.</p><p class="simpara">Default: empty (allowing any destination to be bound).</p></dd><dt><span class="term">spring.cloud.stream.defaultBinder</span></dt><dd><p class="simpara"> The default binder to use, if multiple binders are configured.
|
|
See <a class="link" href="multi__binders.html#multiple-binders" title="26.4 Multiple Binders on the Classpath">Multiple Binders on the Classpath</a>.</p><p class="simpara">Default: empty.</p></dd><dt><span class="term">spring.cloud.stream.overrideCloudConnectors</span></dt><dd><p class="simpara"> This property is only applicable when the <code class="literal">cloud</code> profile is active and Spring Cloud Connectors are provided with the application.
|
|
If the property is false (the default), the binder will detect a suitable bound service (e.g. a RabbitMQ service bound in Cloud Foundry for the RabbitMQ binder) and will use it for creating connections (usually via Spring Cloud Connectors).
|
|
When set to true, this property instructs binders to completely ignore the bound services and rely on Spring Boot properties (e.g. relying on the <code class="literal">spring.rabbitmq.*</code> properties provided in the environment for the RabbitMQ binder).
|
|
The typical usage of this property is to be nested in a customized environment <a class="link" href="multi__binders.html#multiple-systems" title="26.5 Connecting to Multiple Systems">when connecting to multiple systems</a>.</p><p class="simpara">Default: false.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="binding-properties" href="#binding-properties"></a>27.2 Binding Properties</h2></div></div></div><p>Binding properties are supplied using the format <code class="literal">spring.cloud.stream.bindings.<channelName>.<property>=<value></code>.
|
|
The <code class="literal"><channelName></code> represents the name of the channel being configured (e.g., <code class="literal">output</code> for a <code class="literal">Source</code>).</p><p>To avoid repetition, Spring Cloud Stream supports setting values for all channels, in the format <code class="literal">spring.cloud.stream.default.<property>=<value></code>.</p><p>In what follows, we indicate where we have omitted the <code class="literal">spring.cloud.stream.bindings.<channelName>.</code> prefix and focus just on the property name, with the understanding that the prefix will be included at runtime.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_properties_for_use_of_spring_cloud_stream" href="#_properties_for_use_of_spring_cloud_stream"></a>27.2.1 Properties for Use of Spring Cloud Stream</h3></div></div></div><p>The following binding properties are available for both input and output bindings and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.destination=ticktock</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default</code>, e.g. <code class="literal">spring.cloud.stream.default.contentType=application/json</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">destination</span></dt><dd>The target destination of a channel on the bound middleware (e.g., the RabbitMQ exchange or Kafka topic).
|
|
If the channel is bound as a consumer, it could be bound to multiple destinations and the destination names can be specified as comma separated String values.
|
|
If not set, the channel name is used instead.
|
|
The default value of this property cannot be overridden.</dd><dt><span class="term">group</span></dt><dd><p class="simpara"> The consumer group of the channel.
|
|
Applies only to inbound bindings.
|
|
See <a class="link" href="multi__main_concepts.html#consumer-groups" title="24.4 Consumer Groups">Consumer Groups</a>.</p><p class="simpara">Default: null (indicating an anonymous consumer).</p></dd><dt><span class="term">contentType</span></dt><dd><p class="simpara">The content type of the channel.</p><p class="simpara">Default: null (so that no type coercion is performed).</p></dd><dt><span class="term">binder</span></dt><dd><p class="simpara"> The binder used by this binding.
|
|
See <a class="xref" href="multi__binders.html#multiple-binders" title="26.4 Multiple Binders on the Classpath">Section 26.4, “Multiple Binders on the Classpath”</a> for details.</p><p class="simpara">Default: null (the default binder will be used, if one exists).</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_consumer_properties" href="#_consumer_properties"></a>27.2.2 Consumer properties</h3></div></div></div><p>The following binding properties are available for input bindings only and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.consumer.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.consumer.concurrency=3</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default.consumer</code>, e.g. <code class="literal">spring.cloud.stream.default.consumer.headerMode=raw</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">concurrency</span></dt><dd><p class="simpara">The concurrency of the inbound consumer.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">partitioned</span></dt><dd><p class="simpara">Whether the consumer receives data from a partitioned producer.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">headerMode</span></dt><dd><p class="simpara"> When set to <code class="literal">raw</code>, disables header parsing on input.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when inbound data is coming from outside Spring Cloud Stream applications.</p><p class="simpara">Default: <code class="literal">embeddedHeaders</code>.</p></dd><dt><span class="term">maxAttempts</span></dt><dd><p class="simpara">If processing fails, the number of attempts to process the message (including the first).
|
|
Set to 1 to disable retry.</p><p class="simpara">Default: <code class="literal">3</code>.</p></dd><dt><span class="term">backOffInitialInterval</span></dt><dd><p class="simpara">The backoff initial interval on retry.</p><p class="simpara">Default: <code class="literal">1000</code>.</p></dd><dt><span class="term">backOffMaxInterval</span></dt><dd><p class="simpara">The maximum backoff interval.</p><p class="simpara">Default: <code class="literal">10000</code>.</p></dd><dt><span class="term">backOffMultiplier</span></dt><dd><p class="simpara">The backoff multiplier.</p><p class="simpara">Default: <code class="literal">2.0</code>.</p></dd><dt><span class="term">instanceIndex</span></dt><dd><p class="simpara"> When set to a value greater than equal to zero, allows customizing the instance index of this consumer (if different from <code class="literal">spring.cloud.stream.instanceIndex</code>).
|
|
When set to a negative value, it will default to <code class="literal">spring.cloud.stream.instanceIndex</code>.</p><p class="simpara">Default: <code class="literal">-1</code>.</p></dd><dt><span class="term">instanceCount</span></dt><dd><p class="simpara"> When set to a value greater than equal to zero, allows customizing the instance count of this consumer (if different from <code class="literal">spring.cloud.stream.instanceCount</code>).
|
|
When set to a negative value, it will default to <code class="literal">spring.cloud.stream.instanceCount</code>.</p><p class="simpara">Default: <code class="literal">-1</code>.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_producer_properties" href="#_producer_properties"></a>27.2.3 Producer Properties</h3></div></div></div><p>The following binding properties are available for output bindings only and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.producer.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.producer.partitionKeyExpression=payload.id</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default.producer</code>, e.g. <code class="literal">spring.cloud.stream.default.producer.partitionKeyExpression=payload.id</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">partitionKeyExpression</span></dt><dd><p class="simpara"> A SpEL expression that determines how to partition outbound data.
|
|
If set, or if <code class="literal">partitionKeyExtractorClass</code> is set, outbound data on this channel will be partitioned, and <code class="literal">partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a class="xref" href="multi__main_concepts.html#partitioning" title="24.5 Partitioning Support">Section 24.5, “Partitioning Support”</a>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionKeyExtractorClass</span></dt><dd><p class="simpara"> A <code class="literal">PartitionKeyExtractorStrategy</code> implementation.
|
|
If set, or if <code class="literal">partitionKeyExpression</code> is set, outbound data on this channel will be partitioned, and <code class="literal">partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a class="xref" href="multi__main_concepts.html#partitioning" title="24.5 Partitioning Support">Section 24.5, “Partitioning Support”</a>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionSelectorClass</span></dt><dd><p class="simpara"> A <code class="literal">PartitionSelectorStrategy</code> implementation.
|
|
Mutually exclusive with <code class="literal">partitionSelectorExpression</code>.
|
|
If neither is set, the partition will be selected as the <code class="literal">hashCode(key) % partitionCount</code>, where <code class="literal">key</code> is computed via either <code class="literal">partitionKeyExpression</code> or <code class="literal">partitionKeyExtractorClass</code>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionSelectorExpression</span></dt><dd><p class="simpara"> A SpEL expression for customizing partition selection.
|
|
Mutually exclusive with <code class="literal">partitionSelectorClass</code>.
|
|
If neither is set, the partition will be selected as the <code class="literal">hashCode(key) % partitionCount</code>, where <code class="literal">key</code> is computed via either <code class="literal">partitionKeyExpression</code> or <code class="literal">partitionKeyExtractorClass</code>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionCount</span></dt><dd><p class="simpara"> The number of target partitions for the data, if partitioning is enabled.
|
|
Must be
|
|
set to a value greater than 1 if the producer is partitioned.
|
|
On Kafka, interpreted as a
|
|
hint; the larger of this and the partition count of the target topic is used instead.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">requiredGroups</span></dt><dd>A comma-separated list of groups to which the producer must ensure message delivery even if they start after it has been created (e.g., by pre-creating durable queues in RabbitMQ).</dd><dt><span class="term">headerMode</span></dt><dd><p class="simpara"> When set to <code class="literal">raw</code>, disables header embedding on output.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when producing data for non-Spring Cloud Stream applications.</p><p class="simpara">Default: <code class="literal">embeddedHeaders</code>.</p></dd><dt><span class="term">useNativeEncoding</span></dt><dd><p class="simpara"> When set to <code class="literal">true</code>, the outbound message is serialized directly by client library, which must be configured correspondingly (e.g. setting an appropriate Kafka producer value serializer).
|
|
When this configuration is being used, the outbound message marshalling is not based on the <code class="literal">contentType</code> of the binding.
|
|
When native encoding is used, it is the responsibility of the consumer to use appropriate decoder (ex: Kafka consumer value de-serializer) to deserialize the inbound message.
|
|
Also, when native encoding/decoding is used the <code class="literal">headerMode</code> property is ignored and headers will not be embedded into the message.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dynamicdestination" href="#dynamicdestination"></a>27.3 Using dynamically bound destinations</h2></div></div></div><p>Besides the channels defined via <code class="literal">@EnableBinding</code>, Spring Cloud Stream allows applications to send messages to dynamically bound destinations.
|
|
This is useful, for example, when the target destination needs to be determined at runtime.
|
|
Applications can do so by using the <code class="literal">BinderAwareChannelResolver</code> bean, registered automatically by the <code class="literal">@EnableBinding</code> annotation.</p><p>The property 'spring.cloud.stream.dynamicDestinations' can be used for restricting the dynamic destination names to a set known beforehand (whitelisting).
|
|
If the property is not set, any destination can be bound dynamicaly.</p><p>The <code class="literal">BinderAwareChannelResolver</code> can be used directly as in the following example, in which a REST controller uses a path variable to decide the target channel.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SourceWithDynamicDestination {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> BinderAwareChannelResolver resolver;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(path = "/{target}", method = POST, consumes = "*/*")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ResponseStatus(HttpStatus.ACCEPTED)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handleRequest(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> String body, <em><span class="hl-annotation" style="color: gray">@PathVariable("target")</span></em> target,
|
|
<em><span class="hl-annotation" style="color: gray">@RequestHeader(HttpHeaders.CONTENT_TYPE)</span></em> Object contentType) {
|
|
sendMessage(body, target, contentType);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sendMessage(String body, String target, Object contentType) {
|
|
resolver.resolveDestination(target).send(MessageBuilder.createMessage(body,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MessageHeaders(Collections.singletonMap(MessageHeaders.CONTENT_TYPE, contentType))));
|
|
}
|
|
}</pre><p>After starting the application on the default port 8080, when sending the following data:</p><pre class="screen">curl -H "Content-Type: application/json" -X POST -d "customer-1" http://localhost:8080/customers
|
|
|
|
curl -H "Content-Type: application/json" -X POST -d "order-1" http://localhost:8080/orders</pre><p>The destinations 'customers' and 'orders' are created in the broker (for example: exchange in case of Rabbit or topic in case of Kafka) with the names 'customers' and 'orders', and the data is published to the appropriate destinations.</p><p>The <code class="literal">BinderAwareChannelResolver</code> is a general purpose Spring Integration <code class="literal">DestinationResolver</code> and can be injected in other components.
|
|
For example, in a router using a SpEL expression based on the <code class="literal">target</code> field of an incoming JSON message.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SourceWithDynamicDestination {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> BinderAwareChannelResolver resolver;
|
|
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(path = "/", method = POST, consumes = "application/json")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ResponseStatus(HttpStatus.ACCEPTED)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handleRequest(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> String body, <em><span class="hl-annotation" style="color: gray">@RequestHeader(HttpHeaders.CONTENT_TYPE)</span></em> Object contentType) {
|
|
sendMessage(body, contentType);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sendMessage(Object body, Object contentType) {
|
|
routerChannel().send(MessageBuilder.createMessage(body,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MessageHeaders(Collections.singletonMap(MessageHeaders.CONTENT_TYPE, contentType))));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = "routerChannel")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageChannel routerChannel() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> DirectChannel();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ServiceActivator(inputChannel = "routerChannel")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ExpressionEvaluatingRouter router() {
|
|
ExpressionEvaluatingRouter router =
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ExpressionEvaluatingRouter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpelExpressionParser().parseExpression(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"payload.target"</span>));
|
|
router.setDefaultOutputChannelName(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"default-output"</span>);
|
|
router.setChannelResolver(resolver);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> router;
|
|
}
|
|
}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__binders.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="multi__spring_cloud_stream.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="multi_contenttypemanagement.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">26. Binders </td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud.html">Home</a></td><td width="40%" align="right" valign="top"> 28. Content Type and Transformation</td></tr></table></div></body></html> |