<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>
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</code>). To disable it, set <codeclass="literal">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>
@ -15,7 +15,7 @@ on the classpath to cause the Spring Boot application to register with the servi
@@ -15,7 +15,7 @@ on the classpath to cause the Spring Boot application to register with the servi
}</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>
}</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 relies on a <codeclass="literal">Registration</code> bean in the Spring Application Context. Calling <codeclass="literal">/service-registry</code> via a GET will return the status of the <codeclass="literal">Registration</code>. A POST to the same endpoint with a JSON body will change the status of the current <codeclass="literal">Registration</code>to the new value. The JSON body has to include the<codeclass="literal">status</code>field with the preferred 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 returned for the status. For instance, Eureka’s supported statuses are <codeclass="literal">UP</code>, <codeclass="literal">DOWN</code>, <codeclass="literal">OUT_OF_SERVICE</code> and <codeclass="literal">UNKNOWN</code>.</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>
@ -182,4 +182,23 @@ in downstream projects. In addition, if you provide a bean of type <code class=
@@ -182,4 +182,23 @@ in downstream projects. In addition, if you provide a bean of type <code class=
the default factories will use these builders as the basis for the builders returned to 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
<codeclass="literal">false</code>.</p></div><divclass="section"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aname="enabled-features"href="#enabled-features"></a>2.9 Enabled Features</h2></div></div></div><p>A <codeclass="literal">/features</code> actuator endpoint is provided by Commons. This endpoint returns features available on the classpath and if they are enabled or not. The information returned includes the feature type, name, version and vendor.</p><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_feature_types"href="#_feature_types"></a>2.9.1 Feature types</h3></div></div></div><p>There are two types of 'features': abstract and named.</p><p>Abstract features are features where an interface or abstract class is defined that an implementation creates, such as <codeclass="literal">DiscoveryClient</code>, <codeclass="literal">LoadBalancerClient</code> or <codeclass="literal">LockService</code>. The abstract class or interface is used to find a bean of that type in the context. The version displayed is <codeclass="literal">bean.getClass().getPackage().getImplementationVersion()</code>.</p><p>Named features are features that don’t have a particular class they implement, such as "Circuit Breaker", "API Gateway", "Spring Cloud Bus", etc…​ These features require a name and a bean type.</p></div><divclass="section"><divclass="titlepage"><div><div><h3class="title"><aname="_declaring_features"href="#_declaring_features"></a>2.9.2 Declaring features</h3></div></div></div><p>Any module can declare any number of <codeclass="literal">HasFeature</code> beans. Some examples:</p><preclass="programlisting"><em><spanclass="hl-annotation"style="color: gray">@Bean</span></em>
}</pre><p>Each of these beans should go in an appropriately guarded <codeclass="literal">@Configuration</code>.</p></div></div></div><divclass="navfooter"><hr><tablewidth="100%"summary="Navigation footer"><tr><tdwidth="40%"align="left"><aaccesskey="p"href="multi__spring_cloud_context_application_context_services.html">Prev</a> </td><tdwidth="20%"align="center"> </td><tdwidth="40%"align="right"> </td></tr><tr><tdwidth="40%"align="left"valign="top">1. Spring Cloud Context: Application Context Services </td><tdwidth="20%"align="center"><aaccesskey="h"href="multi_spring-cloud-commons.html">Home</a></td><tdwidth="40%"align="right"valign="top"> </td></tr></table></div></body></html>
@ -341,7 +341,7 @@ on the classpath to cause the Spring Boot application to register with the servi
@@ -341,7 +341,7 @@ on the classpath to cause the Spring Boot application to register with the servi
</note>
<sectionxml:id="_health_indicator">
<title>Health Indicator</title>
<simpara>Commons creates a Spring Boot <literal>HealthIndicator</literal> that <literal>DiscoveryClient</literal> implementations can participate in by implementing <literal>DiscoveryHealthIndicator</literal>. To disable the composite <literal>HealthIndicator</literal> set <literal>spring.cloud.discovery.client.composite-indicator.enabled=false</literal>. A generic <literal>HealthIndicator</literal> based on <literal>DiscoveryClient</literal> is auto-configured (<literal>DiscoveryClientHealthIndicator). To disable it, set `spring.cloud.discovery.client.health-indicator.enabled=false</literal>. To disable the description field of the <literal>DiscoveryClientHealthIndicator</literal> set <literal>spring.cloud.discovery.client.health-indicator.include-description=false</literal>, otherwise it can bubble up as the <literal>description</literal> of the rolled up <literal>HealthIndicator</literal>.</simpara>
<simpara>Commons creates a Spring Boot <literal>HealthIndicator</literal> that <literal>DiscoveryClient</literal> implementations can participate in by implementing <literal>DiscoveryHealthIndicator</literal>. To disable the composite <literal>HealthIndicator</literal> set <literal>spring.cloud.discovery.client.composite-indicator.enabled=false</literal>. A generic <literal>HealthIndicator</literal> based on <literal>DiscoveryClient</literal> is auto-configured (<literal>DiscoveryClientHealthIndicator</literal>). To disable it, set <literal>spring.cloud.discovery.client.health-indicator.enabled=false</literal>. To disable the description field of the <literal>DiscoveryClientHealthIndicator</literal> set <literal>spring.cloud.discovery.client.health-indicator.include-description=false</literal>, otherwise it can bubble up as the <literal>description</literal> of the rolled up <literal>HealthIndicator</literal>.</simpara>
</section>
</section>
<sectionxml:id="_serviceregistry">
@ -369,7 +369,7 @@ public class MyConfiguration {
@@ -369,7 +369,7 @@ public class MyConfiguration {
<simpara>A <literal>/service-registry</literal> actuator endpoint is provided by Commons. This endpoint relys on a <literal>Registration</literal> bean in the Spring Application Context. Calling <literal>/service-registry/instance-status</literal> via a GET will return the status of the <literal>Registration</literal>. A POST to the same endpoint with a <literal>String</literal> body will change the status of the current <literal>Registration</literal> to the new value. Please see the documentation of the <literal>ServiceRegistry</literal> implementation you are using for the allowed values for updating the status and the values retured for the status.</simpara>
<simpara>A <literal>/service-registry</literal> actuator endpoint is provided by Commons. This endpoint relies on a <literal>Registration</literal> bean in the Spring Application Context. Calling <literal>/service-registry</literal> via a GET will return the status of the <literal>Registration</literal>. A POST to the same endpoint with a JSON body will change the status of the current <literal>Registration</literal> to the new value. The JSON body has to include the <literal>status</literal> field with the preferred value. Please see the documentation of the <literal>ServiceRegistry</literal> implementation you are using for the allowed values for updating the status and the values returned for the status. For instance, Eureka’s supported statuses are <literal>UP</literal>, <literal>DOWN</literal>, <literal>OUT_OF_SERVICE</literal> and <literal>UNKNOWN</literal>.</simpara>
@ -604,5 +604,40 @@ You can also disable the creation of these beans by setting
@@ -604,5 +604,40 @@ You can also disable the creation of these beans by setting
<literal>spring.cloud.httpclientfactories.apache.enabled</literal> or <literal>spring.cloud.httpclientfactories.ok.enabled</literal> to
<literal>false</literal>.</simpara>
</section>
<sectionxml:id="enabled-features">
<title>Enabled Features</title>
<simpara>A <literal>/features</literal> actuator endpoint is provided by Commons. This endpoint returns features available on the classpath and if they are enabled or not. The information returned includes the feature type, name, version and vendor.</simpara>
<sectionxml:id="_feature_types">
<title>Feature types</title>
<simpara>There are two types of 'features': abstract and named.</simpara>
<simpara>Abstract features are features where an interface or abstract class is defined that an implementation creates, such as <literal>DiscoveryClient</literal>, <literal>LoadBalancerClient</literal> or <literal>LockService</literal>. The abstract class or interface is used to find a bean of that type in the context. The version displayed is <literal>bean.getClass().getPackage().getImplementationVersion()</literal>.</simpara>
<simpara>Named features are features that don’t have a particular class they implement, such as "Circuit Breaker", "API Gateway", "Spring Cloud Bus", etc…​ These features require a name and a bean type.</simpara>
</section>
<sectionxml:id="_declaring_features">
<title>Declaring features</title>
<simpara>Any module can declare any number of <literal>HasFeature</literal> beans. Some examples:</simpara>
buildmaster
7 years ago