diff --git a/spring-cloud.html b/spring-cloud.html index 734ce481..f71c8cfe 100644 --- a/spring-cloud.html +++ b/spring-cloud.html @@ -570,7 +570,17 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Programming Model +
    • +
  • Binders +
  • Configuration Options @@ -585,14 +595,13 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Kafka-Specific Settings
    • -
  • Binder Detection +
  • Content Type and Transformation
    • -
  • Content Type and Transformation
  • Inter-Application Communication +
    +

    Spring Cloud Stream allows you to declaratively configure type conversion for inputs and outputs using the content-type property of a binding. +Note that general type conversion may also be accomplished easily by using a transformer inside your application. +Currently, Spring Cloud Stream natively supports the following type conversions commonly used in streams:

    +
    +
    +
      +
    • +

      JSON to/from POJO

      +
      • +
    • +

      JSON to/from org.springframework.tuple.Tuple

      +
      • +
    • +

      Object to/from byte[] : Either the raw bytes serialized for remote transport, bytes emitted by an application, or converted to bytes using Java serialization(requires the object to be Serializable)

      +
      • +
    • +

      String to/from byte[]

      +
      • +
    • +

      Object to plain text (invokes the object’s toString() method)

      +
      • +
    +
    +
    +

    Where JSON represents either a byte array or String payload containing JSON. +Currently, Objects may be converted from a JSON byte array or String. +Converting to JSON always produces a String.

    +
    +
    +

    MIME types

    +
    +

    content-type values are parsed as media types, e.g., application/json or text/plain;charset=UTF-8. +MIME types are especially useful for indicating how to convert to String or byte[] content. +Spring Cloud Stream also uses MIME type format to represent Java types, using the general type application/x-java-object with a type parameter. +For example, application/x-java-object;type=java.util.Map or application/x-java-object;type=com.bar.Foo can be set as the content-type property of an input binding. +In addition, Spring Cloud Stream provides custom MIME types, notably, application/x-spring-tuple to specify a Tuple.

    +
    +
    +
    +

    MIME types and Java types

    +
    +

    The type conversions Spring Cloud Stream provides out of the box are summarized in the following table:

    +
    + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Source PayloadTarget Payloadcontent-type headercontent-typeComments

    POJO

    JSON String

    ignored

    application/json

    Tuple

    JSON String

    ignored

    application/json

    JSON is tailored for Tuple

    POJO

    String (toString())

    ignored

    text/plain, java.lang.String

    POJO

    byte[] (java.io serialized)

    ignored

    application/x-java-serialized-object

    JSON byte[] or String

    POJO

    application/json (or none)

    application/x-java-object

    byte[] or String

    Serializable

    application/x-java-serialized-object

    application/x-java-object

    JSON byte[] or String

    Tuple

    application/json (or none)

    application/x-spring-tuple

    byte[]

    String

    any

    text/plain, java.lang.String

    will apply any Charset specified in the content-type header

    String

    byte[]

    any

    application/octet-stream

    will apply any Charset specified in the content-type header

    +
    +

    Conversion applies to payloads that require type conversion. +For example, if a module produces an XML string with outputType=application/json, the payload will not be converted from XML to JSON. +This is because the payload at the module’s output channel is already a String so no conversion will be applied at runtime.

    +
    +
    +

    While conversion is supported for both input and output channels, it is especially recommended to be used for the conversion of outbound messages. +For the conversion of inbound messages, especially when the target is a POJO, the @StreamListener support will perform the conversion automatically.

    +
    +
    +
    +

    `@StreamListener and Message Conversion

    +
    +

    The @StreamListener annotation provides a convenient way for converting incoming messages without the need to specify the content type of an input channel. +During the dispatching process to methods annotated with @StreamListener, a conversion will be applied automatically if the argument requires it.

    +
    +
    +

    For example, let’s consider a message with the String content {"greeting":"Hello, world"} and a content-type header of application/json is received on the input channel. +Let us consider the following application that receives it:

    +
    +
    +
    +
    public class GreetingMessage {
+
+  String greeting;
+
+  public String getGreeting() {
+    return greeting;
+  }
+
+  public void setGreeting(String greeting) {
+    this.greeting = greeting;
+  }
+}
+
+@EnableBinding(Sink.class)
+@EnableAutoConfiguration
+public static class GreetingSink {
+
+		@StreamListener(Sink.INPUT)
+		public void receive(Greeting greeting) {
+			// handle Greeting
+		}
+	}
    +
    +
    +
    +

    The argument of the method will be populated automatically with the POJO containing the unmarshalled form of the JSON String.

    +
    +
    @@ -6986,7 +7307,7 @@ You can achieve this scenario by correlating the input and output destinations o

    Supposing that a design calls for the Time Source application to send data to the Log Sink application, you can use a common destination named ticktock for bindings within both applications.

    -

    Time Source will set the following property:

    +

    Time Source (that has the channel name output) will set the following property:

    @@ -6994,7 +7315,7 @@ You can achieve this scenario by correlating the input and output destinations o
    -

    Log Sink will set the following property:

    +

    Log Sink (that has the channel name input) will set the following property:

    @@ -7082,7 +7403,7 @@ If a topic already exists with a larger number of partitions than the maximum of
    Configuring Input Bindings for Partitioning
    -

    An input binding is configured to receive partitioned data by setting its partitioned property, as well as the instanceIndex and instanceCount properties on the application itself, as in the following example:

    +

    An input binding (with the channel name input) is configured to receive partitioned data by setting its partitioned property, as well as the instanceIndex and instanceCount properties on the application itself, as in the following example:

    @@ -7125,7 +7446,7 @@ The following example shows how to test both input and output channels on a proc
    -
    @RunWith(SpringJUnit4ClassRunner.class)
+
    @RunWith(SpringJUnit4ClassRunner.class)
 @SpringApplicationConfiguration(classes = ExampleTest.MyProcessor.class)
 @IntegrationTest({"server.port=-1"})
 @DirtiesContext
@@ -7739,16 +8060,363 @@ If you want to use Grok together with the logs from Cloud Foundry you have to us
 }
    +
    +
    JSON Logback with Logstash
    +
    +

    Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability +we’re passing the dependencies in the groupId:artifactId:version notation.

    +
    +
    +

    Dependencies setup

    +
    +
    +
      +
    • +

      Ensure that Logback is on the classpath (ch.qos.logback:logback-core)

      +
      • +
    • +

      Add Logstash Logback encode - example for version 4.6 : net.logstash.logback:logstash-logback-encoder:4.6

      +
      • +
    +
    +
    +

    Logback setup

    +
    +
    +

    Below you can find an example of a Logback configuration (file named logback-spring.xml) that:

    +
    +
    +
      +
    • +

      logs information from the application in a JSON format to a build/${spring.application.name}.json file

      +
      • +
    • +

      has commented out two additional appenders - console and standard log file

      +
      • +
    • +

      has the same logging pattern as the one presented in the previous section

      +
      • +
    +
    +
    +
    +
    +
    +
    +

    Adding to the project

    +
    +

    Only Sleuth (log correlation)

    -

    In general if you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add -the spring-cloud-starter-sleuth module to your project.

    +

    If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add +the spring-cloud-starter-sleuth module to your project.

    +
    +
    +
    Maven
    +
    +
    <dependencyManagement> (1)
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>Brixton.RELEASE</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
+
+<dependency> (2)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-sleuth</artifactId>
+</dependency>
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-starter-sleuth

      +
      3. +
    +
    +
    +
    Gradle
    +
    +
    dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies { (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth"
+}
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-starter-sleuth

      +
      3. +
    +
    +
    +
    +

    Sleuth with Zipkin via HTTP

    +
    +

    If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency.

    +
    +
    +
    Maven
    +
    +
    <dependencyManagement> (1)
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>Brixton.RELEASE</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
+
+<dependency> (2)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-zipkin</artifactId>
+</dependency>
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-starter-zipkin

      +
      3. +
    +
    +
    +
    Gradle
    +
    +
    dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies { (2)
+    compile "org.springframework.cloud:spring-cloud-starter-zipkin"
+}
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-starter-zipkin

      +
      3. +
    +
    +
    +
    +

    Sleuth with Zipkin via Spring Cloud Stream

    +
    +

    If you want both Sleuth and Zipkin just add the spring-cloud-sleuth-stream dependency.

    +
    +
    +
    Maven
    +
    +
    <dependencyManagement> (1)
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>Brixton.RELEASE</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
+
+<dependency> (2)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-sleuth-stream</artifactId>
+</dependency>
+<dependency> (3)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-sleuth</artifactId>
+</dependency>
+<!-- EXAMPLE FOR RABBIT BINDING -->
+<dependency> (4)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-stream-binder-rabbit</artifactId>
+</dependency>
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-sleuth-stream

      +
      3. +
    3. +

      Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

      +
      4. +
    4. +

      Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

      +
      5. +
    +
    +
    +
    Gradle
    +
    +
    dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies {
+    compile "org.springframework.cloud:spring-cloud-sleuth-stream" (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth" (3)
+    // Example for Rabbit binding
+    compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" (4)
+}
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-sleuth-stream

      +
      3. +
    3. +

      Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

      +
      4. +
    4. +

      Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

      +
      5. +
    +
    +
    +
    +

    Spring Cloud Sleuth Stream Zipkin Collector

    +
    +

    If you want to start a Spring Cloud Sleuth Stream Zipkin collector just add the spring-cloud-sleuth-zipkin-stream +dependency

    +
    +
    +
    Maven
    +
    +
    <dependencyManagement> (1)
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>Brixton.RELEASE</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
+
+<dependency> (2)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-sleuth-zipkin-stream</artifactId>
+</dependency>
+<dependency> (3)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-sleuth</artifactId>
+</dependency>
+<!-- EXAMPLE FOR RABBIT BINDING -->
+<dependency> (4)
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-stream-binder-rabbit</artifactId>
+</dependency>
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-sleuth-zipkin-stream

      +
      3. +
    3. +

      Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

      +
      4. +
    4. +

      Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

      +
      5. +
    +
    +
    +
    Gradle
    +
    +
    dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies {
+    compile "org.springframework.cloud:spring-cloud-sleuth-zipkin-stream" (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth" (3)
+    // Example for Rabbit binding
+    compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" (4)
+}
    +
    +
    +
    +
      +
    1. +

      In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

      +
      2. +
    2. +

      Add the dependency to spring-cloud-sleuth-zipkin-stream

      +
      3. +
    3. +

      Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

      +
      4. +
    4. +

      Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

      +
      5. +
    -

    If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency.

    +

    and then just annotate your main class with @EnableZipkinStreamServer annotation:

    +
    +
    +
    +
    +
    +
    @@ -8616,6 +9284,10 @@ that wraps all Action0 instances into their Sleuth representative - the TraceAction. The hook either starts or continues a span depending on the fact whether tracing was already going on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

    +
    +

    You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list +of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

    +

    HTTP integration

    @@ -8946,7 +9618,7 @@ If you use Spring Cloud Consul Config, private DiscoveryClient discoveryClient; public String serviceUrl() { - List<ServiceInstance> list = client.getInstances("STORES"); + List<ServiceInstance> list = discoveryClient.getInstances("STORES"); if (list != null && list.size() > 0 ) { return list.get(0).getUri(); } @@ -9713,12 +10385,12 @@ Config clients with secret configuration values.

    To install, make sure you have Spring Boot CLI -(1.3.0 or better):

    +(1.3.5 or better):

    $ spring version
-Spring CLI v1.3.2.RELEASE
    +Spring CLI v1.3.5.RELEASE
    @@ -9726,8 +10398,8 @@ Spring CLI v1.3.2.RELEASE
    -
    $ sdk install springboot 1.3.2.RELEASE
-$ sdk use springboot 1.3.2.RELEASE
    +
    $ sdk install springboot 1.3.5.RELEASE
+$ sdk use springboot 1.3.5.RELEASE
    @@ -9736,7 +10408,7 @@ $ sdk use springboot 1.3.2.RELEASE 
    $ mvn install
-$ spring install org.springframework.cloud:spring-cloud-cli:1.1.0.RC1
    +$ spring install org.springframework.cloud:spring-cloud-cli:1.1.0.RELEASE
    @@ -12352,7 +13024,7 @@ created during auto-configuration.