76 lines
20 KiB
HTML
76 lines
20 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>30. Binders</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="multi_spring-cloud.html" title="Spring Cloud"><link rel="up" href="multi__spring_cloud_stream.html" title="Part V. Spring Cloud Stream"><link rel="prev" href="multi__programming_model.html" title="29. Programming Model"><link rel="next" href="multi__configuration_options.html" title="31. 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">30. 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 V. 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="spring-cloud-stream-overview-binders" href="#spring-cloud-stream-overview-binders"></a>30. 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>30.1 Producers and Consumers</h2></div></div></div><p>The following image shows the general relationship of producers and consumers:</p><div class="figure"><a name="d0e9726" href="#d0e9726"></a><p class="title"><b>Figure 30.1. Producers and Consumers</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/producers-consumers.png" align="middle" alt="producers consumers"></div></div></div><br class="figure-break"><p>A producer is any component that sends messages to a channel.
|
|
The channel can be bound to an external message broker with a <code class="literal">Binder</code> 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 sends 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 consumer 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 (that is, it follows normal publish-subscribe semantics).
|
|
If there are multiple consumer instances bound with the same group name, then messages are 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 (that is, it follows normal queueing semantics).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-stream-overview-binder-api" href="#spring-cloud-stream-overview-binder-api"></a>30.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. The following listing shows the definnition of the <code class="literal">Binder</code> interface:</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 that 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 type <code class="literal">Binder</code> along with the middleware connection infrastructure.</li><li class="listitem"><p class="simpara">A <code class="literal">META-INF/spring.binders</code> file found on the classpath containing one or more binder definitions, as shown in the following example:</p><pre class="screen">kafka:\
|
|
org.springframework.cloud.stream.binder.kafka.config.KafkaBinderConfiguration</pre></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_detection" href="#_binder_detection"></a>30.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>30.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 automatically uses it.
|
|
For example, a Spring Cloud Stream project that aims to bind only to RabbitMQ can 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, see 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>30.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> file, which is a simple properties file, as shown in the following example:</p><pre class="screen">rabbit:\
|
|
org.springframework.cloud.stream.binder.rabbit.config.RabbitServiceAutoConfiguration</pre><p>Similar files exist for the other provided binder implementations (such as 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 (for example, <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 named <code class="literal">input</code> and <code class="literal">output</code> for read and write respectively) that 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>30.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 is 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 disables the default binder configuration process altogether.
|
|
If you do so, 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 they do 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 (for example, <code class="literal">spring.cloud.stream.binders.<configurationName>.defaultCandidate=false</code>).
|
|
This denotes a configuration that exists independently of the default binder configuration process.</p></td></tr></table></div><p>The following example shows a typical configuration for a processor application that connects to two RabbitMQ broker instances:</p><pre class="programlisting">spring:
|
|
cloud:
|
|
stream:
|
|
bindings:
|
|
input:
|
|
destination: thing1
|
|
binder: rabbit1
|
|
output:
|
|
destination: thing2
|
|
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="_binding_visualization_and_control" href="#_binding_visualization_and_control"></a>30.6 Binding visualization and control</h2></div></div></div><p>Since version 2.0, Spring Cloud Stream supports visualization and control of the Bindings through Actuator endpoints.</p><p>Starting with version 2.0 actuator and web are optional, you must first add one of the web dependencies as well as add the actuator dependency manually.
|
|
The following example shows how to add the dependency for the Web framework:</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.boot<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-boot-starter-web<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>The following example shows how to add the dependency for the WebFlux framework:</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.boot<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-boot-starter-webflux<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>You can add the Actuator dependency as follows:</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.boot<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-boot-starter-actuator<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><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>To run Spring Cloud Stream 2.0 apps in Cloud Foundry, you must add <code class="literal">spring-boot-starter-web</code> and <code class="literal">spring-boot-starter-actuator</code> to the classpath. Otherwise, the
|
|
application will not start due to health check failures.</p></td></tr></table></div><p>You must also enable the <code class="literal">bindings</code> actuator endpoints by setting the following property: <code class="literal">--management.endpoints.web.exposure.include=bindings</code>.</p><p>Once those prerequisites are satisfied. you should see the following in the logs when application start:</p><pre class="literallayout">: Mapped "{[/actuator/bindings/{name}],methods=[POST]. . .
|
|
: Mapped "{[/actuator/bindings],methods=[GET]. . .
|
|
: Mapped "{[/actuator/bindings/{name}],methods=[GET]. . .</pre><p>To visualize the current bindings, access the following URL:
|
|
<code class="literal"><a class="link" href="http://<host>:<port>/actuator/bindings" target="_top">http://<host>:<port>/actuator/bindings</a></code></p><p>Alternative, to see a single binding, access one of the URLs similar to the following:
|
|
<code class="literal"><a class="link" href="http://<host>:<port>/actuator/bindings/myBindingName" target="_top">http://<host>:<port>/actuator/bindings/myBindingName</a></code></p><p>You can also stop, start, pause, and resume individual bindings by posting to the same URL while providing a <code class="literal">state</code> argument as JSON, as shown in the following examples:</p><p>curl -d '{"state":"STOPPED"}' -H "Content-Type: application/json" -X POST <a class="link" href="http://<host>:<port>/actuator/bindings/myBindingName" target="_top">http://<host>:<port>/actuator/bindings/myBindingName</a>
|
|
curl -d '{"state":"STARTED"}' -H "Content-Type: application/json" -X POST <a class="link" href="http://<host>:<port>/actuator/bindings/myBindingName" target="_top">http://<host>:<port>/actuator/bindings/myBindingName</a>
|
|
curl -d '{"state":"PAUSED"}' -H "Content-Type: application/json" -X POST <a class="link" href="http://<host>:<port>/actuator/bindings/myBindingName" target="_top">http://<host>:<port>/actuator/bindings/myBindingName</a>
|
|
curl -d '{"state":"RESUMED"}' -H "Content-Type: application/json" -X POST <a class="link" href="http://<host>:<port>/actuator/bindings/myBindingName" target="_top">http://<host>:<port>/actuator/bindings/myBindingName</a></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><code class="literal">PAUSED</code> and <code class="literal">RESUMED</code> work only when the corresponding binder and its underlying technology supports it. Otherwise, you see the warning message in the logs.
|
|
Currently, only Kafka binder supports the <code class="literal">PAUSED</code> and <code class="literal">RESUMED</code> states.</p></td></tr></table></div></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>30.7 Binder Configuration Properties</h2></div></div></div><p>The following properties are available when customizing binder configurations. These properties exposed via <code class="literal">org.springframework.cloud.stream.config.BinderProperties</code></p><p>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 inherits 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 property is set, the context in which the binder is being created is not a child of the application context.
|
|
This setting 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 setting 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">29. 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"> 31. Configuration Options</td></tr></table></div></body></html> |