Split files

docs/modules/modules/ROOT/pages/spring-cloud-commons/cachedrandompropertysource.adoc

@@ -0,0 +1,16 @@
+[[cachedrandompropertysource]]
+= CachedRandomPropertySource
+
+Spring Cloud Context provides a `PropertySource` that caches random values based on a key.  Outside of the caching
+functionality it works the same as Spring Boot's https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/env/RandomValuePropertySource.java[`RandomValuePropertySource`].
+This random value might be useful in the case where you want a random value that is consistent even after the Spring Application
+context restarts.  The property value takes the form of `cachedrandom.[yourkey].[type]` where `yourkey` is the key in the cache.  The `type` value can
+be any type supported by Spring Boot's `RandomValuePropertySource`.
+
+====
+[source,properties,indent=0]
+----
+myrandom=${cachedrandom.appname.value}
+----
+====
+

docs/modules/modules/ROOT/pages/spring-cloud-commons/circuit-breaker.adoc

@@ -0,0 +1,5 @@
+[[spring-cloud-circuit-breaker]]
+= Spring Cloud Circuit Breaker
+
+include:../:spring-cloud-circuitbreaker.adoc[leveloffset=+1]
+

docs/modules/modules/ROOT/pages/spring-cloud-commons/commons:-common-abstractions.adoc

@@ -0,0 +1,623 @@
+[[spring-cloud-commons:-common-abstractions]]
+= Spring Cloud Commons: Common Abstractions
+
+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 (for example, discovery with Eureka or Consul).
+
+[[discovery-client]]
+== The `@EnableDiscoveryClient` Annotation
+
+Spring Cloud Commons provides the `@EnableDiscoveryClient` annotation.
+This looks for implementations of the `DiscoveryClient` and `ReactiveDiscoveryClient` interfaces with `META-INF/spring.factories`.
+Implementations of the discovery client add a configuration class to `spring.factories` under the `org.springframework.cloud.client.discovery.EnableDiscoveryClient` key.
+Examples of `DiscoveryClient` implementations include https://cloud.spring.io/spring-cloud-netflix/[Spring Cloud Netflix Eureka], https://cloud.spring.io/spring-cloud-consul/[Spring Cloud Consul Discovery], and https://cloud.spring.io/spring-cloud-zookeeper/[Spring Cloud Zookeeper Discovery].
+
+Spring Cloud will provide both the blocking and reactive service discovery clients by default.
+You can disable the blocking and/or reactive clients easily by setting `spring.cloud.discovery.blocking.enabled=false` or `spring.cloud.discovery.reactive.enabled=false`.
+To completely disable service discovery you just need to set `spring.cloud.discovery.enabled=false`.
+
+By default, implementations of `DiscoveryClient` auto-register the local Spring Boot server with the remote discovery server.
+This behavior can be disabled by setting `autoRegister=false` in `@EnableDiscoveryClient`.
+
+NOTE: `@EnableDiscoveryClient` is no longer required.
+You can put a `DiscoveryClient` implementation on the classpath to cause the Spring Boot application to register with the service discovery server.
+
+[[health-indicators]]
+=== Health Indicators
+
+Commons auto-configures the following Spring Boot health indicators.
+
+[[discoveryclienthealthindicator]]
+==== DiscoveryClientHealthIndicator
+This health indicator is based on the currently registered `DiscoveryClient` implementation.
+
+* To disable entirely, set `spring.cloud.discovery.client.health-indicator.enabled=false`.
+* To disable the description field, set `spring.cloud.discovery.client.health-indicator.include-description=false`.
+Otherwise, it can bubble up as the `description` of the rolled up `HealthIndicator`.
+* To disable service retrieval, set `spring.cloud.discovery.client.health-indicator.use-services-query=false`.
+By default, the indicator invokes the client's `getServices` method. In deployments with many registered services it may too
+costly to retrieve all services during every check. This will skip the service retrieval and instead use the client's `probe` method.
+
+[[discoverycompositehealthcontributor]]
+==== DiscoveryCompositeHealthContributor
+This composite health indicator is based on all registered `DiscoveryHealthIndicator` beans. To disable,
+set `spring.cloud.discovery.client.composite-indicator.enabled=false`.
+
+[[ordering-discoveryclient-instances]]
+=== Ordering `DiscoveryClient` instances
+`DiscoveryClient` interface extends `Ordered`. This is useful when using multiple discovery
+ clients, as it allows you to define the order of the returned discovery clients, similar to
+how you can order the beans loaded by a Spring application. By default, the order of any `DiscoveryClient` is set to
+`0`. If you want to set a different order for your custom `DiscoveryClient` implementations, you just need to override
+the `getOrder()` method so that it returns the value that is suitable for your setup. Apart from this, you can use
+properties to set the order of the `DiscoveryClient`
+implementations provided by Spring Cloud, among others  `ConsulDiscoveryClient`, `EurekaDiscoveryClient` and
+`ZookeeperDiscoveryClient`. In order to do it, you just need to set the
+`spring.cloud.{clientIdentifier}.discovery.order` (or `eureka.client.order` for Eureka) property to the desired value.
+
+[[simplediscoveryclient]]
+=== SimpleDiscoveryClient
+
+If there is no Service-Registry-backed `DiscoveryClient` in the classpath, `SimpleDiscoveryClient`
+instance, that uses properties to get information on service and instances, will be used.
+
+The information about the available instances should be passed to via properties in the following format:
+`spring.cloud.discovery.client.simple.instances.service1[0].uri=http://s11:8080`, where
+`spring.cloud.discovery.client.simple.instances` is the common prefix, then `service1` stands
+for the ID of the service in question, while `[0]` indicates the index number of the instance
+(as visible in the example, indexes start with `0`), and then the value of `uri` is
+the actual URI under which the instance is available.
+
+[[serviceregistry]]
+== ServiceRegistry
+
+Commons now provides a `ServiceRegistry` interface that provides methods such as `register(Registration)` and `deregister(Registration)`, which let you provide custom registered services.
+`Registration` is a marker interface.
+
+The following example shows the `ServiceRegistry` in use:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+@EnableDiscoveryClient(autoRegister=false)
+public class MyConfiguration {
+    private ServiceRegistry registry;
+
+    public MyConfiguration(ServiceRegistry registry) {
+        this.registry = registry;
+    }
+
+    // called through some external process, such as an event or a custom actuator endpoint
+    public void register() {
+        Registration registration = constructRegistration();
+        this.registry.register(registration);
+    }
+}
+----
+====
+
+Each `ServiceRegistry` implementation has its own `Registry` implementation.
+
+* `ZookeeperRegistration` used with `ZookeeperServiceRegistry`
+* `EurekaRegistration` used with `EurekaServiceRegistry`
+* `ConsulRegistration` used with `ConsulServiceRegistry`
+
+If you are using the `ServiceRegistry` interface, you are going to need to pass the
+correct `Registry` implementation for the `ServiceRegistry` implementation you
+are using.
+
+
+[[serviceregistry-auto-registration]]
+=== ServiceRegistry Auto-Registration
+
+By default, the `ServiceRegistry` implementation auto-registers the running service.
+To disable that behavior, you can set:
+* `@EnableDiscoveryClient(autoRegister=false)` to permanently disable auto-registration.
+* `spring.cloud.service-registry.auto-registration.enabled=false` to disable the behavior through configuration.
+
+[[serviceregistry-auto-registration-events]]
+==== ServiceRegistry Auto-Registration Events
+
+There are two events that will be fired when a service auto-registers.  The first event, called
+`InstancePreRegisteredEvent`, is fired before the service is registered.  The second
+event, called `InstanceRegisteredEvent`, is fired after the service is registered.  You can register an
+`ApplicationListener`(s) to listen to and react to these events.
+
+NOTE: These events will not be fired if the `spring.cloud.service-registry.auto-registration.enabled` property is set to `false`.
+
+[[service-registry-actuator-endpoint]]
+=== Service Registry Actuator Endpoint
+
+Spring Cloud Commons provides a `/service-registry` actuator endpoint.
+This endpoint relies on a `Registration` bean in the Spring Application Context.
+Calling `/service-registry` with GET returns the status of the `Registration`.
+Using POST to the same endpoint with a JSON body changes the status of the current `Registration` to the new value.
+The JSON body has to include the `status` field with the preferred value.
+Please see the documentation of the `ServiceRegistry` implementation you use for the allowed values when updating the status and the values returned for the status.
+For instance, Eureka's supported statuses are `UP`, `DOWN`, `OUT_OF_SERVICE`, and `UNKNOWN`.
+
+[[rest-template-loadbalancer-client]]
+== Spring RestTemplate as a Load Balancer Client
+
+You can configure a `RestTemplate` to use a Load-balancer client.
+To create a load-balanced `RestTemplate`, create a `RestTemplate` `@Bean` and use the `@LoadBalanced` qualifier, as the following example shows:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+
+    @LoadBalanced
+    @Bean
+    RestTemplate restTemplate() {
+        return new RestTemplate();
+    }
+}
+
+public class MyClass {
+    @Autowired
+    private RestTemplate restTemplate;
+
+    public String doOtherStuff() {
+        String results = restTemplate.getForObject("http://stores/stores", String.class);
+        return results;
+    }
+}
+----
+====
+
+CAUTION: A `RestTemplate` bean is no longer created through auto-configuration.
+Individual applications must create it.
+
+The URI needs to use a virtual host name (that is, a service name, not a host name).
+The BlockingLoadBalancerClient is used to create a full physical address.
+
+IMPORTANT: To use a load-balanced `RestTemplate`, you need to have a load-balancer implementation in your classpath.
+Add <<spring-cloud-loadbalancer-starter, Spring Cloud LoadBalancer starter>> to your project in order to use it.
+
+[[webclinet-loadbalancer-client]]
+== Spring WebClient as a Load Balancer Client
+
+You can configure `WebClient` to automatically use a load-balancer client.
+To create a load-balanced `WebClient`, create a `WebClient.Builder` `@Bean` and use the `@LoadBalanced` qualifier, as follows:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+
+	@Bean
+	@LoadBalanced
+	public WebClient.Builder loadBalancedWebClientBuilder() {
+		return WebClient.builder();
+	}
+}
+
+public class MyClass {
+    @Autowired
+    private WebClient.Builder webClientBuilder;
+
+    public Mono<String> doOtherStuff() {
+        return webClientBuilder.build().get().uri("http://stores/stores")
+        				.retrieve().bodyToMono(String.class);
+    }
+}
+----
+====
+
+The URI needs to use a virtual host name (that is, a service name, not a host name).
+The Spring Cloud LoadBalancer is used to create a full physical address.
+
+IMPORTANT: If you want to use a `@LoadBalanced WebClient.Builder`, you need to have a load balancer
+implementation in the classpath. We recommend that you add the
+<<spring-cloud-loadbalancer-starter, Spring Cloud LoadBalancer starter>> to your project.
+Then, `ReactiveLoadBalancer` is used underneath.
+
+[[retrying-failed-requests]]
+=== Retrying Failed Requests
+
+A load-balanced `RestTemplate` can be configured to retry failed requests.
+By default, this logic is disabled.
+For the non-reactive version (with `RestTemplate`), you can enable it by adding link:https://github.com/spring-projects/spring-retry[Spring Retry] to your application's classpath. For the reactive version (with `WebTestClient`), you need to set `spring.cloud.loadbalancer.retry.enabled=true`.
+
+If you would like to disable the retry logic with Spring Retry or Reactive Retry on the classpath, you can set `spring.cloud.loadbalancer.retry.enabled=false`.
+
+For the non-reactive implementation, if you would like to implement a `BackOffPolicy` in your retries, you need to create a bean of type `LoadBalancedRetryFactory` and override the `createBackOffPolicy()` method.
+
+For the reactive implementation, you just need to enable it by setting `spring.cloud.loadbalancer.retry.backoff.enabled` to `false`.
+
+You can set:
+
+- `spring.cloud.loadbalancer.retry.maxRetriesOnSameServiceInstance` - indicates how many times a request should be retried on the same `ServiceInstance` (counted separately for every selected instance)
+- `spring.cloud.loadbalancer.retry.maxRetriesOnNextServiceInstance` - indicates how many times a request should be retried a newly selected `ServiceInstance`
+- `spring.cloud.loadbalancer.retry.retryableStatusCodes` - the status codes on which to always retry a failed request.
+
+For the reactive implementation, you can additionally set:
+ - `spring.cloud.loadbalancer.retry.backoff.minBackoff` - Sets the minimum backoff duration (by default, 5 milliseconds)
+ - `spring.cloud.loadbalancer.retry.backoff.maxBackoff` - Sets the maximum backoff duration (by default, max long value of milliseconds)
+ - `spring.cloud.loadbalancer.retry.backoff.jitter` - Sets the jitter used for calculating the actual backoff duration for each call (by default, 0.5).
+
+For the reactive implementation, you can also implement your own `LoadBalancerRetryPolicy` to have more detailed control over the load-balanced call retries.
+
+For both implementations, you can also set the exceptions that trigger the replies by adding a list of values under the `spring.cloud.loadbalancer.[serviceId].retry.retryable-exceptions` property. If you do, we make sure to add `RetryableStatusCodeExceptions` to the list of exceptions provided by you, so that we also retry on retryable status codes. If you do not specify any exceptions via properties, the exceptions we use by default are `IOException`, `TimeoutException` and `RetryableStatusCodeException`. You can also enable retrying on all exceptions by setting `spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions` to `true`.
+
+WARNING: If you use the blocking implementation with Spring Retries, if you want to keep the behaviour from previous releases, set `spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions` to `true` as that used to be the default mode for the blocking implementation.
+
+NOTE: Individual Loadbalancer clients may be configured individually with the same properties as above except the prefix is `spring.cloud.loadbalancer.clients.<clientId>.*` where `clientId` is the name of the loadbalancer.
+
+NOTE: For load-balanced retries, by default, we wrap the `ServiceInstanceListSupplier` bean with `RetryAwareServiceInstanceListSupplier` to select a different instance from the one previously chosen, if available. You can disable this behavior by setting the value of `spring.cloud.loadbalancer.retry.avoidPreviousInstance` to `false`.
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+    @Bean
+    LoadBalancedRetryFactory retryFactory() {
+        return new LoadBalancedRetryFactory() {
+            @Override
+            public BackOffPolicy createBackOffPolicy(String service) {
+        		return new ExponentialBackOffPolicy();
+        	}
+        };
+    }
+}
+----
+====
+
+If you want to add one or more `RetryListener` implementations to your retry functionality, you need to
+create a bean of type `LoadBalancedRetryListenerFactory` and return the `RetryListener` array
+you would like to use for a given service, as the following example shows:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+    @Bean
+    LoadBalancedRetryListenerFactory retryListenerFactory() {
+        return new LoadBalancedRetryListenerFactory() {
+            @Override
+            public RetryListener[] createRetryListeners(String service) {
+                return new RetryListener[]{new RetryListener() {
+                    @Override
+                    public <T, E extends Throwable> boolean open(RetryContext context, RetryCallback<T, E> callback) {
+                        //TODO Do you business...
+                        return true;
+                    }
+
+                    @Override
+                     public <T, E extends Throwable> void close(RetryContext context, RetryCallback<T, E> callback, Throwable throwable) {
+                        //TODO Do you business...
+                    }
+
+                    @Override
+                    public <T, E extends Throwable> void onError(RetryContext context, RetryCallback<T, E> callback, Throwable throwable) {
+                        //TODO Do you business...
+                    }
+                }};
+            }
+        };
+    }
+}
+----
+====
+
+[[multiple-resttemplate-objects]]
+== Multiple `RestTemplate` Objects
+
+If you want a `RestTemplate` that is not load-balanced, create a `RestTemplate` bean and inject it.
+To access the load-balanced `RestTemplate`, use the `@LoadBalanced` qualifier when you create your `@Bean`, as the following example shows:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+
+    @LoadBalanced
+    @Bean
+    RestTemplate loadBalanced() {
+        return new RestTemplate();
+    }
+
+    @Primary
+    @Bean
+    RestTemplate restTemplate() {
+        return new RestTemplate();
+    }
+}
+
+public class MyClass {
+    @Autowired
+    private RestTemplate restTemplate;
+
+    @Autowired
+    @LoadBalanced
+    private RestTemplate loadBalanced;
+
+    public String doOtherStuff() {
+        return loadBalanced.getForObject("http://stores/stores", String.class);
+    }
+
+    public String doStuff() {
+        return restTemplate.getForObject("http://example.com", String.class);
+    }
+}
+----
+====
+
+IMPORTANT: Notice the use of the `@Primary` annotation on the plain `RestTemplate` declaration in the preceding example to disambiguate the unqualified `@Autowired` injection.
+
+TIP: If you see errors such as `java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89`, try injecting `RestOperations` or setting `spring.aop.proxyTargetClass=true`.
+
+[[multiple-webclient-objects]]
+== Multiple WebClient Objects
+
+If you want a `WebClient` that is not load-balanced, create a `WebClient` bean and inject it.
+To access the load-balanced `WebClient`, use the `@LoadBalanced` qualifier when you create your `@Bean`, as the following example shows:
+
+====
+[source,java,indent=0]
+----
+@Configuration
+public class MyConfiguration {
+
+    @LoadBalanced
+    @Bean
+    WebClient.Builder loadBalanced() {
+        return WebClient.builder();
+    }
+
+    @Primary
+    @Bean
+    WebClient.Builder webClient() {
+        return WebClient.builder();
+    }
+}
+
+public class MyClass {
+    @Autowired
+    private WebClient.Builder webClientBuilder;
+
+    @Autowired
+    @LoadBalanced
+    private WebClient.Builder loadBalanced;
+
+    public Mono<String> doOtherStuff() {
+        return loadBalanced.build().get().uri("http://stores/stores")
+        				.retrieve().bodyToMono(String.class);
+    }
+
+    public Mono<String> doStuff() {
+        return webClientBuilder.build().get().uri("http://example.com")
+        				.retrieve().bodyToMono(String.class);
+    }
+}
+----
+====
+
+[[loadbalanced-webclient]]
+== Spring WebFlux `WebClient` as a Load Balancer Client
+
+The Spring WebFlux can work with both reactive and non-reactive `WebClient` configurations, as the topics describe:
+
+* <<webflux-with-reactive-loadbalancer>>
+* <<load-balancer-exchange-filter-function>>
+
+[[webflux-with-reactive-loadbalancer]]
+=== Spring WebFlux `WebClient` with `ReactorLoadBalancerExchangeFilterFunction`
+
+You can configure `WebClient` to use the `ReactiveLoadBalancer`.
+If you add <<spring-cloud-loadbalancer-starter, Spring Cloud LoadBalancer starter>> to your project
+and if `spring-webflux` is on the classpath, `ReactorLoadBalancerExchangeFilterFunction` is auto-configured.
+The following example shows how to configure a `WebClient` to use reactive load-balancer:
+
+====
+[source,java,indent=0]
+----
+public class MyClass {
+    @Autowired
+    private ReactorLoadBalancerExchangeFilterFunction lbFunction;
+
+    public Mono<String> doOtherStuff() {
+        return WebClient.builder().baseUrl("http://stores")
+            .filter(lbFunction)
+            .build()
+            .get()
+            .uri("/stores")
+            .retrieve()
+            .bodyToMono(String.class);
+    }
+}
+----
+====
+
+The URI needs to use a virtual host name (that is, a service name, not a host name).
+The `ReactorLoadBalancer` is used to create a full physical address.
+
+[[load-balancer-exchange-filter-function]]
+=== Spring WebFlux `WebClient` with a Non-reactive Load Balancer Client
+
+If `spring-webflux` is on the classpath, `LoadBalancerExchangeFilterFunction`
+is auto-configured. Note, however, that this
+uses a non-reactive client under the hood.
+The following example shows how to configure a `WebClient` to use load-balancer:
+
+====
+[source,java,indent=0]
+----
+public class MyClass {
+    @Autowired
+    private LoadBalancerExchangeFilterFunction lbFunction;
+
+    public Mono<String> doOtherStuff() {
+        return WebClient.builder().baseUrl("http://stores")
+            .filter(lbFunction)
+            .build()
+            .get()
+            .uri("/stores")
+            .retrieve()
+            .bodyToMono(String.class);
+    }
+}
+----
+====
+
+The URI needs to use a virtual host name (that is, a service name, not a host name).
+The `LoadBalancerClient` is used to create a full physical address.
+
+WARN: This approach is now deprecated.
+We suggest that you use <<webflux-with-reactive-loadbalancer,WebFlux with reactive Load-Balancer>>
+instead.
+
+[[ignore-network-interfaces]]
+== Ignore Network Interfaces
+
+Sometimes, it is useful to ignore certain named network interfaces so that they can be excluded from Service Discovery registration (for example, when running in a Docker container).
+A list of regular expressions can be set to cause the desired network interfaces to be ignored.
+The following configuration ignores the `docker0` interface and all interfaces that start with `veth`:
+
+.application.yml
+====
+----
+spring:
+  cloud:
+    inetutils:
+      ignoredInterfaces:
+        - docker0
+        - veth.*
+----
+====
+
+You can also force the use of only specified network addresses by using a list of regular expressions, as the following example shows:
+
+.bootstrap.yml
+====
+----
+spring:
+  cloud:
+    inetutils:
+      preferredNetworks:
+        - 192.168
+        - 10.0
+----
+====
+
+You can also force the use of only site-local addresses, as the following example shows:
+
+.application.yml
+====
+----
+spring:
+  cloud:
+    inetutils:
+      useOnlySiteLocalInterfaces: true
+----
+====
+
+See https://docs.oracle.com/javase/8/docs/api/java/net/Inet4Address.html#isSiteLocalAddress--[Inet4Address.html.isSiteLocalAddress()] for more details about what constitutes a site-local address.
+
+[[http-clients]]
+== HTTP Client Factories
+
+Spring Cloud Commons provides beans for creating both Apache HTTP clients (`ApacheHttpClientFactory`) and OK HTTP clients (`OkHttpClientFactory`).
+The `OkHttpClientFactory` bean is created only 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: `ApacheHttpClientConnectionManagerFactory` for the Apache HTTP client and `OkHttpClientConnectionPoolFactory` for the OK HTTP client.
+If you would like to customize how the HTTP clients are created in downstream projects, you can provide your own implementation of these beans.
+In addition, if you provide a bean of type `HttpClientBuilder` or `OkHttpClient.Builder`, the default factories use these builders as the basis for the builders returned to downstream projects.
+You can also disable the creation of these beans by setting `spring.cloud.httpclientfactories.apache.enabled` or `spring.cloud.httpclientfactories.ok.enabled` to `false`.
+
+[[enabled-features]]
+== Enabled Features
+
+Spring Cloud Commons provides a `/features` actuator endpoint.
+This endpoint returns features available on the classpath and whether they are enabled.
+The information returned includes the feature type, name, version, and vendor.
+
+[[feature-types]]
+=== Feature types
+
+There are two types of 'features': abstract and named.
+
+Abstract features are features where an interface or abstract class is defined and that an implementation the creates, such as `DiscoveryClient`, `LoadBalancerClient`, or `LockService`.
+The abstract class or interface is used to find a bean of that type in the context.
+The version displayed is `bean.getClass().getPackage().getImplementationVersion()`.
+
+Named features are features that do not have a particular class they implement. These features include "`Circuit Breaker`", "`API Gateway`", "`Spring Cloud Bus`", and others. These features require a name and a bean type.
+
+[[declaring-features]]
+=== Declaring features
+
+Any module can declare any number of `HasFeature` beans, as the following examples show:
+
+====
+[source,java,indent=0]
+----
+@Bean
+public HasFeatures commonsFeatures() {
+  return HasFeatures.abstractFeatures(DiscoveryClient.class, LoadBalancerClient.class);
+}
+
+@Bean
+public HasFeatures consulFeatures() {
+  return HasFeatures.namedFeatures(
+    new NamedFeature("Spring Cloud Bus", ConsulBusAutoConfiguration.class),
+    new NamedFeature("Circuit Breaker", HystrixCommandAspect.class));
+}
+
+@Bean
+HasFeatures localFeatures() {
+  return HasFeatures.builder()
+      .abstractFeature(Something.class)
+      .namedFeature(new NamedFeature("Some Other Feature", Someother.class))
+      .abstractFeature(Somethingelse.class)
+      .build();
+}
+----
+====
+
+Each of these beans should go in an appropriately guarded `@Configuration`.
+
+
+[[spring-cloud-compatibility-verification]]
+== Spring Cloud Compatibility Verification
+
+Due to the fact that some users have problem with setting up Spring Cloud application, we've decided
+to add a compatibility verification mechanism. It will break if your current setup is not compatible
+with Spring Cloud requirements, together with a report, showing what exactly went wrong.
+
+At the moment we verify which version of Spring Boot is added to your classpath.
+
+Example of a report
+
+====
+----
+***************************
+APPLICATION FAILED TO START
+***************************
+
+Description:
+
+Your project setup is incompatible with our requirements due to following reasons:
+
+- Spring Boot [2.1.0.RELEASE] is not compatible with this Spring Cloud release train
+
+
+Action:
+
+Consider applying the following actions:
+
+- Change Spring Boot version to one of the following versions [1.2.x, 1.3.x] .
+You can find the latest Spring Boot versions here [https://spring.io/projects/spring-boot#learn].
+If you want to learn more about the Spring Cloud Release train compatibility, you can visit this page [https://spring.io/projects/spring-cloud#overview] and check the [Release Trains] section.
+----
+====
+
+In order to disable this feature, set `spring.cloud.compatibility-verifier.enabled` to `false`.
+If you want to override the compatible Spring Boot versions, just set the
+`spring.cloud.compatibility-verifier.compatible-boot-versions` property with a comma separated list
+of compatible Spring Boot versions.
+

docs/modules/modules/ROOT/pages/spring-cloud-commons/configuration-properties.adoc

@@ -0,0 +1,4 @@
+[[configuration-properties]]
+= Configuration Properties
+
+To see the list of all Spring Cloud Commons related configuration properties please check link:appendix.html[the Appendix page].

docs/modules/modules/ROOT/pages/spring-cloud-commons/context:-application-context-services.adoc

@@ -0,0 +1,255 @@
+[[spring-cloud-context:-application-context-services]]
+= Spring Cloud Context: Application Context Services
+
+Spring Boot has an opinionated view of how to build an application with Spring.
+For instance, it has conventional locations for common configuration files and has endpoints for common management and monitoring tasks.
+Spring Cloud builds on top of that and adds a few features that many components in a system would use or occasionally need.
+
+[[the-bootstrap-application-context]]
+== The Bootstrap Application Context
+
+A Spring Cloud application operates by creating a "`bootstrap`" context, which is a parent context for the main application.
+This context is responsible for loading configuration properties from the external sources and for decrypting properties in the local external configuration files.
+The two contexts share an `Environment`, which is the source of external properties for any Spring application.
+By default, bootstrap properties (not `bootstrap.properties` but properties that are loaded during the bootstrap phase) are added with high precedence, so they cannot be overridden by local configuration.
+
+The bootstrap context uses a different convention for locating external configuration than the main application context.
+Instead of `application.yml` (or `.properties`), you can use `bootstrap.yml`, keeping the external configuration for bootstrap and main context nicely separate.
+The following listing shows an example:
+
+.bootstrap.yml
+====
+----
+spring:
+  application:
+    name: foo
+  cloud:
+    config:
+      uri: ${SPRING_CONFIG_URI:http://localhost:8888}
+----
+====
+
+If your application needs any application-specific configuration from the server, it is a good idea to set the `spring.application.name` (in `bootstrap.yml` or `application.yml`).
+For the property `spring.application.name` to be used as the application's context ID, you must set it in `bootstrap.[properties | yml]`.
+
+If you want to retrieve specific profile configuration, you should also set `spring.profiles.active` in `bootstrap.[properties | yml]`.
+
+You can disable the bootstrap process completely by setting `spring.cloud.bootstrap.enabled=false` (for example, in system properties).
+
+[[application-context-hierarchies]]
+== Application Context Hierarchies
+
+If you build an application context from `SpringApplication` or `SpringApplicationBuilder`, 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 contains additional property sources, compared to building the same context without Spring Cloud Config.
+The additional property sources are:
+
+* "`bootstrap`": If any `PropertySourceLocators` are found in the bootstrap context and if they have non-empty properties, an optional `CompositePropertySource` appears with high priority.
+An example would be properties from the Spring Cloud Config Server.
+See "`<<customizing-bootstrap-property-sources>>`" for how to customize the contents of this property source.
+
+NOTE:  Prior to Spring Cloud 2022.0.3 `PropertySourceLocators` (including the ones for Spring Cloud Config) were run during
+the main application context and not in the Bootstrap context.  You can force `PropertySourceLocators` to be run during the
+Bootstrap context by setting `spring.cloud.config.initialize-on-context-refresh=true` in `bootstrap.[properties | yaml]`.
+
+* "`applicationConfig: [classpath:bootstrap.yml]`" (and related files if Spring profiles are active): If you have a `bootstrap.yml` (or `.properties`), those properties are used to configure the bootstrap context.
+Then they get added to the child context when its parent is set.
+They have lower precedence than the `application.yml` (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 "`<<customizing-bootstrap-properties>>`" for how to customize the contents of these property sources.
+
+Because of the ordering rules of property sources, the "`bootstrap`" entries take precedence.
+However, note that these do not contain any data from `bootstrap.yml`, which has very low precedence but can be used to set defaults.
+
+You can extend the context hierarchy by setting the parent context of any `ApplicationContext` you create -- for example, by using its own interface or with the `SpringApplicationBuilder` convenience methods (`parent()`, `child()` and `sibling()`).
+The bootstrap context is the parent of the most senior ancestor that you create yourself.
+Every context in the hierarchy has its own "`bootstrap`" (possibly empty) property source to avoid promoting values inadvertently from parents down to their descendants.
+If there is a config server, every context in the hierarchy can also (in principle) have a different `spring.application.name` and, hence, a different remote property source.
+Normal Spring application context behavior 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 value from the parent is not included in the child).
+
+Note that the `SpringApplicationBuilder` lets you share an `Environment` 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 may share common values with their parent.
+
+[[customizing-bootstrap-properties]]
+== Changing the Location of Bootstrap Properties
+
+The `bootstrap.yml` (or `.properties`) location can be specified by setting `spring.cloud.bootstrap.name` (default: `bootstrap`), `spring.cloud.bootstrap.location` (default: empty) or `spring.cloud.bootstrap.additional-location` (default: empty) -- for example, in System properties.
+
+Those properties behave like the `spring.config.*` variants with the same name.
+With `spring.cloud.bootstrap.location` the default locations are replaced and only the specified ones are used.
+To add locations to the list of default ones, `spring.cloud.bootstrap.additional-location` can be used.
+In fact, they are used to set up the bootstrap `ApplicationContext` by setting those properties in its `Environment`.
+If there is an active profile (from `spring.profiles.active` or through the `Environment` API in the context you are building), properties in that profile get loaded as well, the same as in a regular Spring Boot app -- for example, from `bootstrap-development.properties` for a `development` profile.
+
+[[overriding-bootstrap-properties]]
+== Overriding the Values of Remote Properties
+
+The property sources that are added to your application by the bootstrap context are often "`remote`" (from example, from Spring Cloud Config Server).
+By default, they cannot be overridden locally.
+If you want to let your applications override the remote properties with their own system properties or config files, the remote property source has to grant it permission by setting `spring.cloud.config.allowOverride=true` (it does not work to set this locally).
+Once that flag is set, two finer-grained settings control the location of the remote properties in relation to system properties and the application's local configuration:
+
+* `spring.cloud.config.overrideNone=true`: Override from any local property source.
+* `spring.cloud.config.overrideSystemProperties=false`: Only system properties, command line arguments, and environment variables (but not the local config files) should override the remote settings.
+
+[[customizing-the-bootstrap-configuration]]
+== Customizing the Bootstrap Configuration
+
+The bootstrap context can be set to do anything you like by adding entries to `/META-INF/spring.factories` under a key named `org.springframework.cloud.bootstrap.BootstrapConfiguration`.
+This holds a comma-separated list of Spring `@Configuration` classes that are used to create the context.
+Any beans that you want to be available to the main application context for autowiring can be created here.
+There is a special contract for `@Beans` of type `ApplicationContextInitializer`.
+If you want to control the startup sequence, you can mark classes with the `@Order` annotation (the default order is `last`).
+
+WARNING: When adding custom `BootstrapConfiguration`, be careful that the classes you add are not `@ComponentScanned` by mistake into your "`main`" application context, where they might not be needed.
+Use a separate package name for boot configuration classes and make sure that name is not already covered by your `@ComponentScan` or `@SpringBootApplication` annotated configuration classes.
+
+The bootstrap process ends by injecting initializers into the main `SpringApplication` instance (which is the normal Spring Boot startup sequence, whether it runs as a standalone application or is deployed in an application server).
+First, a bootstrap context is created from the classes found in `spring.factories`.
+Then, all `@Beans` of type `ApplicationContextInitializer` are added to the main `SpringApplication` before it is started.
+
+[[customizing-bootstrap-property-sources]]
+== Customizing the Bootstrap Property Sources
+
+The default property source for external configuration added by the bootstrap process is the Spring Cloud Config Server, but you can add additional sources by adding beans of type `PropertySourceLocator` to the bootstrap context (through `spring.factories`).
+For instance, you can insert additional properties from a different server or from a database.
+
+As an example, consider the following custom locator:
+
+====
+[source,java]
+----
+@Configuration
+public class CustomPropertySourceLocator implements PropertySourceLocator {
+
+    @Override
+    public PropertySource<?> locate(Environment environment) {
+        return new MapPropertySource("customProperty",
+                Collections.<String, Object>singletonMap("property.from.sample.custom.source", "worked as intended"));
+    }
+
+}
+----
+====
+
+The `Environment` that is passed in is the one for the `ApplicationContext` about to be created -- in other words, the one for which we supply additional property sources.
+It already has its normal Spring Boot-provided property sources, so you can use those to locate a property source specific to this `Environment` (for example, by keying it on `spring.application.name`, as is done in the default Spring Cloud Config Server property source locator).
+
+If you create a jar with this class in it and then add a `META-INF/spring.factories` containing the following setting, the `customProperty` `PropertySource` appears in any application that includes that jar on its classpath:
+
+====
+[source]
+----
+org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator
+----
+====
+
+As of Spring Cloud 2022.0.3, Spring Cloud will now call `PropertySourceLocators` twice.  The first fetch
+will retrieve any property sources without any profiles.  These property sources will have the opportunity to
+activate profiles using `spring.profiles.active`.  After the main application context starts `PropertySourceLocators`
+will be called a second time, this time with any active profiles allowing `PropertySourceLocators` to locate
+any additional `PropertySources` with profiles.
+
+[[logging-configuration]]
+== Logging Configuration
+
+If you use Spring Boot to configure log settings, you should place this configuration in `bootstrap.[yml | properties]` if you would like it to apply to all events.
+
+NOTE: For Spring Cloud to initialize logging configuration properly, you cannot use a custom prefix.
+For example, using `custom.loggin.logpath` is not recognized by Spring Cloud when initializing the logging system.
+
+[[environment-changes]]
+== Environment Changes
+
+The application listens for an `EnvironmentChangeEvent` and reacts to the change in a couple of standard ways (additional `ApplicationListeners` can be added as `@Beans` in the normal way).
+When an `EnvironmentChangeEvent` is observed, it has a list of key values that have changed, and the application uses those to:
+
+* Re-bind any `@ConfigurationProperties` beans in the context.
+* Set the logger levels for any properties in `logging.level.*`.
+
+Note that the Spring Cloud Config Client does not, by default, poll for changes in the `Environment`.
+Generally, we would not recommend that approach for detecting changes (although you can set it up with a
+`@Scheduled` annotation).
+If you have a scaled-out client application, it is better to broadcast the `EnvironmentChangeEvent` to all the instances instead of having them polling for changes (for example, by using the https://github.com/spring-cloud/spring-cloud-bus[Spring Cloud Bus]).
+
+The `EnvironmentChangeEvent` covers a large class of refresh use cases, as long as you can actually make a change to the `Environment` and publish the event.
+Note that those APIs are public and part of core Spring).
+You can verify that the changes are bound to `@ConfigurationProperties` beans by visiting the `/configprops` endpoint (a standard Spring Boot Actuator feature).
+For instance, a `DataSource` can have its `maxPoolSize` changed at runtime (the default `DataSource` created by Spring Boot is a `@ConfigurationProperties` bean) and grow capacity dynamically.
+Re-binding `@ConfigurationProperties` 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 `ApplicationContext`.
+To address those concerns, we have `@RefreshScope`.
+
+[[refresh-scope]]
+== Refresh Scope
+
+When there is a configuration change, a Spring `@Bean` that is marked as `@RefreshScope` gets special treatment.
+This feature addresses the problem of stateful beans that get their configuration injected only when they are initialized.
+For instance, if a `DataSource` has open connections when the database URL is changed through the `Environment`, you probably want the holders of those connections to be able to complete what they are doing.
+Then, the next time something borrows a connection from the pool, it gets one with the new URL.
+
+Sometimes, it might even be mandatory to apply the `@RefreshScope` annotation on some beans that can be only initialized once.
+If a bean is "`immutable`", you have to either annotate the bean with `@RefreshScope` or specify the classname under the property key: `spring.cloud.refresh.extra-refreshable`.
+
+WARNING: If you hava a `DataSource` bean that is a `HikariDataSource`, it can not be
+refreshed. It is the default value for `spring.cloud.refresh.never-refreshable`. Choose a
+different `DataSource` implementation if you need it to be refreshed.
+
+Refresh scope beans are lazy proxies that initialize when they are used (that is, 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 must invalidate its cache entry.
+
+The `RefreshScope` is a bean in the context and has a public `refreshAll()` method to refresh all beans in the scope by clearing the target cache.
+The `/refresh` endpoint exposes this functionality (over HTTP or JMX).
+To refresh an individual bean by name, there is also a `refresh(String)` method.
+
+To expose the `/refresh` endpoint, you need to add following configuration to your application:
+
+====
+[source,yaml]
+----
+management:
+  endpoints:
+    web:
+      exposure:
+        include: refresh
+----
+====
+
+NOTE: `@RefreshScope` works (technically) on a `@Configuration` class, but it might lead to surprising behavior.
+For example, it does not mean that all the `@Beans` defined in that class are themselves in `@RefreshScope`.
+Specifically, anything that depends on those beans cannot rely on them being updated when a refresh is initiated, unless it is itself in `@RefreshScope`.
+In that case, it is rebuilt on a refresh and its dependencies are re-injected.
+At that point, they are re-initialized from the refreshed `@Configuration`).
+
+NOTE:  Removing a configuration value and then performing a refresh will not update the presence of the configuration value.
+The configuration property must be present in order to update the value after a refresh.  If you are relying on the presence of
+a value in your application you might want to switch your logic to rely on its absence instead.  Another option would be to rely
+on the value changing rather than not being present in the application's configuration.
+
+[[encryption-and-decryption]]
+== Encryption and Decryption
+
+Spring Cloud has an `Environment` pre-processor for decrypting property values locally.
+It follows the same rules as the Spring Cloud Config Server and has the same external configuration through `encrypt.\*`.
+Thus, you can use encrypted values in the form of `{cipher}*`, and, as long as there is a valid key, they are decrypted before the main application context gets the `Environment` settings.
+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.
+
+include:../:jce.adoc[]
+
+[[endpoints]]
+== Endpoints
+
+For a Spring Boot Actuator application, some additional management endpoints are available. You can use:
+
+* `POST` to `/actuator/env` to update the `Environment` and rebind `@ConfigurationProperties` and log levels.
+  To enabled this endpoint you must set `management.endpoint.env.post.enabled=true`.
+* `/actuator/refresh` to re-load the boot strap context and refresh the `@RefreshScope` beans.
+* `/actuator/restart` to close the `ApplicationContext` and restart it (disabled by default).
+* `/actuator/pause` and `/actuator/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`).
+
+NOTE: While enabling the `POST` method for `/actuator/env` endpoint can provide flexibility and convenience in managing your application environment variables,
+it's critical to ensure that the endpoint is secured and monitored to prevent potential security risks.
+Add a `spring-boot-starter-security` dependency to configure access control for the actuator’s endpoint.
+
+NOTE: If you disable the `/actuator/restart` endpoint then the `/actuator/pause` and `/actuator/resume` endpoints
+will also be disabled since they are just a special case of `/actuator/restart`.
+

docs/modules/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc

@@ -0,0 +1,517 @@
+[[spring-cloud-loadbalancer]]
+= Spring Cloud LoadBalancer
+
+Spring Cloud provides its own client-side load-balancer abstraction and implementation. For the load-balancing
+mechanism, `ReactiveLoadBalancer` interface has been added and a *Round-Robin-based* and *Random* implementations
+have been provided for it. In order to get instances to select from reactive `ServiceInstanceListSupplier`
+is used. Currently we support a service-discovery-based implementation of `ServiceInstanceListSupplier`
+that retrieves available instances from Service Discovery using a <<discovery-client, Discovery Client>> available in the classpath.
+
+TIP: It is possible to disable Spring Cloud LoadBalancer by setting the value of `spring.cloud.loadbalancer.enabled` to `false`.
+
+[[eager-loading-of-loadbalancer-contexts]]
+== Eager loading of LoadBalancer contexts
+
+Spring Cloud LoadBalancer creates a separate Spring child context for each service id. By default, these contexts are initialised lazily, whenever the first request for a service id is being load-balanced.
+
+You can choose to load those contexts eagerly. In order to do that, specify the service ids for which you want to do eager load using the `spring.cloud-loadbalancer.eager-load.clients` property.
+
+[[switching-between-the-load-balancing-algorithms]]
+== Switching between the load-balancing algorithms
+
+The `ReactiveLoadBalancer` implementation that is used by default is `RoundRobinLoadBalancer`. To switch to a different implementation, either for selected services or all of them, you can use the <<custom-loadbalancer-configuration, custom LoadBalancer configurations mechanism>>.
+
+For example, the following configuration can be passed via `@LoadBalancerClient` annotation to switch to using the `RandomLoadBalancer`:
+
+[[random-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	ReactorLoadBalancer<ServiceInstance> randomLoadBalancer(Environment environment,
+			LoadBalancerClientFactory loadBalancerClientFactory) {
+		String name = environment.getProperty(LoadBalancerClientFactory.PROPERTY_NAME);
+		return new RandomLoadBalancer(loadBalancerClientFactory
+				.getLazyProvider(name, ServiceInstanceListSupplier.class),
+				name);
+	}
+}
+----
+
+NOTE: The classes you pass as `@LoadBalancerClient` or `@LoadBalancerClients` configuration arguments should either not be annotated with `@Configuration` or be outside component scan scope.
+
+[[spring-cloud-loadbalancer-integrations]]
+== Spring Cloud LoadBalancer integrations
+
+In order to make it easy to use Spring Cloud LoadBalancer, we provide `ReactorLoadBalancerExchangeFilterFunction` that can be used with `WebClient` and `BlockingLoadBalancerClient` that works with `RestTemplate`.
+You can see more information and examples of usage in the following sections:
+
+* <<rest-template-loadbalancer-client,Spring RestTemplate as a Load Balancer Client>>
+* <<webclinet-loadbalancer-client, Spring WebClient as a Load Balancer Client>>
+* <<webflux-with-reactive-loadbalancer,Spring WebFlux WebClient with `ReactorLoadBalancerExchangeFilterFunction`>>
+
+[[loadbalancer-caching]]
+== Spring Cloud LoadBalancer Caching
+
+Apart from the basic `ServiceInstanceListSupplier` implementation that retrieves instances via `DiscoveryClient` each time it has to choose an instance, we provide two caching implementations.
+
+[[https://github-com/ben-manes/caffeine[caffeine]-backed-loadbalancer-cache-implementation]]
+=== https://github.com/ben-manes/caffeine[Caffeine]-backed LoadBalancer Cache Implementation
+
+If you have `com.github.ben-manes.caffeine:caffeine` in the classpath, Caffeine-based implementation will be used.
+See the <<loadbalancer-cache-configuration, LoadBalancerCacheConfiguration>> section for information on how to configure it.
+
+If you are using Caffeine, you can also override the default Caffeine Cache setup for the LoadBalancer by passing your own https://static.javadoc.io/com.github.ben-manes.caffeine/caffeine/2.2.2/com/github/benmanes/caffeine/cache/CaffeineSpec.html[Caffeine Specification]
+in the `spring.cloud.loadbalancer.cache.caffeine.spec` property.
+
+WARN: Passing your own Caffeine specification will override any other LoadBalancerCache settings, including <<loadbalancer-cache-configuration, General LoadBalancer Cache Configuration>> fields, such as `ttl` and `capacity`.
+
+[[default-loadbalancer-cache-implementation]]
+=== Default LoadBalancer Cache Implementation
+
+If you do not have Caffeine in the classpath, the `DefaultLoadBalancerCache`, which comes automatically with `spring-cloud-starter-loadbalancer`, will be used.
+See the <<loadbalancer-cache-configuration, LoadBalancerCacheConfiguration>> section for information on how to configure it.
+
+TIP: To use Caffeine instead of the default cache, add the `com.github.ben-manes.caffeine:caffeine` dependency to classpath.
+
+[[loadbalancer-cache-configuration]]
+=== LoadBalancer Cache Configuration
+
+You can set your own `ttl` value (the time after write after which entries should be expired), expressed as `Duration`, by passing a `String` compliant with the https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config-conversion-duration[Spring Boot `String` to `Duration` converter syntax].
+as the value of the `spring.cloud.loadbalancer.cache.ttl` property.
+You can also set your own LoadBalancer cache initial capacity by setting the value of the `spring.cloud.loadbalancer.cache.capacity` property.
+
+The default setup includes `ttl` set to 35 seconds and the default `initialCapacity` is `256`.
+
+You can also altogether disable loadBalancer caching by setting the value of `spring.cloud.loadbalancer.cache.enabled`
+to `false`.
+
+WARNING: Although the basic, non-cached, implementation is useful for prototyping and testing, it's much less efficient than the cached versions, so we recommend always using the cached version in production. If the caching is already done by the `DiscoveryClient` implementation, for example `EurekaDiscoveryClient`, the load-balancer caching should be disabled to prevent double caching.
+
+NOTE: When you create your own configuration, if you use `CachingServiceInstanceListSupplier` make sure to place it in the hierarchy directly after the supplier that retrieves the instances over the network, for example, `DiscoveryClientServiceInstanceListSupplier`, before any other filtering suppliers.
+
+[[weighted-load-balancing]]
+== Weighted Load-Balancing
+
+To enable weighted load-balancing, we provide the `WeightedServiceInstanceListSupplier`. We use `WeightFunction` to calculate the weight of each instance.
+By default, we try to read and parse the weight from the metadata map (the key is `weight`).
+
+If the weight is not specified in the metadata map, we default the weight of this instance to be 1.
+
+You can configure it either by setting the value of `spring.cloud.loadbalancer.configurations` to `weighted` or by providing your own `ServiceInstanceListSupplier` bean, for example:
+
+[[weighted-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+					.withWeighted()
+					.withCaching()
+					.build(context);
+	}
+}
+----
+
+NOTE: You can also customize the weight calculation logic by providing `WeightFunction`.
+
+You can use this sample configuration to make all instances have a random weight:
+
+[[random-weight-weighted-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+					.withWeighted(instance -> ThreadLocalRandom.current().nextInt(1, 101))
+					.withCaching()
+					.build(context);
+	}
+}
+----
+
+[[zone-based-load-balancing]]
+== Zone-Based Load-Balancing
+
+To enable zone-based load-balancing, we provide the `ZonePreferenceServiceInstanceListSupplier`.
+We use `DiscoveryClient`-specific `zone` configuration (for example, `eureka.instance.metadata-map.zone`) to pick the zone that the client tries to filter available service instances for.
+
+NOTE: You can also override `DiscoveryClient`-specific zone setup by setting the value of `spring.cloud.loadbalancer.zone` property.
+
+WARNING: For the time being, only Eureka Discovery Client is instrumented to set the LoadBalancer zone. For other discovery client, set the `spring.cloud.loadbalancer.zone` property. More instrumentations coming shortly.
+
+NOTE: To determine the zone of a retrieved `ServiceInstance`, we check the value under the `"zone"` key in its metadata map.
+
+The `ZonePreferenceServiceInstanceListSupplier` filters retrieved instances and only returns the ones within the same zone.
+If the zone is `null` or there are no instances within the same zone, it returns all the retrieved instances.
+
+In order to use the zone-based load-balancing approach, you will have to instantiate a `ZonePreferenceServiceInstanceListSupplier` bean in a <<custom-loadbalancer-configuration,custom configuration>>.
+
+We use delegates to work with `ServiceInstanceListSupplier` beans.
+We suggest using a `DiscoveryClientServiceInstanceListSupplier` delegate, wrapping it with a `CachingServiceInstanceListSupplier` to leverage <<loadbalancer-caching, LoadBalancer caching mechanism>>, and then passing the resulting bean in the constructor of `ZonePreferenceServiceInstanceListSupplier`.
+
+You can use this sample configuration to set it up:
+
+[[zoned-based-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+                    .withCaching()
+					.withZonePreference()
+					.build(context);
+	}
+}
+----
+
+[[instance-health-check-for-loadbalancer]]
+== Instance Health-Check for LoadBalancer
+
+It is possible to enable a scheduled HealthCheck for the LoadBalancer. The `HealthCheckServiceInstanceListSupplier`
+is provided for that. It regularly verifies if the instances provided by a delegate
+`ServiceInstanceListSupplier` are still alive and only returns the healthy instances,
+unless there are none - then it returns all the retrieved instances.
+
+TIP: This mechanism is particularly helpful while using the `SimpleDiscoveryClient`. For the
+clients backed by an actual Service Registry, it's not necessary to use, as we already get
+healthy instances after querying the external ServiceDiscovery.
+
+TIP: This supplier is also recommended for setups with a small number of instances per service
+in order to avoid retrying calls on a failing instance.
+
+WARNING: If using any of the Service Discovery-backed suppliers, adding this health-check mechanism is usually not necessary, as we retrieve the health state of the instances directly
+from the Service Registry.
+
+TIP: The `HealthCheckServiceInstanceListSupplier` relies on having updated instances provided by a delegate flux. In the rare cases when you want to use a delegate that does not refresh the instances, even though the list of instances may change (such as the `DiscoveryClientServiceInstanceListSupplier` provided by us), you can set `spring.cloud.loadbalancer.health-check.refetch-instances` to `true` to have the instance list refreshed by the `HealthCheckServiceInstanceListSupplier`. You can then also adjust the refretch intervals by modifying the value of `spring.cloud.loadbalancer.health-check.refetch-instances-interval` and opt to disable the additional healthcheck repetitions by setting `spring.cloud.loadbalancer.health-check.repeat-health-check` to `false` as every instances refetch
+  will also trigger a healthcheck.
+
+`HealthCheckServiceInstanceListSupplier` uses properties prefixed with
+`spring.cloud.loadbalancer.health-check`. You can set the `initialDelay` and `interval`
+for the scheduler. You can set the default path for the healthcheck URL by setting
+the value of the `spring.cloud.loadbalancer.health-check.path.default` property. You can also set a specific value for any given service by setting the value of the `spring.cloud.loadbalancer.health-check.path.[SERVICE_ID]` property, substituting `[SERVICE_ID]` with the correct ID of your service. If the `[SERVICE_ID]` is not specified, `/actuator/health` is used by default.  If the `[SERVICE_ID]` is set to `null` or empty as a value, then the health check will not be executed. You can also set a custom port for health-check requests by setting the value of `spring.cloud.loadbalancer.health-check.port`. If none is set, the port under which the requested service is available at the service instance.
+
+TIP: If you rely on the default path (`/actuator/health`), make sure you add `spring-boot-starter-actuator` to your collaborator's dependencies, unless you are planning to add such an endpoint on your own.
+
+TIP: By default, the `healthCheckFlux` will emit on each alive `ServiceInstance` that has been retrieved. You can modify this behaviour by setting the value of `spring.cloud.loadbalancer.health-check.update-results-list` to `false`. If this property is set to `false`, the entire alive instances sequence is first collected into a list and only then emitted, which ensures the flux does not emit values in between the health-check intervals set in properties.
+
+In order to use the health-check scheduler approach, you will have to instantiate a `HealthCheckServiceInstanceListSupplier` bean in a <<custom-loadbalancer-configuration,custom configuration>>.
+
+We use delegates to work with `ServiceInstanceListSupplier` beans.
+We suggest passing a `DiscoveryClientServiceInstanceListSupplier` delegate in the constructor of `HealthCheckServiceInstanceListSupplier`.
+
+You can use this sample configuration to set it up:
+
+[[health-check-based-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+					.withHealthChecks()
+					.build(context);
+	    }
+	}
+----
+
+TIP: For the non-reactive stack, create this supplier with the `withBlockingHealthChecks()`.
+You can also pass your own `WebClient` or `RestTemplate` instance to be used for the checks.
+
+WARNING: `HealthCheckServiceInstanceListSupplier` has its own caching mechanism based on Reactor Flux `replay()`. Therefore, if it's being used, you may want to skip wrapping that supplier with `CachingServiceInstanceListSupplier`.
+
+NOTE: When you create your own configuration, `HealthCheckServiceInstanceListSupplier`, make sure to place it in the hierarchy directly after the supplier that retrieves the instances over the network, for example, `DiscoveryClientServiceInstanceListSupplier`, before any other filtering suppliers.
+
+[[same-instance-preference-for-loadbalancer]]
+== Same instance preference for LoadBalancer
+
+You can set up the LoadBalancer in such a way that it prefers the instance that was previously selected, if that instance is available.
+
+For that, you need to use `SameInstancePreferenceServiceInstanceListSupplier`. You can configure it either by setting the value of `spring.cloud.loadbalancer.configurations` to `same-instance-preference` or by providing your own `ServiceInstanceListSupplier` bean -- for example:
+
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+					.withSameInstancePreference()
+					.build(context);
+	    }
+	}
+----
+
+TIP: This is also a replacement for Zookeeper `StickyRule`.
+
+[[request-based-sticky-session-for-loadbalancer]]
+== Request-based Sticky Session for LoadBalancer
+
+You can set up the LoadBalancer in such a way that it prefers the instance with `instanceId` provided in a request cookie. We currently support this if the request is being passed to the LoadBalancer through either `ClientRequestContext` or `ServerHttpRequestContext`, which are used by the SC LoadBalancer exchange filter functions and filters.
+
+For that, you need to use the `RequestBasedStickySessionServiceInstanceListSupplier`. You can configure it either by setting the value of `spring.cloud.loadbalancer.configurations` to `request-based-sticky-session` or by providing your own `ServiceInstanceListSupplier` bean -- for example:
+
+[[health-check-based-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+					.withRequestBasedStickySession()
+					.build(context);
+	    }
+	}
+----
+
+For that functionality, it is useful to have the selected service instance (which can be different from the one in the original request cookie if that one is not available) to be updated before sending the request forward. To do that, set the value of `spring.cloud.loadbalancer.sticky-session.add-service-instance-cookie` to `true`.
+
+By default, the name of the cookie is `sc-lb-instance-id`. You can modify it by changing the value of the `spring.cloud.loadbalancer.instance-id-cookie-name` property.
+
+NOTE: This feature is currently supported for WebClient-backed load-balancing.
+
+[[spring-cloud-loadbalancer-hints]]
+== Spring Cloud LoadBalancer Hints
+
+Spring Cloud LoadBalancer lets you set `String` hints that are passed to the LoadBalancer within the `Request` object and that can later be used in `ReactiveLoadBalancer` implementations that can handle them.
+
+You can set a default hint for all services by setting the value of the `spring.cloud.loadbalancer.hint.default` property. You can also set a specific value
+for any given service by setting the value of the `spring.cloud.loadbalancer.hint.[SERVICE_ID]` property, substituting `[SERVICE_ID]` with the correct ID of your service. If the hint is not set by the user, `default` is used.
+
+[[hints-based-loadbalancing]]
+== Hint-Based Load-Balancing
+
+We also provide a `HintBasedServiceInstanceListSupplier`, which is a `ServiceInstanceListSupplier` implementation for hint-based instance selection.
+
+`HintBasedServiceInstanceListSupplier` checks for a hint request header (the default header-name is `X-SC-LB-Hint`, but you can modify it by changing the value of the `spring.cloud.loadbalancer.hint-header-name` property) and, if it finds a hint request header, uses the hint value passed in the header  to filter service instances.
+
+If no hint header has been added, `HintBasedServiceInstanceListSupplier` uses <<spring-cloud-loadbalancer-hints,hint values from properties>> to filter service instances.
+
+If no hint is set, either by the header or by properties, all service instances provided by the delegate are returned.
+
+While filtering, `HintBasedServiceInstanceListSupplier` looks for service instances that have a matching value set under the `hint` key in their `metadataMap`. If no matching instances are found, all instances provided by the delegate are returned.
+
+You can use the following sample configuration to set it up:
+
+[[hints-based-custom-loadbalancer-configuration]]
+[source,java,indent=0]
+----
+public class CustomLoadBalancerConfiguration {
+
+	@Bean
+	public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+			ConfigurableApplicationContext context) {
+		return ServiceInstanceListSupplier.builder()
+					.withDiscoveryClient()
+                    .withCaching()
+					.withHints()
+					.build(context);
+	}
+}
+----
+
+[[transform-the-load-balanced-http-request]]
+== Transform the load-balanced HTTP request
+
+You can use the selected `ServiceInstance` to transform the load-balanced HTTP Request.
+
+For `RestTemplate`, you need to implement and define `LoadBalancerRequestTransformer` as follows:
+
+[source,java,indent=0]
+----
+	@Bean
+	public LoadBalancerRequestTransformer transformer() {
+		return new LoadBalancerRequestTransformer() {
+			@Override
+			public HttpRequest transformRequest(HttpRequest request, ServiceInstance instance) {
+				return new HttpRequestWrapper(request) {
+					@Override
+					public HttpHeaders getHeaders() {
+						HttpHeaders headers = new HttpHeaders();
+						headers.putAll(super.getHeaders());
+						headers.add("X-InstanceId", instance.getInstanceId());
+						return headers;
+					}
+				};
+			}
+		};
+	}
+----
+
+For `WebClient`, you need to implement and define `LoadBalancerClientRequestTransformer` as follows:
+
+[source,java,indent=0]
+----
+	@Bean
+	public LoadBalancerClientRequestTransformer transformer() {
+		return new LoadBalancerClientRequestTransformer() {
+			@Override
+			public ClientRequest transformRequest(ClientRequest request, ServiceInstance instance) {
+				return ClientRequest.from(request)
+						.header("X-InstanceId", instance.getInstanceId())
+						.build();
+			}
+		};
+	}
+----
+
+If multiple transformers are defined, they are applied in the order in which Beans are defined.
+Alternatively, you can use `LoadBalancerRequestTransformer.DEFAULT_ORDER` or `LoadBalancerClientRequestTransformer.DEFAULT_ORDER` to specify the order.
+
+[[spring-cloud-loadbalancer-starter]]
+== Spring Cloud LoadBalancer Starter
+
+We also provide a starter that allows you to easily add Spring Cloud LoadBalancer in a Spring Boot app.
+In order to use it, just add `org.springframework.cloud:spring-cloud-starter-loadbalancer` to your Spring Cloud dependencies in your build file.
+
+NOTE: Spring Cloud LoadBalancer starter includes
+https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-caching.html[Spring Boot Caching]
+and https://github.com/stoyanr/Evictor[Evictor].
+
+[[custom-loadbalancer-configuration]]
+== Passing Your Own Spring Cloud LoadBalancer Configuration
+
+You can also use the `@LoadBalancerClient` annotation to pass your own load-balancer client configuration, passing the name of the load-balancer client and the configuration class, as follows:
+
+[source,java,indent=0]
+----
+@Configuration
+@LoadBalancerClient(value = "stores", configuration = CustomLoadBalancerConfiguration.class)
+public class MyConfiguration {
+
+	@Bean
+	@LoadBalanced
+	public WebClient.Builder loadBalancedWebClientBuilder() {
+		return WebClient.builder();
+	}
+}
+----
+
+TIP: In order to make working on your own LoadBalancer configuration easier, we have added a `builder()` method to the `ServiceInstanceListSupplier` class.
+
+TIP: You can also use our alternative predefined configurations in place of the default ones by setting the value of `spring.cloud.loadbalancer.configurations` property to `zone-preference` to use `ZonePreferenceServiceInstanceListSupplier` with caching or to `health-check` to use `HealthCheckServiceInstanceListSupplier` with caching.
+
+
+You can use this feature to instantiate different implementations of `ServiceInstanceListSupplier` or `ReactorLoadBalancer`, either written by you, or provided by us as alternatives (for example `ZonePreferenceServiceInstanceListSupplier`) to override the default setup.
+
+You can see an example of a custom configuration <<zoned-based-custom-loadbalancer-configuration,here>>.
+
+NOTE: The annotation `value` arguments (`stores` in the example above) specifies the service id of the service that we should send the requests to with the given custom configuration.
+
+You can also pass multiple configurations (for more than one load-balancer client) through the `@LoadBalancerClients` annotation, as the following example shows:
+
+[source,java,indent=0]
+----
+@Configuration
+@LoadBalancerClients({@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class), @LoadBalancerClient(value = "customers", configuration = CustomersLoadBalancerClientConfiguration.class)})
+public class MyConfiguration {
+
+	@Bean
+	@LoadBalanced
+	public WebClient.Builder loadBalancedWebClientBuilder() {
+		return WebClient.builder();
+	}
+}
+----
+
+NOTE: The classes you pass as `@LoadBalancerClient` or `@LoadBalancerClients` configuration arguments should either not be annotated with `@Configuration` or be outside component scan scope.
+
+NOTE: When you create your own configuration, if you use `CachingServiceInstanceListSupplier` or `HealthCheckServiceInstanceListSupplier`, makes sure to use one of them, not both, and make sure to place it in the hierarchy directly after the supplier that retrieves the instances over the network, for example, `DiscoveryClientServiceInstanceListSupplier`, before any other filtering suppliers.
+
+
+[[loadbalancer-lifecycle]]
+== Spring Cloud LoadBalancer Lifecycle
+
+One type of bean that it may be useful to register using <<custom-loadbalancer-configuration,Custom LoadBalancer configuration>> is `LoadBalancerLifecycle`.
+
+The `LoadBalancerLifecycle` beans provide callback methods, named `onStart(Request<RC> request)`, `onStartRequest(Request<RC> request, Response<T> lbResponse)` and `onComplete(CompletionContext<RES, T, RC> completionContext)`, that you should implement to specify what actions should take place before and after load-balancing.
+
+`onStart(Request<RC> request)` takes a `Request` object as a parameter. It contains data that is used to select an appropriate instance, including the downstream client request and <<spring-cloud-loadbalancer-hints,hint>>. `onStartRequest` also takes the `Request` object and, additionally, the `Response<T>` object as parameters.  On the other hand, a `CompletionContext` object is provided to the `onComplete(CompletionContext<RES, T, RC> completionContext)` method. It contains the LoadBalancer `Response`, including the selected service instance, the `Status` of the request executed against that service instance and (if available) the response returned to the downstream client, and (if an exception has occurred) the corresponding `Throwable`.
+
+The `supports(Class requestContextClass, Class responseClass,
+Class serverTypeClass)` method can be used to determine whether the processor in question handles objects of provided types. If not overridden by the user, it returns `true`.
+
+NOTE: In the preceding method calls, `RC` means `RequestContext` type, `RES` means client response type, and `T` means returned server type.
+
+[[loadbalancer-micrometer-stats-lifecycle]]
+== Spring Cloud LoadBalancer Statistics
+
+We provide a `LoadBalancerLifecycle` bean called `MicrometerStatsLoadBalancerLifecycle`, which uses Micrometer to provide statistics for load-balanced calls.
+
+In order to get this bean added to your application context,
+set the value of the `spring.cloud.loadbalancer.stats.micrometer.enabled` to `true` and have a `MeterRegistry` available (for example, by adding https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html[Spring Boot Actuator] to your project).
+
+`MicrometerStatsLoadBalancerLifecycle` registers the following meters in `MeterRegistry`:
+
+* `loadbalancer.requests.active`: A gauge that allows you to monitor the number of currently active requests for any service instance (service instance data available via tags);
+* `loadbalancer.requests.success`: A timer that measures the time of execution of any load-balanced requests that have ended in passing a response on to the underlying client;
+* `loadbalancer.requests.failed`: A timer that measures the time of execution of any load-balanced requests that have ended with an exception;
+* `loadbalancer.requests.discard`: A counter that measures the number of discarded load-balanced requests, i.e. requests where a service instance to run the request on has not been retrieved by the LoadBalancer.
+
+Additional information regarding the service instances, request data, and response data is added to metrics via tags whenever available.
+
+NOTE: For some implementations, such as `BlockingLoadBalancerClient`, request and response data might not be available, as we establish generic types from arguments and might not be able to determine the types and read the data.
+
+NOTE: The meters are registered in the registry when at least one record is added for a given meter.
+
+TIP: You can further configure the behavior of those metrics (for example, add https://micrometer.io/docs/concepts#_histograms_and_percentiles[publishing percentiles and histograms]) by https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-per-meter-properties[adding `MeterFilters`].
+
+[[configuring-individual-loadbalancerclients]]
+== Configuring Individual LoadBalancerClients
+
+Individual Loadbalancer clients may be configured individually with a different prefix `spring.cloud.loadbalancer.clients.<clientId>.*` where `clientId` is the name of the loadbalancer. Default configuration values may be set in the `spring.cloud.loadbalancer.*` namespace and will be merged with the client specific values taking precedence
+
+.application.yml
+====
+----
+spring:
+  cloud:
+    loadbalancer:
+      health-check:
+        initial-delay: 1s
+      clients:
+        myclient:
+          health-check:
+            interval: 30s
+----
+====
+
+The above example will result in a merged health-check `@ConfigurationProperties` object with `initial-delay=1s` and `interval=30s`.
+
+The per-client configuration properties work for most of the properties, apart from the following global ones:
+
+- `spring.cloud.loadbalancer.enabled` - globally enables or disables load-balancing
+- `spring.cloud.loadbalancer.retry.enabled` - globally enables or disables load-balanced retries. If you enable it globally, you can still disable retries for specific clients using the `client`-prefixed properties, but not the other way round
+- `spring.cloud.loadbalancer.cache.enabled` - globally enables or disables LoadBalancer caching. If you enable it globally, you can still disable caching for specific clients by creating a <<custom-loadbalancer-configuration, custom configuration>> that does not include the `CachingServiceInstanceListSupplier` in the `ServiceInstanceListSupplier` delegates hierarchy, but not the other way round.
+- `spring.cloud.loadbalancer.stats.micrometer.enabled` - globally enables or disables LoadBalancer Micrometer metrics
+
+NOTE: For the properties where maps where already used, where you can specify a different value per-client without using the `clients` keyword (for example, `hints`, `health-check.path`), we have kept that behaviour in order to keep the library backwards compatible. It will be modified in the next major release.
+
+NOTE: Starting with `4.1.0`, we have introduced the `callGetWithRequestOnDelegates` flag in `LoadBalancerProperties`. If this flag is set to `true`, `ServiceInstanceListSupplier#get(Request request)` method will be implemented to call `delegate.get(request)` in classes assignable from `DelegatingServiceInstanceListSupplier` that don't already implement that method, with the exclusion of `CachingServiceInstanceListSupplier` and `HealthCheckServiceInstanceListSupplier`, which should be placed in the instance supplier hierarchy directly after the supplier performing instance retrieval over the network, before any request-based filtering is done. It is set to `true` by default.
+
+[[-aot-and-native-image-support]]
+==  AOT and Native Image Support
+
+Since `4.0.0`, Spring Cloud LoadBalancer supports Spring AOT transformations and native images. However, to use this feature, you need to explicitly define your `LoadBalancerClient` service IDs. You can do so by using the `value` or `name` attributes of the `@LoadBalancerClient` annotation or as values of the `spring.cloud.loadbalancer.eager-load.clients` property.
+

docs/modules/modules/ROOT/pages/spring-cloud-commons/security.adoc

@@ -0,0 +1,89 @@
+[[spring-cloud-security]]
+= Security
+
+[[spring-cloud-security-single-sign-on]]
+== Single Sign On
+
+NOTE: All of the OAuth2 SSO and resource server features moved to Spring Boot
+in version 1.3. You can find documentation in the
+https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/[Spring Boot user guide].
+
+[[spring-cloud-security-client-token-relay]]
+=== Client Token Relay
+
+If your app is a user facing OAuth2 client (i.e. has declared
+`@EnableOAuth2Sso` or `@EnableOAuth2Client`) then it has an
+`OAuth2ClientContext` in request scope from Spring Boot. You can
+create your own `OAuth2RestTemplate` from this context and an
+autowired `OAuth2ProtectedResourceDetails`, and then the context will
+always forward the access token downstream, also refreshing the access
+token automatically if it expires. (These are features of Spring
+Security and Spring Boot.)
+
+[[spring-cloud-security-resource-server-token-relay]]
+=== Resource Server Token Relay
+
+If your app has `@EnableResourceServer` you might want to relay the
+incoming token downstream to other services. If you use a
+`RestTemplate` to contact the downstream services then this is just a
+matter of how to create the template with the right context.
+
+If your service uses `UserInfoTokenServices` to authenticate incoming
+tokens (i.e. it is using the `security.oauth2.user-info-uri`
+configuration), then you can simply create an `OAuth2RestTemplate`
+using an autowired `OAuth2ClientContext` (it will be populated by the
+authentication process before it hits the backend code). Equivalently
+(with Spring Boot 1.4), you can inject a
+`UserInfoRestTemplateFactory` and grab its `OAuth2RestTemplate` in
+your configuration. For example:
+
+.MyConfiguration.java
+[source,java]
+----
+@Bean
+public OAuth2RestTemplate restTemplate(UserInfoRestTemplateFactory factory) {
+    return factory.getUserInfoRestTemplate();
+}
+----
+
+This rest template will then have the same `OAuth2ClientContext`
+(request-scoped) that is used by the authentication filter, so you can
+use it to send requests with the same access token.
+
+If your app is not using `UserInfoTokenServices` but is still a client
+(i.e. it declares `@EnableOAuth2Client` or `@EnableOAuth2Sso`), then
+with Spring Security Cloud any `OAuth2RestOperations` that the user
+creates from an `@Autowired` `OAuth2Context` will also forward
+tokens. This feature is implemented by default as an MVC handler
+interceptor, so it only works in Spring MVC. If you are not using MVC
+you can use a custom filter or AOP interceptor wrapping an
+`AccessTokenContextRelay` to provide the same feature.
+
+Here's a basic
+example showing the use of an autowired rest template created
+elsewhere ("foo.com" is a Resource Server accepting the same tokens as
+the surrounding app):
+
+.MyController.java
+[source,java]
+----
+@Autowired
+private OAuth2RestOperations restTemplate;
+
+@RequestMapping("/relay")
+public String relay() {
+    ResponseEntity<String> response =
+      restTemplate.getForEntity("https://foo.com/bar", String.class);
+    return "Success! (" + response.getBody() + ")";
+}
+----
+
+If you don't want to forward tokens (and that is a valid
+choice, since you might want to act as yourself, rather than the
+client that sent you the token), then you only need to create your own
+`OAuth2Context` instead of autowiring the default one.
+
+Feign clients will also pick up an interceptor that uses the
+`OAuth2ClientContext` if it is available, so they should also do a
+token relay anywhere where a `RestTemplate` would.
+