From 90a2d8f49fdefd4e78d17014916aa988e4d9e972 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Thu, 7 Sep 2023 12:07:40 +0200 Subject: [PATCH] Fix cross references --- .../commons:-common-abstractions.adoc | 12 +++---- ...context:-application-context-services.adoc | 4 +-- .../spring-cloud-commons/loadbalancer.adoc | 32 +++++++++---------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/modules/modules/ROOT/pages/spring-cloud-commons/commons:-common-abstractions.adoc b/docs/modules/modules/ROOT/pages/spring-cloud-commons/commons:-common-abstractions.adoc index 9679e71c..fffec0c3 100644 --- a/docs/modules/modules/ROOT/pages/spring-cloud-commons/commons:-common-abstractions.adoc +++ b/docs/modules/modules/ROOT/pages/spring-cloud-commons/commons:-common-abstractions.adoc @@ -174,7 +174,7 @@ The URI needs to use a virtual host name (that is, a service name, not a host na 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 <> to your project in order to use it. +Add xref:spring-cloud-commons/loadbalancer.adoc#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 @@ -212,7 +212,7 @@ 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 -<> to your project. +xref:spring-cloud-commons/loadbalancer.adoc#spring-cloud-loadbalancer-starter[Spring Cloud LoadBalancer starter] to your project. Then, `ReactiveLoadBalancer` is used underneath. [[retrying-failed-requests]] @@ -404,14 +404,14 @@ public class MyClass { The Spring WebFlux can work with both reactive and non-reactive `WebClient` configurations, as the topics describe: -* <> -* <> +* xref:spring-cloud-commons/commons:-common-abstractions.adoc#webflux-with-reactive-loadbalancer[Spring WebFlux `WebClient` with `ReactorLoadBalancerExchangeFilterFunction`] +* xref:spring-cloud-commons/commons:-common-abstractions.adoc#load-balancer-exchange-filter-function[Spring WebFlux `WebClient` with a Non-reactive Load Balancer Client] [[webflux-with-reactive-loadbalancer]] === Spring WebFlux `WebClient` with `ReactorLoadBalancerExchangeFilterFunction` You can configure `WebClient` to use the `ReactiveLoadBalancer`. -If you add <> to your project +If you add xref:spring-cloud-commons/loadbalancer.adoc#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: @@ -470,7 +470,7 @@ The URI needs to use a virtual host name (that is, a service name, not a host na The `LoadBalancerClient` is used to create a full physical address. WARN: This approach is now deprecated. -We suggest that you use <> +We suggest that you use xref:spring-cloud-commons/commons:-common-abstractions.adoc#webflux-with-reactive-loadbalancer[WebFlux with reactive Load-Balancer] instead. [[ignore-network-interfaces]] diff --git a/docs/modules/modules/ROOT/pages/spring-cloud-commons/context:-application-context-services.adoc b/docs/modules/modules/ROOT/pages/spring-cloud-commons/context:-application-context-services.adoc index 952ecb8d..7f2e858f 100644 --- a/docs/modules/modules/ROOT/pages/spring-cloud-commons/context:-application-context-services.adoc +++ b/docs/modules/modules/ROOT/pages/spring-cloud-commons/context:-application-context-services.adoc @@ -45,7 +45,7 @@ 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 "`<>`" for how to customize the contents of this property source. +See "`xref:spring-cloud-commons/context:-application-context-services.adoc#customizing-bootstrap-property-sources[Customizing the 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 @@ -54,7 +54,7 @@ Bootstrap context by setting `spring.cloud.config.initialize-on-context-refresh= * "`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 "`<>`" for how to customize the contents of these property sources. +See "`xref:spring-cloud-commons/context:-application-context-services.adoc#customizing-bootstrap-properties[Changing the Location of 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. diff --git a/docs/modules/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc b/docs/modules/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc index f4994f98..97ad8e0f 100644 --- a/docs/modules/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc +++ b/docs/modules/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc @@ -5,7 +5,7 @@ Spring Cloud provides its own client-side load-balancer abstraction and implemen 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 <> available in the classpath. +that retrieves available instances from Service Discovery using a xref:spring-cloud-commons/commons:-common-abstractions.adoc#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`. @@ -19,7 +19,7 @@ You can choose to load those contexts eagerly. In order to do that, specify the [[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 <>. +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 xref:spring-cloud-commons/loadbalancer.adoc#custom-loadbalancer-configuration[custom LoadBalancer configurations mechanism]. For example, the following configuration can be passed via `@LoadBalancerClient` annotation to switch to using the `RandomLoadBalancer`: @@ -47,9 +47,9 @@ NOTE: The classes you pass as `@LoadBalancerClient` or `@LoadBalancerClients` co 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: -* <> -* <> -* <> +* xref:spring-cloud-commons/commons:-common-abstractions.adoc#rest-template-loadbalancer-client[Spring RestTemplate as a Load Balancer Client] +* xref:spring-cloud-commons/commons:-common-abstractions.adoc#webclinet-loadbalancer-client[Spring WebClient as a Load Balancer Client] +* xref:spring-cloud-commons/commons:-common-abstractions.adoc#webflux-with-reactive-loadbalancer[Spring WebFlux WebClient with `ReactorLoadBalancerExchangeFilterFunction`] [[loadbalancer-caching]] == Spring Cloud LoadBalancer Caching @@ -60,18 +60,18 @@ Apart from the basic `ServiceInstanceListSupplier` implementation that retrieves === 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 <> section for information on how to configure it. +See the xref:spring-cloud-commons/loadbalancer.adoc#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 <> fields, such as `ttl` and `capacity`. +WARN: Passing your own Caffeine specification will override any other LoadBalancerCache settings, including xref:spring-cloud-commons/loadbalancer.adoc#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 <> section for information on how to configure it. +See the xref:spring-cloud-commons/loadbalancer.adoc#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. @@ -154,10 +154,10 @@ NOTE: To determine the zone of a retrieved `ServiceInstance`, we check the value 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 <>. +In order to use the zone-based load-balancing approach, you will have to instantiate a `ZonePreferenceServiceInstanceListSupplier` bean in a xref:spring-cloud-commons/loadbalancer.adoc#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 <>, and then passing the resulting bean in the constructor of `ZonePreferenceServiceInstanceListSupplier`. +We suggest using a `DiscoveryClientServiceInstanceListSupplier` delegate, wrapping it with a `CachingServiceInstanceListSupplier` to leverage xref:spring-cloud-commons/loadbalancer.adoc#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: @@ -208,7 +208,7 @@ TIP: If you rely on the default path (`/actuator/health`), make sure you add `sp 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 <>. +In order to use the health-check scheduler approach, you will have to instantiate a `HealthCheckServiceInstanceListSupplier` bean in a xref:spring-cloud-commons/loadbalancer.adoc#custom-loadbalancer-configuration[custom configuration]. We use delegates to work with `ServiceInstanceListSupplier` beans. We suggest passing a `DiscoveryClientServiceInstanceListSupplier` delegate in the constructor of `HealthCheckServiceInstanceListSupplier`. @@ -306,7 +306,7 @@ We also provide a `HintBasedServiceInstanceListSupplier`, which is a `ServiceIns `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 <> to filter service instances. +If no hint header has been added, `HintBasedServiceInstanceListSupplier` uses xref:spring-cloud-commons/loadbalancer.adoc#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. @@ -415,7 +415,7 @@ TIP: You can also use our alternative predefined configurations in place of the 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 <>. +You can see an example of a custom configuration xref:spring-cloud-commons/loadbalancer.adoc#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. @@ -443,11 +443,11 @@ NOTE: When you create your own configuration, if you use `CachingServiceInstance [[loadbalancer-lifecycle]] == Spring Cloud LoadBalancer Lifecycle -One type of bean that it may be useful to register using <> is `LoadBalancerLifecycle`. +One type of bean that it may be useful to register using xref:spring-cloud-commons/loadbalancer.adoc#custom-loadbalancer-configuration[Custom LoadBalancer configuration] is `LoadBalancerLifecycle`. The `LoadBalancerLifecycle` beans provide callback methods, named `onStart(Request request)`, `onStartRequest(Request request, Response lbResponse)` and `onComplete(CompletionContext completionContext)`, that you should implement to specify what actions should take place before and after load-balancing. -`onStart(Request 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 <>. `onStartRequest` also takes the `Request` object and, additionally, the `Response` object as parameters. On the other hand, a `CompletionContext` object is provided to the `onComplete(CompletionContext 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`. +`onStart(Request 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 xref:spring-cloud-commons/loadbalancer.adoc#spring-cloud-loadbalancer-hints[hint]. `onStartRequest` also takes the `Request` object and, additionally, the `Response` object as parameters. On the other hand, a `CompletionContext` object is provided to the `onComplete(CompletionContext 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`. @@ -503,7 +503,7 @@ The per-client configuration properties work for most of the properties, apart f - `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 <> that does not include the `CachingServiceInstanceListSupplier` in the `ServiceInstanceListSupplier` delegates hierarchy, 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 xref:spring-cloud-commons/loadbalancer.adoc#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.