58 lines
14 KiB
HTML
58 lines
14 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>27. Binders</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__programming_model.html" title="26. Programming Model"><link rel="next" href="multi__configuration_options.html" title="28. Configuration Options"></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. Binders</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__programming_model.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__configuration_options.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_binders" href="#_binders"></a>27. Binders</h2></div></div></div><p>Spring Cloud Stream provides a Binder abstraction for use in connecting to physical destinations at the external middleware.
|
|
This section provides information about the main concepts behind the Binder SPI, its main components, and implementation-specific details.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_producers_and_consumers" href="#_producers_and_consumers"></a>27.1 Producers and Consumers</h2></div></div></div><div class="figure"><a name="d0e7517" href="#d0e7517"></a><p class="title"><b>Figure 27.1. Producers and Consumers</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/producers-consumers.png" alt="producers consumers"></div></div></div><br class="figure-break"><p>A <span class="emphasis"><em>producer</em></span> is any component that sends messages to a channel.
|
|
The channel can be bound to an external message broker via a Binder implementation for that broker.
|
|
When invoking the <code class="literal">bindProducer()</code> method, the first parameter is the name of the destination within the broker, the second parameter is the local channel instance to which the producer will send messages, and the third parameter contains properties (such as a partition key expression) to be used within the adapter that is created for that channel.</p><p>A <span class="emphasis"><em>consumer</em></span> is any component that receives messages from a channel.
|
|
As with a producer, the consumer’s channel can be bound to an external message broker.
|
|
When invoking the <code class="literal">bindConsumer()</code> method, the first parameter is the destination name, and a second parameter provides the name of a logical group of consumers.
|
|
Each group that is represented by consumer bindings for a given destination receives a copy of each message that a producer sends to that destination (i.e., publish-subscribe semantics).
|
|
If there are multiple consumer instances bound using the same group name, then messages will be load-balanced across those consumer instances so that each message sent by a producer is consumed by only a single consumer instance within each group (i.e., queueing semantics).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_spi" href="#_binder_spi"></a>27.2 Binder SPI</h2></div></div></div><p>The Binder SPI consists of a number of interfaces, out-of-the box utility classes and discovery strategies that provide a pluggable mechanism for connecting to external middleware.</p><p>The key point of the SPI is the <code class="literal">Binder</code> interface which is a strategy for connecting inputs and outputs to external middleware.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Binder<T, C <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ConsumerProperties, P <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ProducerProperties> {
|
|
Binding<T> bindConsumer(String name, String group, T inboundBindTarget, C consumerProperties);
|
|
|
|
Binding<T> bindProducer(String name, T outboundBindTarget, P producerProperties);
|
|
}</pre><p>The interface is parameterized, offering a number of extension points:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">input and output bind targets - as of version 1.0, only <code class="literal">MessageChannel</code> is supported, but this is intended to be used as an extension point in the future;</li><li class="listitem">extended consumer and producer properties - allowing specific Binder implementations to add supplemental properties which can be supported in a type-safe manner.</li></ul></div><p>A typical binder implementation consists of the following</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">a class that implements the <code class="literal">Binder</code> interface;</li><li class="listitem">a Spring <code class="literal">@Configuration</code> class that creates a bean of the type above along with the middleware connection infrastructure;</li><li class="listitem">a <code class="literal">META-INF/spring.binders</code> file found on the classpath containing one or more binder definitions, e.g.</li></ul></div><pre class="screen">kafka:\
|
|
org.springframework.cloud.stream.binder.kafka.config.KafkaBinderConfiguration</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_detection" href="#_binder_detection"></a>27.3 Binder Detection</h2></div></div></div><p>Spring Cloud Stream relies on implementations of the Binder SPI to perform the task of connecting channels to message brokers.
|
|
Each Binder implementation typically connects to one type of messaging system.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_classpath_detection" href="#_classpath_detection"></a>27.3.1 Classpath Detection</h3></div></div></div><p>By default, Spring Cloud Stream relies on Spring Boot’s auto-configuration to configure the binding process.
|
|
If a single Binder implementation is found on the classpath, Spring Cloud Stream will use it automatically.
|
|
For example, a Spring Cloud Stream project that aims to bind only to RabbitMQ can simply add the following dependency:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>For the specific maven coordinates of other binder dependencies, please refer to the documentation of that binder implementation.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="multiple-binders" href="#multiple-binders"></a>27.4 Multiple Binders on the Classpath</h2></div></div></div><p>When multiple binders are present on the classpath, the application must indicate which binder is to be used for each channel binding.
|
|
Each binder configuration contains a <code class="literal">META-INF/spring.binders</code>, which is a simple properties file:</p><pre class="screen">rabbit:\
|
|
org.springframework.cloud.stream.binder.rabbit.config.RabbitServiceAutoConfiguration</pre><p>Similar files exist for the other provided binder implementations (e.g., Kafka), and custom binder implementations are expected to provide them, as well.
|
|
The key represents an identifying name for the binder implementation, whereas the value is a comma-separated list of configuration classes that each contain one and only one bean definition of type <code class="literal">org.springframework.cloud.stream.binder.Binder</code>.</p><p>Binder selection can either be performed globally, using the <code class="literal">spring.cloud.stream.defaultBinder</code> property (e.g., <code class="literal">spring.cloud.stream.defaultBinder=rabbit</code>) or individually, by configuring the binder on each channel binding.
|
|
For instance, a processor application (that has channels with the names <code class="literal">input</code> and <code class="literal">output</code> for read/write respectively) which reads from Kafka and writes to RabbitMQ can specify the following configuration:</p><pre class="screen">spring.cloud.stream.bindings.input.binder=kafka
|
|
spring.cloud.stream.bindings.output.binder=rabbit</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="multiple-systems" href="#multiple-systems"></a>27.5 Connecting to Multiple Systems</h2></div></div></div><p>By default, binders share the application’s Spring Boot auto-configuration, so that one instance of each binder found on the classpath will be created.
|
|
If your application should connect to more than one broker of the same type, you can specify multiple binder configurations, each with different environment settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Turning on explicit binder configuration will disable the default binder configuration process altogether.
|
|
If you do this, all binders in use must be included in the configuration.
|
|
Frameworks that intend to use Spring Cloud Stream transparently may create binder configurations that can be referenced by name, but will not affect the default binder configuration.
|
|
In order to do so, a binder configuration may have its <code class="literal">defaultCandidate</code> flag set to false, e.g. <code class="literal">spring.cloud.stream.binders.<configurationName>.defaultCandidate=false</code>.
|
|
This denotes a configuration that will exist independently of the default binder configuration process.</p></td></tr></table></div><p>For example, this is the typical configuration for a processor application which connects to two RabbitMQ broker instances:</p><pre class="programlisting">spring:
|
|
cloud:
|
|
stream:
|
|
bindings:
|
|
input:
|
|
destination: foo
|
|
binder: rabbit1
|
|
output:
|
|
destination: bar
|
|
binder: rabbit2
|
|
binders:
|
|
rabbit1:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host1>
|
|
rabbit2:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host2></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_configuration_properties" href="#_binder_configuration_properties"></a>27.6 Binder configuration properties</h2></div></div></div><p>The following properties are available when creating custom binder configurations.
|
|
They must be prefixed with <code class="literal">spring.cloud.stream.binders.<configurationName></code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">type</span></dt><dd><p class="simpara"> The binder type.
|
|
It typically references one of the binders found on the classpath, in particular a key in a <code class="literal">META-INF/spring.binders</code> file.</p><p class="simpara">By default, it has the same value as the configuration name.</p></dd><dt><span class="term">inheritEnvironment</span></dt><dd><p class="simpara">Whether the configuration will inherit the environment of the application itself.</p><p class="simpara">Default <code class="literal">true</code>.</p></dd><dt><span class="term">environment</span></dt><dd><p class="simpara"> Root for a set of properties that can be used to customize the environment of the binder.
|
|
When this is configured, the context in which the binder is being created is not a child of the application context.
|
|
This allows for complete separation between the binder components and the application components.</p><p class="simpara">Default <code class="literal">empty</code>.</p></dd><dt><span class="term">defaultCandidate</span></dt><dd><p class="simpara"> Whether the binder configuration is a candidate for being considered a default binder, or can be used only when explicitly referenced.
|
|
This allows adding binder configurations without interfering with the default processing.</p><p class="simpara">Default <code class="literal">true</code>.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__programming_model.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__configuration_options.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">26. Programming Model </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. Configuration Options</td></tr></table></div></body></html> |