You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
294 lines
46 KiB
294 lines
46 KiB
<html><head> |
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|
<title>Cloud Native Applications</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Cloud Native Applications</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e9"></a></span></dt><dt><span class="chapter"><a href="#_spring_cloud_context_application_context_services">1. Spring Cloud Context: Application Context Services</a></span></dt><dd><dl><dt><span class="section"><a href="#_the_bootstrap_application_context">1.1. The Bootstrap Application Context</a></span></dt><dt><span class="section"><a href="#_application_context_hierarchies">1.2. Application Context Hierarchies</a></span></dt><dt><span class="section"><a href="#customizing-bootstrap-properties">1.3. Changing the Location of Bootstrap Properties</a></span></dt><dt><span class="section"><a href="#overriding-bootstrap-properties">1.4. Overriding the Values of Remote Properties</a></span></dt><dt><span class="section"><a href="#_customizing_the_bootstrap_configuration">1.5. Customizing the Bootstrap Configuration</a></span></dt><dt><span class="section"><a href="#customizing-bootstrap-property-sources">1.6. Customizing the Bootstrap Property Sources</a></span></dt><dt><span class="section"><a href="#_environment_changes">1.7. Environment Changes</a></span></dt><dt><span class="section"><a href="#_refresh_scope">1.8. Refresh Scope</a></span></dt><dt><span class="section"><a href="#_encryption_and_decryption">1.9. Encryption and Decryption</a></span></dt><dt><span class="section"><a href="#_endpoints">1.10. Endpoints</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_commons_common_abstractions">2. Spring Cloud Commons: Common Abstractions</a></span></dt><dd><dl><dt><span class="section"><a href="#__enablediscoveryclient">2.1. @EnableDiscoveryClient</a></span></dt><dd><dl><dt><span class="section"><a href="#_health_indicator">2.1.1. Health Indicator</a></span></dt></dl></dd><dt><span class="section"><a href="#_serviceregistry">2.2. ServiceRegistry</a></span></dt><dd><dl><dt><span class="section"><a href="#_serviceregistry_auto_registration">2.2.1. ServiceRegistry Auto-Registration</a></span></dt><dt><span class="section"><a href="#_service_registry_actuator_endpoint">2.2.2. Service Registry Actuator Endpoint</a></span></dt></dl></dd><dt><span class="section"><a href="#_spring_resttemplate_as_a_load_balancer_client">2.3. Spring RestTemplate as a Load Balancer Client</a></span></dt><dd><dl><dt><span class="section"><a href="#_retrying_failed_requests">2.3.1. Retrying Failed Requests</a></span></dt></dl></dd><dt><span class="section"><a href="#_multiple_resttemplate_objects">2.4. Multiple RestTemplate objects</a></span></dt><dt><span class="section"><a href="#ignore-network-interfaces">2.5. Ignore Network Interfaces</a></span></dt><dt><span class="section"><a href="#http-clients">2.6. HTTP Client Factories</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9" href="#d0e9"></a></h1></div></div></div><p><a class="link" href="http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook" target="_top">Cloud Native</a> is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building <a class="link" href="http://12factor.net/" target="_top">12-factor Apps</a> in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required.</p><p>Many of those features are covered by <a class="link" href="http://projects.spring.io/spring-boot" target="_top">Spring Boot</a>, which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the <code class="literal">ApplicationContext</code> of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).</p><p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html" target="_top">Java 6 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html" target="_top">Java 7 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html" target="_top">Java 8 JCE</a></li></ul></div><p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</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>Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <a class="link" href="https://github.com/spring-cloud/spring-cloud-commons/tree/master/docs/src/main/asciidoc" target="_top">github</a>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_context_application_context_services" href="#_spring_cloud_context_application_context_services"></a>1. Spring Cloud Context: Application Context Services</h1></div></div></div><p>Spring Boot has an opinionated view of how to build an application |
|
with Spring: for instance it has conventional locations for common |
|
configuration file, and endpoints for common management and monitoring |
|
tasks. Spring Cloud builds on top of that and adds a few features that |
|
probably all components in a system would use or occasionally need.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_the_bootstrap_application_context" href="#_the_bootstrap_application_context"></a>1.1 The Bootstrap Application Context</h2></div></div></div><p>A Spring Cloud application operates by creating a "bootstrap" |
|
context, which is a parent context for the main application. Out of |
|
the box it is responsible for loading configuration properties from |
|
the external sources, and also decrypting properties in the local |
|
external configuration files. The two contexts share an <code class="literal">Environment</code> |
|
which is the source of external properties for any Spring |
|
application. Bootstrap properties are added with high precedence, so |
|
they cannot be overridden by local configuration, by default.</p><p>The bootstrap context uses a different convention for locating |
|
external configuration than the main application context, so instead |
|
of <code class="literal">application.yml</code> (or <code class="literal">.properties</code>) you use <code class="literal">bootstrap.yml</code>, |
|
keeping the external configuration for bootstrap and main context |
|
nicely separate. Example:</p><p><b>bootstrap.yml. </b> |
|
</p><pre class="screen">spring: |
|
application: |
|
name: foo |
|
cloud: |
|
config: |
|
uri: ${SPRING_CONFIG_URI:http://localhost:8888}</pre><p> |
|
</p><p>It is a good idea to set the <code class="literal">spring.application.name</code> (in |
|
<code class="literal">bootstrap.yml</code> or <code class="literal">application.yml</code>) if your application needs any |
|
application-specific configuration from the server.</p><p>You can disable the bootstrap process completely by setting |
|
<code class="literal">spring.cloud.bootstrap.enabled=false</code> (e.g. in System properties).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_application_context_hierarchies" href="#_application_context_hierarchies"></a>1.2 Application Context Hierarchies</h2></div></div></div><p>If you build an application context from <code class="literal">SpringApplication</code> or |
|
<code class="literal">SpringApplicationBuilder</code>, then the Bootstrap context is added as a |
|
parent to that context. It is a feature of Spring that child contexts |
|
inherit property sources and profiles from their parent, so the "main" |
|
application context will contain additional property sources, compared |
|
to building the same context without Spring Cloud Config. The |
|
additional property sources are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">"bootstrap": an optional <code class="literal">CompositePropertySource</code> appears with high |
|
priority if any <code class="literal">PropertySourceLocators</code> are found in the Bootstrap |
|
context, and they have non-empty properties. An example would be |
|
properties from the Spring Cloud Config Server. See |
|
<a class="link" href="#customizing-bootstrap-property-sources" title="1.6 Customizing the Bootstrap Property Sources">below</a> for instructions |
|
on how to customize the contents of this property source.</li><li class="listitem">"applicationConfig: [classpath:bootstrap.yml]" (and friends if |
|
Spring profiles are active). If you have a <code class="literal">bootstrap.yml</code> (or |
|
properties) then those properties are used to configure the Bootstrap |
|
context, and then they get added to the child context when its parent |
|
is set. They have lower precedence than the <code class="literal">application.yml</code> (or |
|
properties) and any other property sources that are added to the child |
|
as a normal part of the process of creating a Spring Boot |
|
application. See <a class="link" href="#customizing-bootstrap-properties" title="1.3 Changing the Location of Bootstrap Properties">below</a> for |
|
instructions on how to customize the contents of these property |
|
sources.</li></ul></div><p>Because of the ordering rules of property sources the "bootstrap" |
|
entries take precedence, but note that these do not contain any data |
|
from <code class="literal">bootstrap.yml</code>, which has very low precedence, but can be used |
|
to set defaults.</p><p>You can extend the context hierarchy by simply setting the parent |
|
context of any <code class="literal">ApplicationContext</code> you create, e.g. using its own |
|
interface, or with the <code class="literal">SpringApplicationBuilder</code> convenience methods |
|
(<code class="literal">parent()</code>, <code class="literal">child()</code> and <code class="literal">sibling()</code>). The bootstrap context will be |
|
the parent of the most senior ancestor that you create yourself. |
|
Every context in the hierarchy will have its own "bootstrap" property |
|
source (possibly empty) to avoid promoting values inadvertently from |
|
parents down to their descendants. Every context in the hierarchy can |
|
also (in principle) have a different <code class="literal">spring.application.name</code> and |
|
hence a different remote property source if there is a Config |
|
Server. Normal Spring application context behaviour rules apply to |
|
property resolution: properties from a child context override those in |
|
the parent, by name and also by property source name (if the child has |
|
a property source with the same name as the parent, the one from the |
|
parent is not included in the child).</p><p>Note that the <code class="literal">SpringApplicationBuilder</code> allows you to share an |
|
<code class="literal">Environment</code> amongst the whole hierarchy, but that is not the |
|
default. Thus, sibling contexts in particular do not need to have the |
|
same profiles or property sources, even though they will share common |
|
things with their parent.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="customizing-bootstrap-properties" href="#customizing-bootstrap-properties"></a>1.3 Changing the Location of Bootstrap Properties</h2></div></div></div><p>The <code class="literal">bootstrap.yml</code> (or <code class="literal">.properties</code>) location can be specified using |
|
<code class="literal">spring.cloud.bootstrap.name</code> (default "bootstrap") or |
|
<code class="literal">spring.cloud.bootstrap.location</code> (default empty), e.g. in System |
|
properties. Those properties behave like the <code class="literal">spring.config.*</code> |
|
variants with the same name, in fact they are used to set up the |
|
bootstrap <code class="literal">ApplicationContext</code> by setting those properties in its |
|
<code class="literal">Environment</code>. If there is an active profile (from |
|
<code class="literal">spring.profiles.active</code> or through the <code class="literal">Environment</code> API in the |
|
context you are building) then properties in that profile will be |
|
loaded as well, just like in a regular Spring Boot app, e.g. from |
|
<code class="literal">bootstrap-development.properties</code> for a "development" profile.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="overriding-bootstrap-properties" href="#overriding-bootstrap-properties"></a>1.4 Overriding the Values of Remote Properties</h2></div></div></div><p>The property sources that are added to you application by the |
|
bootstrap context are often "remote" (e.g. from a Config Server), and |
|
by default they cannot be overridden locally, except on the command |
|
line. If you want to allow your applications to override the remote |
|
properties with their own System properties or config files, the |
|
remote property source has to grant it permission by setting |
|
<code class="literal">spring.cloud.config.allowOverride=true</code> (it doesn’t work to set this |
|
locally). Once that flag is set there are some finer grained settings |
|
to control the location of the remote properties in relation to System |
|
properties and the application’s local configuration: |
|
<code class="literal">spring.cloud.config.overrideNone=true</code> to override with any local |
|
property source, and |
|
<code class="literal">spring.cloud.config.overrideSystemProperties=false</code> if only System |
|
properties and env vars should override the remote settings, but not |
|
the local config files.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_the_bootstrap_configuration" href="#_customizing_the_bootstrap_configuration"></a>1.5 Customizing the Bootstrap Configuration</h2></div></div></div><p>The bootstrap context can be trained to do anything you like by adding |
|
entries to <code class="literal">/META-INF/spring.factories</code> under the key |
|
<code class="literal">org.springframework.cloud.bootstrap.BootstrapConfiguration</code>. This is |
|
a comma-separated list of Spring <code class="literal">@Configuration</code> classes which will |
|
be used to create the context. Any beans that you want to be available |
|
to the main application context for autowiring can be created here, |
|
and also there is a special contract for <code class="literal">@Beans</code> of type |
|
<code class="literal">ApplicationContextInitializer</code>. Classes can be marked with an <code class="literal">@Order</code> |
|
if you want to control the startup sequence (the default order is |
|
"last").</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Be careful when adding custom <code class="literal">BootstrapConfiguration</code> that the |
|
classes you add are not <code class="literal">@ComponentScanned</code> by mistake into your |
|
"main" application context, where they might not be needed. |
|
Use a separate package name for boot configuration classes that is |
|
not already covered by your <code class="literal">@ComponentScan</code> or <code class="literal">@SpringBootApplication</code> |
|
annotated configuration classes.</p></td></tr></table></div><p>The bootstrap process ends by injecting initializers into the main |
|
<code class="literal">SpringApplication</code> instance (i.e. the normal Spring Boot startup |
|
sequence, whether it is running as a standalone app or deployed in an |
|
application server). First a bootstrap context is created from the |
|
classes found in <code class="literal">spring.factories</code> and then all <code class="literal">@Beans</code> of type |
|
<code class="literal">ApplicationContextInitializer</code> are added to the main |
|
<code class="literal">SpringApplication</code> before it is started.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="customizing-bootstrap-property-sources" href="#customizing-bootstrap-property-sources"></a>1.6 Customizing the Bootstrap Property Sources</h2></div></div></div><p>The default property source for external configuration added by the |
|
bootstrap process is the Config Server, but you can add additional |
|
sources by adding beans of type <code class="literal">PropertySourceLocator</code> to the |
|
bootstrap context (via <code class="literal">spring.factories</code>). You could use this to |
|
insert additional properties from a different server, or from a |
|
database, for instance.</p><p>As an example, consider the following trivial custom locator:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomPropertySourceLocator <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> PropertySourceLocator { |
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> PropertySource<?> locate(Environment environment) { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MapPropertySource(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"customProperty"</span>, |
|
Collections.<String, Object>singletonMap(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"property.from.sample.custom.source"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"worked as intended"</span>)); |
|
} |
|
|
|
}</pre><p>The <code class="literal">Environment</code> that is passed in is the one for the |
|
<code class="literal">ApplicationContext</code> about to be created, i.e. the one that we are |
|
supplying additional property sources for. It will already have its |
|
normal Spring Boot-provided property sources, so you can use those to |
|
locate a property source specific to this <code class="literal">Environment</code> (e.g. by |
|
keying it on the <code class="literal">spring.application.name</code>, as is done in the default |
|
Config Server property source locator).</p><p>If you create a jar with this class in it and then add a |
|
<code class="literal">META-INF/spring.factories</code> containing:</p><pre class="screen">org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator</pre><p>then the "customProperty" <code class="literal">PropertySource</code> will show up in any |
|
application that includes that jar on its classpath.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_environment_changes" href="#_environment_changes"></a>1.7 Environment Changes</h2></div></div></div><p>The application will listen for an <code class="literal">EnvironmentChangeEvent</code> and react |
|
to the change in a couple of standard ways (additional |
|
<code class="literal">ApplicationListeners</code> can be added as <code class="literal">@Beans</code> by the user in the |
|
normal way). When an <code class="literal">EnvironmentChangeEvent</code> is observed it will |
|
have a list of key values that have changed, and the application will |
|
use those to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Re-bind any <code class="literal">@ConfigurationProperties</code> beans in the context</li><li class="listitem">Set the logger levels for any properties in <code class="literal">logging.level.*</code></li></ul></div><p>Note that the Config Client does not by default poll for changes in |
|
the <code class="literal">Environment</code>, and generally we would not recommend that approach |
|
for detecting changes (although you could set it up with a |
|
<code class="literal">@Scheduled</code> annotation). If you have a scaled-out client application |
|
then it is better to broadcast the <code class="literal">EnvironmentChangeEvent</code> to all |
|
the instances instead of having them polling for changes (e.g. using |
|
the <a class="link" href="https://github.com/spring-cloud/spring-cloud-bus" target="_top">Spring Cloud |
|
Bus</a>).</p><p>The <code class="literal">EnvironmentChangeEvent</code> covers a large class of refresh use |
|
cases, as long as you can actually make a change to the <code class="literal">Environment</code> |
|
and publish the event (those APIs are public and part of core |
|
Spring). You can verify the changes are bound to |
|
<code class="literal">@ConfigurationProperties</code> beans by visiting the <code class="literal">/configprops</code> |
|
endpoint (normal Spring Boot Actuator feature). For instance a |
|
<code class="literal">DataSource</code> can have its <code class="literal">maxPoolSize</code> changed at runtime (the |
|
default <code class="literal">DataSource</code> created by Spring Boot is an |
|
<code class="literal">@ConfigurationProperties</code> bean) and grow capacity |
|
dynamically. Re-binding <code class="literal">@ConfigurationProperties</code> does not cover |
|
another large class of use cases, where you need more control over the |
|
refresh, and where you need a change to be atomic over the whole |
|
<code class="literal">ApplicationContext</code>. To address those concerns we have |
|
<code class="literal">@RefreshScope</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_refresh_scope" href="#_refresh_scope"></a>1.8 Refresh Scope</h2></div></div></div><p>A Spring <code class="literal">@Bean</code> that is marked as <code class="literal">@RefreshScope</code> will get special |
|
treatment when there is a configuration change. This addresses the |
|
problem of stateful beans that only get their configuration injected |
|
when they are initialized. For instance if a <code class="literal">DataSource</code> has open |
|
connections when the database URL is changed via the <code class="literal">Environment</code>, we |
|
probably want the holders of those connections to be able to complete |
|
what they are doing. Then the next time someone borrows a connection |
|
from the pool he gets one with the new URL.</p><p>Refresh scope beans are lazy proxies that initialize when they are |
|
used (i.e. when a method is called), and the scope acts as a cache of |
|
initialized values. To force a bean to re-initialize on the next |
|
method call you just need to invalidate its cache entry.</p><p>The <code class="literal">RefreshScope</code> is a bean in the context and it has a public method |
|
<code class="literal">refreshAll()</code> to refresh all beans in the scope by clearing the |
|
target cache. There is also a <code class="literal">refresh(String)</code> method to refresh an |
|
individual bean by name. This functionality is exposed in the |
|
<code class="literal">/refresh</code> endpoint (over HTTP or JMX).</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">@RefreshScope</code> works (technically) on an <code class="literal">@Configuration</code> |
|
class, but it might lead to surprising behaviour: e.g. it does <span class="strong"><strong>not</strong></span> |
|
mean that all the <code class="literal">@Beans</code> defined in that class are themselves |
|
<code class="literal">@RefreshScope</code>. Specifically, anything that depends on those beans |
|
cannot rely on them being updated when a refresh is initiated, unless |
|
it is itself in <code class="literal">@RefreshScope</code> (in which it will be rebuilt on a |
|
refresh and its dependencies re-injected, at which point they will be |
|
re-initialized from the refreshed <code class="literal">@Configuration</code>).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_encryption_and_decryption" href="#_encryption_and_decryption"></a>1.9 Encryption and Decryption</h2></div></div></div><p>Spring Cloud has an <code class="literal">Environment</code> pre-processor for decrypting |
|
property values locally. It follows the same rules as the Config |
|
Server, and has the same external configuration via <code class="literal">encrypt.*</code>. Thus |
|
you can use encrypted values in the form <code class="literal">{cipher}*</code> and as long as |
|
there is a valid key then they will be decrypted before the main |
|
application context gets the <code class="literal">Environment</code>. To use the encryption |
|
features in an application you need to include Spring Security RSA in |
|
your classpath (Maven co-ordinates |
|
"org.springframework.security:spring-security-rsa") and you also need |
|
the full strength JCE extensions in your JVM.</p><p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html" target="_top">Java 6 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html" target="_top">Java 7 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html" target="_top">Java 8 JCE</a></li></ul></div><p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_endpoints" href="#_endpoints"></a>1.10 Endpoints</h2></div></div></div><p>For a Spring Boot Actuator application there are some additional management endpoints:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">POST to <code class="literal">/env</code> to update the <code class="literal">Environment</code> and rebind <code class="literal">@ConfigurationProperties</code> and log levels</li><li class="listitem"><code class="literal">/refresh</code> for re-loading the boot strap context and refreshing the <code class="literal">@RefreshScope</code> beans</li><li class="listitem"><code class="literal">/restart</code> for closing the <code class="literal">ApplicationContext</code> and restarting it (disabled by default)</li><li class="listitem"><code class="literal">/pause</code> and <code class="literal">/resume</code> for calling the <code class="literal">Lifecycle</code> methods (<code class="literal">stop()</code> and <code class="literal">start()</code> on the <code class="literal">ApplicationContext</code>)</li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_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><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="__enablediscoveryclient" href="#__enablediscoveryclient"></a>2.1 @EnableDiscoveryClient</h2></div></div></div><p>Commons provides the <code class="literal">@EnableDiscoveryClient</code> annotation. This looks for implementations of the <code class="literal">DiscoveryClient</code> interface via <code class="literal">META-INF/spring.factories</code>. Implementations of Discovery Client will add a configuration class to <code class="literal">spring.factories</code> under the <code class="literal">org.springframework.cloud.client.discovery.EnableDiscoveryClient</code> key. Examples of <code class="literal">DiscoveryClient</code> implementations: are <a class="link" href="http://cloud.spring.io/spring-cloud-netflix/" target="_top">Spring Cloud Netflix Eureka</a>, <a class="link" href="http://cloud.spring.io/spring-cloud-consul/" target="_top">Spring Cloud Consul Discovery</a> and <a class="link" href="http://cloud.spring.io/spring-cloud-zookeeper/" target="_top">Spring Cloud Zookeeper Discovery</a>.</p><p>By default, implementations of <code class="literal">DiscoveryClient</code> will auto-register the local Spring Boot server with the remote discovery server. This can be disabled by setting <code class="literal">autoRegister=false</code> in <code class="literal">@EnableDiscoveryClient</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_health_indicator" href="#_health_indicator"></a>2.1.1 Health Indicator</h3></div></div></div><p>Commons creates a Spring Boot <code class="literal">HealthIndicator</code> that <code class="literal">DiscoveryClient</code> implementations can participate in by implementing <code class="literal">DiscoveryHealthIndicator</code>. To disable the composite <code class="literal">HealthIndicator</code> set <code class="literal">spring.cloud.discovery.client.composite-indicator.enabled=false</code>. A generic <code class="literal">HealthIndicator</code> based on <code class="literal">DiscoveryClient</code> is auto-configured (<code class="literal">DiscoveryClientHealthIndicator). To disable it, set `spring.cloud.discovery.client.health-indicator.enabled=false</code>. To disable the description field of the <code class="literal">DiscoveryClientHealthIndicator</code> set <code class="literal">spring.cloud.discovery.client.health-indicator.include-description=false</code>, otherwise it can bubble up as the <code class="literal">description</code> of the rolled up <code class="literal">HealthIndicator</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_serviceregistry" href="#_serviceregistry"></a>2.2 ServiceRegistry</h2></div></div></div><p>Commons now provides a <code class="literal">ServiceRegistry</code> interface which provides methods like <code class="literal">register(Registration)</code> and <code class="literal">deregister(Registration)</code> which allow you to provide custom registered services. <code class="literal">Registration</code> is a marker interface.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em> |
|
<em><span class="hl-annotation" style="color: gray">@EnableDiscoveryClient(autoRegister=false)</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ServiceRegistry registry; |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MyConfiguration(ServiceRegistry registry) { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.registry = registry; |
|
} |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// called via some external process, such as an event or a custom actuator endpoint</span> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> register() { |
|
Registration registration = constructRegistration(); |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.registry.register(registration); |
|
} |
|
}</pre><p>Each <code class="literal">ServiceRegistry</code> implementation has its own <code class="literal">Registry</code> implementation.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_serviceregistry_auto_registration" href="#_serviceregistry_auto_registration"></a>2.2.1 ServiceRegistry Auto-Registration</h3></div></div></div><p>By default, the <code class="literal">ServiceRegistry</code> implementation will auto-register the running service. To disable that behavior, there are two methods. You can set <code class="literal">@EnableDiscoveryClient(autoRegister=false)</code> to permanently disable auto-registration. You can also set <code class="literal">spring.cloud.service-registry.auto-registration.enabled=false</code> to disable the behavior via configuration.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_service_registry_actuator_endpoint" href="#_service_registry_actuator_endpoint"></a>2.2.2 Service Registry Actuator Endpoint</h3></div></div></div><p>A <code class="literal">/service-registry</code> actuator endpoint is provided by Commons. This endpoint relys on a <code class="literal">Registration</code> bean in the Spring Application Context. Calling <code class="literal">/service-registry/instance-status</code> via a GET will return the status of the <code class="literal">Registration</code>. A POST to the same endpoint with a <code class="literal">String</code> body will change the status of the current <code class="literal">Registration</code> to the new value. Please see the documentation of the <code class="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><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_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><code class="literal">RestTemplate</code> can be automatically configured to use ribbon. To create a load balanced <code class="literal">RestTemplate</code> create a <code class="literal">RestTemplate</code> <code class="literal">@Bean</code> and use the <code class="literal">@LoadBalanced</code> qualifier.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>A <code class="literal">RestTemplate</code> bean is no longer created via auto configuration. It must be created by individual applications.</p></td></tr></table></div><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration { |
|
|
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em> |
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em> |
|
RestTemplate restTemplate() { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate(); |
|
} |
|
} |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass { |
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate restTemplate; |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doOtherStuff() { |
|
String results = restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://stores/stores"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>); |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> results; |
|
} |
|
}</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. See |
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java" target="_top">RibbonAutoConfiguration</a> |
|
for details of how the <code class="literal">RestTemplate</code> is set up.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_retrying_failed_requests" href="#_retrying_failed_requests"></a>2.3.1 Retrying Failed Requests</h3></div></div></div><p>A load balanced <code class="literal">RestTemplate</code> can be configured to retry failed requests. |
|
By default this logic is disabled, you can enable it by adding <a class="link" href="https://github.com/spring-projects/spring-retry" target="_top">Spring Retry</a> to your application’s classpath. The load balanced <code class="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 <code class="literal">spring.cloud.loadbalancer.retry.enabled=false</code>. |
|
The properties you can use are <code class="literal">client.ribbon.MaxAutoRetries</code>, |
|
<code class="literal">client.ribbon.MaxAutoRetriesNextServer</code>, and <code class="literal">client.ribbon.OkToRetryOnAllOperations</code>. |
|
See the <a class="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><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">client</code> in the above examples should be replaced with your Ribbon client’s |
|
name.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_multiple_resttemplate_objects" href="#_multiple_resttemplate_objects"></a>2.4 Multiple RestTemplate objects</h2></div></div></div><p>If you want a <code class="literal">RestTemplate</code> that is not load balanced, create a <code class="literal">RestTemplate</code> |
|
bean and inject it as normal. To access the load balanced <code class="literal">RestTemplate</code> use |
|
the <code class="literal">@LoadBalanced</code> qualifier when you create your <code class="literal">@Bean</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Notice the <code class="literal">@Primary</code> annotation on the plain <code class="literal">RestTemplate</code> declaration in the example below, to disambiguate the unqualified <code class="literal">@Autowired</code> injection.</p></td></tr></table></div><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration { |
|
|
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em> |
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em> |
|
RestTemplate loadBalanced() { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate(); |
|
} |
|
|
|
<em><span class="hl-annotation" style="color: gray">@Primary</span></em> |
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em> |
|
RestTemplate restTemplate() { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate(); |
|
} |
|
} |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass { |
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate restTemplate; |
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> |
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em> |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate loadBalanced; |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doOtherStuff() { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> loadBalanced.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://stores/stores"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>); |
|
} |
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doStuff() { |
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://example.com"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>); |
|
} |
|
}</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you see errors like <code class="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 <code class="literal">RestOperations</code> instead or setting <code class="literal">spring.aop.proxyTargetClass=true</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ignore-network-interfaces" href="#ignore-network-interfaces"></a>2.5 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><pre class="screen">spring: |
|
cloud: |
|
inetutils: |
|
ignoredInterfaces: |
|
- docker0 |
|
- veth.*</pre><p> |
|
</p><p>You can also force to use only specified network addresses using list of regular expressions:</p><p><b>application.yml. </b> |
|
</p><pre class="screen">spring: |
|
cloud: |
|
inetutils: |
|
preferredNetworks: |
|
- 192.168 |
|
- 10.0</pre><p> |
|
</p><p>You can also force to use only site local addresses. See <a class="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> |
|
</p><pre class="screen">spring: |
|
cloud: |
|
inetutils: |
|
useOnlySiteLocalInterfaces: true</pre><p> |
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="http-clients" href="#http-clients"></a>2.6 HTTP Client Factories</h2></div></div></div><p>Spring Cloud Commons provides beans for creating both Apache HTTP clients (<code class="literal">ApacheHttpClientFactory</code>) |
|
as well as OK HTTP clients (<code class="literal">OkHttpClientFactory</code>). The <code class="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, <code class="literal">ApacheHttpClientConnectionManagerFactory</code> for the Apache |
|
HTTP client and <code class="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 |
|
<code class="literal">spring.cloud.httpclientfactories.apache.enabled</code> or <code class="literal">spring.cloud.httpclientfactories.ok.enabled</code> to |
|
<code class="literal">false</code>.</p></div></div></div></body></html> |