<title>2. Spring Cloud Commons: Common Abstractions</title><linkrel="stylesheet"type="text/css"href="css/manual-multipage.css"><metaname="generator"content="DocBook XSL Stylesheets V1.78.1"><linkrel="home"href="multi_spring-cloud-commons.html"title="Cloud Native Applications"><linkrel="up"href="multi_spring-cloud-commons.html"title="Cloud Native Applications"><linkrel="prev"href="multi__spring_cloud_context_application_context_services.html"title="1. Spring Cloud Context: Application Context Services"></head><bodybgcolor="white"text="black"link="#0000FF"vlink="#840084"alink="#0000FF"><divclass="navheader"><tablewidth="100%"summary="Navigation header"><tr><thcolspan="3"align="center">2. Spring Cloud Commons: Common Abstractions</th></tr><tr><tdwidth="20%"align="left"><aaccesskey="p"href="multi__spring_cloud_context_application_context_services.html">Prev</a> </td><thwidth="60%"align="center"> </th><tdwidth="20%"align="right"> </td></tr></table><hr></div><divclass="chapter"><divclass="titlepage"><div><div><h1class="title"><aname="_spring_cloud_commons_common_abstractions"href="#_spring_cloud_commons_common_abstractions"></a>2. Spring Cloud Commons: Common Abstractions</h1></div></div></div><p>Patterns such as service discovery, load balancing and circuit breakers lend themselves to a common abstraction layer that can be consumed by all Spring Cloud clients, independent of the implementation (e.g. discovery via Eureka or Consul).</p><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="__enablediscoveryclient"href="#__enablediscoveryclient"></a>2.1 @EnableDiscoveryClient</h2></div></div></div><p>Commons provides the <codeclass="literal">@EnableDiscoveryClient</code> annotation. This looks for implementations of the <codeclass="literal">DiscoveryClient</code> interface via <codeclass="literal">META-INF/spring.factories</code>. Implementations of Discovery Client will add a configuration class to <codeclass="literal">spring.factories</code> under the <codeclass="literal">org.springframework.cloud.client.discovery.EnableDiscoveryClient</code> key. Examples of <codeclass="literal">DiscoveryClient</code> implementations: are <aclass="link"href="http://cloud.spring.io/spring-cloud-netflix/"target="_top">Spring Cloud Netflix Eureka</a>, <aclass="link"href="http://cloud.spring.io/spring-cloud-consul/"target="_top">Spring Cloud Consul Discovery</a> and <aclass="link"href="http://cloud.spring.io/spring-cloud-zookeeper/"target="_top">Spring Cloud Zookeeper Discovery</a>.</p><p>By default, implementations of <codeclass="literal">DiscoveryClient</code> will auto-register the local Spring Boot server with the remote discovery server. This can be disabled by setting <codeclass="literal">autoRegister=false</code> in <codeclass="literal">@EnableDiscoveryClient</code>.</p><divclass="note"style="margin-left: 0.5in; margin-right: 0.5in;"><tableborder="0"summary="Note"><tr><tdrowspan="2"align="center"valign="top"width="25"><imgalt="[Note]"src="images/note.png"></td><thalign="left">Note</th></tr><tr><tdalign="left"valign="top"><p>The use of <codeclass="literal">@EnableDiscoveryClient</code> is no longer required. It is enough to just have a <codeclass="literal">DiscoveryClient</code> implementation
on the classpath to cause the Spring Boot application to register with the service discovery server.</p></td></tr></table></div><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_health_indicator"href="#_health_indicator"></a>2.1.1 Health Indicator</h3></div></div></div><p>Commons creates a Spring Boot <codeclass="literal">HealthIndicator</code> that <codeclass="literal">DiscoveryClient</code> implementations can participate in by implementing <codeclass="literal">DiscoveryHealthIndicator</code>. To disable the composite <codeclass="literal">HealthIndicator</code> set <codeclass="literal">spring.cloud.discovery.client.composite-indicator.enabled=false</code>. A generic <codeclass="literal">HealthIndicator</code> based on <codeclass="literal">DiscoveryClient</code> is auto-configured (<codeclass="literal">DiscoveryClientHealthIndicator). To disable it, set `spring.cloud.discovery.client.health-indicator.enabled=false</code>. To disable the description field of the <codeclass="literal">DiscoveryClientHealthIndicator</code> set <codeclass="literal">spring.cloud.discovery.client.health-indicator.include-description=false</code>, otherwise it can bubble up as the <codeclass="literal">description</code> of the rolled up <codeclass="literal">HealthIndicator</code>.</p></div></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="_serviceregistry"href="#_serviceregistry"></a>2.2 ServiceRegistry</h2></div></div></div><p>Commons now provides a <codeclass="literal">ServiceRegistry</code> interface which provides methods like <codeclass="literal">register(Registration)</code> and <codeclass="literal">deregister(Registration)</code> which allow you to provide custom registered services. <codeclass="literal">Registration</code> is a marker interface.</p><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Configuration</span></em>
<spanxmlns:d="http://docbook.org/ns/docbook"class="hl-comment">// called via some external process, such as an event or a custom actuator endpoint</span>
}</pre><p>Each <codeclass="literal">ServiceRegistry</code> implementation has its own <codeclass="literal">Registry</code> implementation.</p><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_serviceregistry_auto_registration"href="#_serviceregistry_auto_registration"></a>2.2.1 ServiceRegistry Auto-Registration</h3></div></div></div><p>By default, the <codeclass="literal">ServiceRegistry</code> implementation will auto-register the running service. To disable that behavior, there are two methods. You can set <codeclass="literal">@EnableDiscoveryClient(autoRegister=false)</code> to permanently disable auto-registration. You can also set <codeclass="literal">spring.cloud.service-registry.auto-registration.enabled=false</code> to disable the behavior via configuration.</p></div><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_service_registry_actuator_endpoint"href="#_service_registry_actuator_endpoint"></a>2.2.2 Service Registry Actuator Endpoint</h3></div></div></div><p>A <codeclass="literal">/service-registry</code> actuator endpoint is provided by Commons. This endpoint relys on a <codeclass="literal">Registration</code> bean in the Spring Application Context. Calling <codeclass="literal">/service-registry/instance-status</code> via a GET will return the status of the <codeclass="literal">Registration</code>. A POST to the same endpoint with a <codeclass="literal">String</code> body will change the status of the current <codeclass="literal">Registration</code> to the new value. Please see the documentation of the <codeclass="literal">ServiceRegistry</code> implementation you are using for the allowed values for updating the status and the values retured for the status.</p></div></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="_spring_resttemplate_as_a_load_balancer_client"href="#_spring_resttemplate_as_a_load_balancer_client"></a>2.3 Spring RestTemplate as a Load Balancer Client</h2></div></div></div><p><codeclass="literal">RestTemplate</code> can be automatically configured to use ribbon. To create a load balanced <codeclass="literal">RestTemplate</code> create a <codeclass="literal">RestTemplate</code><codeclass="literal">@Bean</code> and use the <codeclass="literal">@LoadBalanced</code> qualifier.</p><divclass="warning"style="margin-left: 0.5in; margin-right: 0.5in;"><tableborder="0"summary="Warning"><tr><tdrowspan="2"align="center"valign="top"width="25"><imgalt="[Warning]"src="images/warning.png"></td><thalign="left">Warning</th></tr><tr><tdalign="left"valign="top"><p>A <codeclass="literal">RestTemplate</code> bean is no longer created via auto configuration. It must be created by individual applications.</p></td></tr></table></div><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Configuration</span></em>
for details of how the <codeclass="literal">RestTemplate</code> is set up.</p></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="_spring_webclient_as_a_load_balancer_client"href="#_spring_webclient_as_a_load_balancer_client"></a>2.4 Spring WebClient as a Load Balancer Client</h2></div></div></div><p><codeclass="literal">WebClient</code> can be automatically configured to use the <codeclass="literal">LoadBalancerClient</code>. To create a load balanced <codeclass="literal">WebClient</code> create a <codeclass="literal">WebClient.Builder</code><codeclass="literal">@Bean</code> and use the <codeclass="literal">@LoadBalanced</code> qualifier.</p><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Configuration</span></em>
}</pre><p>The URI needs to use a virtual host name (ie. service name, not a host name).
The Ribbon client is used to create a full physical address.</p><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_retrying_failed_requests"href="#_retrying_failed_requests"></a>2.4.1 Retrying Failed Requests</h3></div></div></div><p>A load balanced <codeclass="literal">RestTemplate</code> can be configured to retry failed requests.
By default this logic is disabled, you can enable it by adding <aclass="link"href="https://github.com/spring-projects/spring-retry"target="_top">Spring Retry</a> to your application’s classpath. The load balanced <codeclass="literal">RestTemplate</code> will
honor some of the Ribbon configuration values related to retrying failed requests. If
you would like to disable the retry logic with Spring Retry on the classpath
you can set <codeclass="literal">spring.cloud.loadbalancer.retry.enabled=false</code>.
The properties you can use are <codeclass="literal">client.ribbon.MaxAutoRetries</code>,
<codeclass="literal">client.ribbon.MaxAutoRetriesNextServer</code>, and <codeclass="literal">client.ribbon.OkToRetryOnAllOperations</code>.
See the <aclass="link"href="https://github.com/Netflix/ribbon/wiki/Getting-Started#the-properties-file-sample-clientproperties"target="_top">Ribbon documentation</a>
for a description of what there properties do.</p><p>If you would like to implement a <codeclass="literal">BackOffPolicy</code> in your retries you will need to
create a bean of type <codeclass="literal">LoadBalancedBackOffPolicyFactory</code>, and return the <codeclass="literal">BackOffPolicy</code>
you would like to use for a given service.</p><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Configuration</span></em>
}</pre><divclass="note"style="margin-left: 0.5in; margin-right: 0.5in;"><tableborder="0"summary="Note"><tr><tdrowspan="2"align="center"valign="top"width="25"><imgalt="[Note]"src="images/note.png"></td><thalign="left">Note</th></tr><tr><tdalign="left"valign="top"><p><codeclass="literal">client</code> in the above examples should be replaced with your Ribbon client’s
name.</p></td></tr></table></div></div><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_multiple_resttemplate_objects"href="#_multiple_resttemplate_objects"></a>2.4.2 Multiple RestTemplate objects</h3></div></div></div><p>If you want a <codeclass="literal">RestTemplate</code> that is not load balanced, create a <codeclass="literal">RestTemplate</code>
bean and inject it as normal. To access the load balanced <codeclass="literal">RestTemplate</code> use
the <codeclass="literal">@LoadBalanced</code> qualifier when you create your <codeclass="literal">@Bean</code>.</p><divclass="important"style="margin-left: 0.5in; margin-right: 0.5in;"><tableborder="0"summary="Important"><tr><tdrowspan="2"align="center"valign="top"width="25"><imgalt="[Important]"src="images/important.png"></td><thalign="left">Important</th></tr><tr><tdalign="left"valign="top"><p>Notice the <codeclass="literal">@Primary</code> annotation on the plain <codeclass="literal">RestTemplate</code> declaration in the example below, to disambiguate the unqualified <codeclass="literal">@Autowired</code> injection.</p></td></tr></table></div><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Configuration</span></em>
}</pre><divclass="tip"style="margin-left: 0.5in; margin-right: 0.5in;"><tableborder="0"summary="Tip"><tr><tdrowspan="2"align="center"valign="top"width="25"><imgalt="[Tip]"src="images/tip.png"></td><thalign="left">Tip</th></tr><tr><tdalign="left"valign="top"><p>If you see errors like <codeclass="literal">java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</code> try injecting <codeclass="literal">RestOperations</code> instead or setting <codeclass="literal">spring.aop.proxyTargetClass=true</code>.</p></td></tr></table></div></div></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="loadbalanced-webclient"href="#loadbalanced-webclient"></a>2.5 Spring WebFlux WebClient as a Load Balancer Client</h2></div></div></div><p><codeclass="literal">WebClient</code> can be configured to use the <codeclass="literal">LoadBalancerClient. A `LoadBalancerExchangeFilterFunction</code> is auto-configured if spring-webflux is on the classpath.</p><preclass="programlisting"><spanxmlns:d="http://docbook.org/ns/docbook"class="hl-keyword">public</span><spanxmlns:d="http://docbook.org/ns/docbook"class="hl-keyword">class</span> MyClass {
The <codeclass="literal">LoadBalancerClient</code> is used to create a full physical address.</p></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="ignore-network-interfaces"href="#ignore-network-interfaces"></a>2.6 Ignore Network Interfaces</h2></div></div></div><p>Sometimes it is useful to ignore certain named network interfaces so they can be excluded from Service Discovery registration (eg. running in a Docker container). A list of regular expressions can be set that will cause the desired network interfaces to be ignored. The following configuration will ignore the "docker0" interface and all interfaces that start with "veth".</p><p><b>application.yml. </b>
</p><p>You can also force to use only specified network addresses using list of regular expressions:</p><p><b>application.yml. </b>
</p><preclass="screen">spring:
cloud:
inetutils:
preferredNetworks:
- 192.168
- 10.0</pre><p>
</p><p>You can also force to use only site local addresses. See <aclass="link"href="https://docs.oracle.com/javase/8/docs/api/java/net/Inet4Address.html#isSiteLocalAddress--"target="_top">Inet4Address.html.isSiteLocalAddress()</a> for more details what is site local address.</p><p><b>application.yml. </b>
as well as OK HTTP clients (<codeclass="literal">OkHttpClientFactory</code>). The <codeclass="literal">OkHttpClientFactory</code> bean will only be created
if the OK HTTP jar is on the classpath. In addition, Spring Cloud Commons provides beans for creating
the connection managers used by both clients, <codeclass="literal">ApacheHttpClientConnectionManagerFactory</code> for the Apache
HTTP client and <codeclass="literal">OkHttpClientConnectionPoolFactory</code> for the OK HTTP client. You can provide
your own implementation of these beans if you would like to customize how the HTTP clients are created
in downstream projects. You can also disable the creation of these beans by setting
<codeclass="literal">spring.cloud.httpclientfactories.apache.enabled</code> or <codeclass="literal">spring.cloud.httpclientfactories.ok.enabled</code> to
