Migrate Structure

docs/modules/modules/ROOT/pages/README.adoc

@@ -0,0 +1,9 @@
+include::intro.adoc[]
+
+== Building
+
+include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/building.adoc[]
+
+== Contributing
+
+include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/contributing.adoc[]

docs/modules/modules/ROOT/pages/_attributes.adoc

@@ -0,0 +1,16 @@
+:doctype: book
+:idprefix:
+:idseparator: -
+:toc: left
+:toclevels: 4
+:tabsize: 4
+:numbered:
+:sectanchors:
+:sectnums:
+:icons: font
+:hide-uri-scheme:
+:docinfo: shared,private
+
+:sc-ext: java
+:project-full-name: Spring Cloud Commons
+:all: {asterisk}{asterisk}

docs/modules/modules/ROOT/pages/_configprops.adoc

@@ -0,0 +1,83 @@
+|===
+|Name | Default | Description
+
+|spring.cloud.compatibility-verifier.compatible-boot-versions | `+++3.2.x+++` | Default accepted versions for the Spring Boot dependency. You can set {@code x} for the patch version if you don't want to specify a concrete value. Example: {@code 3.4.x}
+|spring.cloud.compatibility-verifier.enabled | `+++false+++` | Enables creation of Spring Cloud compatibility verification.
+|spring.cloud.config.allow-override | `+++true+++` | Flag to indicate that {@link #isOverrideSystemProperties() systemPropertiesOverride} can be used. Set to false to prevent users from changing the default accidentally. Default true.
+|spring.cloud.config.initialize-on-context-refresh | `+++false+++` | Flag to initialize bootstrap configuration on context refresh event. Default false.
+|spring.cloud.config.override-none | `+++false+++` | Flag to indicate that when {@link #setAllowOverride(boolean) allowOverride} is true, external properties should take lowest priority and should not override any existing property sources (including local config files). Default false.
+|spring.cloud.config.override-system-properties | `+++true+++` | Flag to indicate that the external properties should override system properties. Default true.
+|spring.cloud.decrypt-environment-post-processor.enabled | `+++true+++` | Enable the DecryptEnvironmentPostProcessor.
+|spring.cloud.discovery.client.composite-indicator.enabled | `+++true+++` | Enables discovery client composite health indicator.
+|spring.cloud.discovery.client.health-indicator.enabled | `+++true+++` | 
+|spring.cloud.discovery.client.health-indicator.include-description | `+++false+++` | 
+|spring.cloud.discovery.client.health-indicator.use-services-query | `+++true+++` | Whether or not the indicator should use {@link DiscoveryClient#getServices} to check its health. When set to {@code false} the indicator instead uses the lighter {@link DiscoveryClient#probe()}. This can be helpful in large deployments where the number of services returned makes the operation unnecessarily heavy.
+|spring.cloud.discovery.client.simple.instances |  | 
+|spring.cloud.discovery.client.simple.local.host |  | 
+|spring.cloud.discovery.client.simple.local.instance-id |  | 
+|spring.cloud.discovery.client.simple.local.metadata |  | 
+|spring.cloud.discovery.client.simple.local.port | `+++0+++` | 
+|spring.cloud.discovery.client.simple.local.secure | `+++false+++` | 
+|spring.cloud.discovery.client.simple.local.service-id |  | 
+|spring.cloud.discovery.client.simple.local.uri |  | 
+|spring.cloud.discovery.client.simple.order |  | 
+|spring.cloud.discovery.enabled | `+++true+++` | Enables discovery client health indicators.
+|spring.cloud.features.enabled | `+++true+++` | Enables the features endpoint.
+|spring.cloud.httpclientfactories.apache.enabled | `+++true+++` | Enables creation of Apache Http Client factory beans.
+|spring.cloud.httpclientfactories.ok.enabled | `+++true+++` | Enables creation of OK Http Client factory beans.
+|spring.cloud.hypermedia.refresh.fixed-delay | `+++5000+++` | 
+|spring.cloud.hypermedia.refresh.initial-delay | `+++10000+++` | 
+|spring.cloud.inetutils.default-hostname | `+++localhost+++` | The default hostname. Used in case of errors.
+|spring.cloud.inetutils.default-ip-address | `+++127.0.0.1+++` | The default IP address. Used in case of errors.
+|spring.cloud.inetutils.ignored-interfaces |  | List of Java regular expressions for network interfaces that will be ignored.
+|spring.cloud.inetutils.preferred-networks |  | List of Java regular expressions for network addresses that will be preferred.
+|spring.cloud.inetutils.timeout-seconds | `+++1+++` | Timeout, in seconds, for calculating hostname.
+|spring.cloud.inetutils.use-only-site-local-interfaces | `+++false+++` | Whether to use only interfaces with site local addresses. See {@link InetAddress#isSiteLocalAddress()} for more details.
+|spring.cloud.loadbalancer.cache.caffeine.spec |  | The spec to use to create caches. See CaffeineSpec for more details on the spec format.
+|spring.cloud.loadbalancer.cache.capacity | `+++256+++` | Initial cache capacity expressed as int.
+|spring.cloud.loadbalancer.cache.enabled | `+++true+++` | Enables Spring Cloud LoadBalancer caching mechanism.
+|spring.cloud.loadbalancer.cache.ttl | `+++35s+++` | Time To Live - time counted from writing of the record, after which cache entries are expired, expressed as a {@link Duration}. The property {@link String} has to be in keeping with the appropriate syntax as specified in Spring Boot <code>StringToDurationConverter</code>. @see <a href= "https://github.com/spring-projects/spring-boot/blob/master/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/convert/StringToDurationConverter.java">StringToDurationConverter.java</a>
+|spring.cloud.loadbalancer.call-get-with-request-on-delegates | `+++true+++` | If this flag is set to {@code true}, {@code ServiceInstanceListSupplier#get(Request request)} method will be implemented to call {@code delegate.get(request)} in classes assignable from {@code DelegatingServiceInstanceListSupplier} that don't already implement that method, with the exclusion of {@code CachingServiceInstanceListSupplier} and {@code 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, {@code true} by default.
+|spring.cloud.loadbalancer.clients |  | 
+|spring.cloud.loadbalancer.configurations | `+++default+++` | Enables a predefined LoadBalancer configuration.
+|spring.cloud.loadbalancer.eager-load.clients |  | Names of the clients.
+|spring.cloud.loadbalancer.enabled | `+++true+++` | Enables Spring Cloud LoadBalancer.
+|spring.cloud.loadbalancer.health-check.initial-delay | `+++0+++` | Initial delay value for the HealthCheck scheduler.
+|spring.cloud.loadbalancer.health-check.interval | `+++25s+++` | Interval for rerunning the HealthCheck scheduler.
+|spring.cloud.loadbalancer.health-check.interval  | `+++25s+++` | Interval for rerunning the HealthCheck scheduler.
+|spring.cloud.loadbalancer.health-check.path |  | Path at which the health-check request should be made. Can be set up per `serviceId`. A `default` value can be set up as well. If none is set up, `/actuator/health` will be used.
+|spring.cloud.loadbalancer.health-check.port |  | Path at which the health-check request should be made. If none is set, the port under which the requested service is available at the service instance.
+|spring.cloud.loadbalancer.health-check.refetch-instances | `+++false+++` | Indicates whether the instances should be refetched by the `HealthCheckServiceInstanceListSupplier`. This can be used if the instances can be updated and the underlying delegate does not provide an ongoing flux.
+|spring.cloud.loadbalancer.health-check.refetch-instances-interval | `+++25s+++` | Interval for refetching available service instances.
+|spring.cloud.loadbalancer.health-check.repeat-health-check | `+++true+++` | Indicates whether health checks should keep repeating. It might be useful to set it to `false` if periodically refetching the instances, as every refetch will also trigger a healthcheck.
+|spring.cloud.loadbalancer.health-check.update-results-list | `+++true+++` | Indicates whether the {@code healthCheckFlux} should emit on each alive {@link ServiceInstance} that has been retrieved. If set to {@code false}, the entire alive instances sequence is first collected into a list and only then emitted.
+|spring.cloud.loadbalancer.hint |  | Allows setting the value of <code>hint</code> that is passed on to the LoadBalancer request and can subsequently be used in {@link ReactiveLoadBalancer} implementations.
+|spring.cloud.loadbalancer.hint-header-name | `+++X-SC-LB-Hint+++` | Allows setting the name of the header used for passing the hint for hint-based service instance filtering.
+|spring.cloud.loadbalancer.retry.avoid-previous-instance | `+++true+++` | Enables wrapping ServiceInstanceListSupplier beans with `RetryAwareServiceInstanceListSupplier` if Spring-Retry is in the classpath.
+|spring.cloud.loadbalancer.retry.backoff.enabled | `+++false+++` | Indicates whether Reactor Retry backoffs should be applied.
+|spring.cloud.loadbalancer.retry.backoff.jitter | `+++0.5+++` | Used to set `RetryBackoffSpec.jitter`.
+|spring.cloud.loadbalancer.retry.backoff.max-backoff | `+++Long.MAX ms+++` | Used to set `RetryBackoffSpec.maxBackoff`.
+|spring.cloud.loadbalancer.retry.backoff.min-backoff | `+++5 ms+++` | Used to set `RetryBackoffSpec#minBackoff`.
+|spring.cloud.loadbalancer.retry.enabled | `+++true+++` | Enables LoadBalancer retries.
+|spring.cloud.loadbalancer.retry.max-retries-on-next-service-instance | `+++1+++` | Number of retries to be executed on the next `ServiceInstance`. A `ServiceInstance` is chosen before each retry call.
+|spring.cloud.loadbalancer.retry.max-retries-on-same-service-instance | `+++0+++` | Number of retries to be executed on the same `ServiceInstance`.
+|spring.cloud.loadbalancer.retry.retry-on-all-exceptions | `+++false+++` | Indicates retries should be attempted for all exceptions, not only those specified in `retryableExceptions`.
+|spring.cloud.loadbalancer.retry.retry-on-all-operations | `+++false+++` | Indicates retries should be attempted on operations other than `HttpMethod.GET`.
+|spring.cloud.loadbalancer.retry.retryable-exceptions | `+++{}+++` | A `Set` of `Throwable` classes that should trigger a retry.
+|spring.cloud.loadbalancer.retry.retryable-status-codes | `+++{}+++` | A `Set` of status codes that should trigger a retry.
+|spring.cloud.loadbalancer.service-discovery.timeout |  | String representation of Duration of the timeout for calls to service discovery.
+|spring.cloud.loadbalancer.stats.micrometer.enabled | `+++false+++` | Enables Spring Cloud LoadBalancer Micrometer stats.
+|spring.cloud.loadbalancer.sticky-session.add-service-instance-cookie | `+++false+++` | Indicates whether a cookie with the newly selected instance should be added by LoadBalancer.
+|spring.cloud.loadbalancer.sticky-session.instance-id-cookie-name | `+++sc-lb-instance-id+++` | The name of the cookie holding the preferred instance id.
+|spring.cloud.loadbalancer.x-forwarded.enabled | `+++false+++` | To Enable X-Forwarded Headers.
+|spring.cloud.loadbalancer.zone |  | Spring Cloud LoadBalancer zone.
+|spring.cloud.refresh.additional-property-sources-to-retain |  | Additional property sources to retain during a refresh. Typically only system property sources are retained. This property allows property sources, such as property sources created by EnvironmentPostProcessors to be retained as well.
+|spring.cloud.refresh.enabled | `+++true+++` | Enables autoconfiguration for the refresh scope and associated features.
+|spring.cloud.refresh.extra-refreshable | `+++true+++` | Additional class names for beans to post process into refresh scope.
+|spring.cloud.refresh.never-refreshable | `+++true+++` | Comma separated list of class names for beans to never be refreshed or rebound.
+|spring.cloud.service-registry.auto-registration.enabled | `+++true+++` | Whether service auto-registration is enabled. Defaults to true.
+|spring.cloud.service-registry.auto-registration.fail-fast | `+++false+++` | Whether startup fails if there is no AutoServiceRegistration. Defaults to false.
+|spring.cloud.service-registry.auto-registration.register-management | `+++true+++` | Whether to register the management as a service. Defaults to true.
+|spring.cloud.util.enabled | `+++true+++` | Enables creation of Spring Cloud utility beans.
+
+|===

docs/modules/modules/ROOT/pages/_observability.adoc

@@ -0,0 +1,8 @@
+:root-target: ../../../target/
+
+[[observability]]
+== Observability metadata
+
+include::{root-target}_metrics.adoc[]
+
+include::{root-target}_spans.adoc[]

docs/modules/modules/ROOT/pages/appendix.adoc

@@ -0,0 +1,16 @@
+:numbered!:
+[appendix]
+[[common-application-properties]]
+== Common application properties
+
+include::_attributes.adoc[]
+
+Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
+This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them.
+
+NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
+Also, you can define your own properties.
+
+include::_configprops.adoc[]
+
+include::_observability.adoc[]

docs/modules/modules/ROOT/pages/index.adoc

@@ -0,0 +1 @@
+include::spring-cloud-commons.adoc[]

docs/modules/modules/ROOT/pages/intro.adoc

@@ -0,0 +1,10 @@
+
+https://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook[Cloud Native] is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development.
+A related discipline is that of building https://12factor.net/[12-factor Applications], in which development practices are aligned with delivery and operations goals -- for instance, by using declarative programming and management and monitoring.
+Spring Cloud facilitates these styles of development in a number of specific ways.
+ The starting point is a set of features to which all components in a distributed system need easy access.
+
+Many of those features are covered by https://projects.spring.io/spring-boot[Spring Boot], on which Spring Cloud builds. Some more features are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons.
+Spring Cloud Context provides utilities and special services for the `ApplicationContext` of a Spring Cloud application (bootstrap context, encryption, refresh scope, and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (such as Spring Cloud Netflix and Spring Cloud Consul).
+
+include::jce.adoc[]

docs/modules/modules/ROOT/pages/jce.adoc

@@ -0,0 +1,8 @@
+If you get an exception due to "Illegal key size" and you use Sun's JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.
+See the following links for more information:
+
+* https://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html[Java 6 JCE]
+* https://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html[Java 7 JCE]
+* https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Java 8 JCE]
+
+Extract the files into the JDK/jre/lib/security folder for whichever version of JRE/JDK x64/x86 you use.

docs/modules/modules/ROOT/pages/sagan-index.adoc

@@ -0,0 +1,16 @@
+Spring Cloud Commons delivers features as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the ApplicationContext of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).
+
+## Features
+
+### Spring Cloud Context features:
+
+* Bootstrap Context
+* `TextEncryptor` beans
+* Refresh Scope
+* Spring Boot Actuator endpoints for manipulating the `Environment`
+
+### Spring Cloud Commons features:
+
+* `DiscoveryClient` interface
+* `ServiceRegistry` interface
+* Instrumentation for `RestTemplate` to resolve hostnames using `DiscoveryClient`

docs/modules/modules/ROOT/pages/spring-cloud-circuitbreaker.adoc

@@ -0,0 +1,105 @@
+== Introduction
+
+Spring Cloud Circuit breaker provides an abstraction across different circuit breaker implementations.
+It provides a consistent API to use in your applications, letting you, the developer, choose the circuit breaker implementation that best fits your needs for your application.
+
+=== Supported Implementations
+
+Spring Cloud supports the following circuit-breaker implementations:
+
+* https://github.com/resilience4j/resilience4j[Resilience4J]
+* https://github.com/alibaba/Sentinel[Sentinel]
+* https://github.com/spring-projects/spring-retry[Spring Retry]
+
+== Core Concepts
+
+To create a circuit breaker in your code, you can use the `CircuitBreakerFactory` API. When you include a Spring Cloud Circuit Breaker starter on your classpath, a bean that implements this API is automatically created for you.
+The following example shows a simple example of how to use this API:
+
+====
+[source,java]
+----
+@Service
+public static class DemoControllerService {
+	private RestTemplate rest;
+	private CircuitBreakerFactory cbFactory;
+
+	public DemoControllerService(RestTemplate rest, CircuitBreakerFactory cbFactory) {
+		this.rest = rest;
+		this.cbFactory = cbFactory;
+	}
+
+	public String slow() {
+		return cbFactory.create("slow").run(() -> rest.getForObject("/slow", String.class), throwable -> "fallback");
+	}
+
+}
+----
+====
+
+The `CircuitBreakerFactory.create` API creates an instance of a class called `CircuitBreaker`.
+The `run` method takes a `Supplier` and a `Function`.
+The `Supplier` is the code that you are going to wrap in a circuit breaker.
+The `Function` is the fallback that is run if the circuit breaker is tripped.
+The function is passed the `Throwable` that caused the fallback to be triggered.
+You can optionally exclude the fallback if you do not want to provide one.
+
+=== Circuit Breakers In Reactive Code
+
+If Project Reactor is on the class path, you can also use `ReactiveCircuitBreakerFactory` for your reactive code.
+The following example shows how to do so:
+
+====
+[source,java]
+----
+@Service
+public static class DemoControllerService {
+	private ReactiveCircuitBreakerFactory cbFactory;
+	private WebClient webClient;
+
+
+	public DemoControllerService(WebClient webClient, ReactiveCircuitBreakerFactory cbFactory) {
+		this.webClient = webClient;
+		this.cbFactory = cbFactory;
+	}
+
+	public Mono<String> slow() {
+		return webClient.get().uri("/slow").retrieve().bodyToMono(String.class).transform(
+		it -> cbFactory.create("slow").run(it, throwable -> return Mono.just("fallback")));
+	}
+}
+----
+====
+
+The `ReactiveCircuitBreakerFactory.create` API creates an instance of a class called `ReactiveCircuitBreaker`.
+The `run` method takes a `Mono` or a `Flux` and wraps it in a circuit breaker.
+You can optionally profile a fallback `Function`, which will be called if the circuit breaker is tripped and is passed the `Throwable`
+that caused the failure.
+
+== Configuration
+
+You can configure your circuit breakers by creating beans of type `Customizer`.
+The `Customizer` interface has a single method (called `customize`) that takes the `Object` to customize.
+
+For detailed information on how to customize a given implementation see
+the following documentation:
+
+* link:../../../../spring-cloud-circuitbreaker/current/reference/html/spring-cloud-circuitbreaker.html#configuring-resilience4j-circuit-breakers[Resilience4J]
+* link:https://github.com/alibaba/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-docs/src/main/asciidoc/circuitbreaker-sentinel.adoc#circuit-breaker-spring-cloud-circuit-breaker-with-sentinel--configuring-sentinel-circuit-breakers[Sentinel]
+* link:../../../../../spring-cloud-circuitbreaker/docs/current/reference/html/spring-cloud-circuitbreaker.html#configuring-spring-retry-circuit-breakers[Spring Retry]
+
+Some `CircuitBreaker` implementations such as `Resilience4JCircuitBreaker` call `customize` method every time `CircuitBreaker#run` is called.
+It can be inefficient. In that case, you can use `CircuitBreaker#once` method. It is useful where calling `customize` many times doesn't make sense,
+for example, in case of https://resilience4j.readme.io/docs/circuitbreaker#section-consume-emitted-circuitbreakerevents[consuming Resilience4j's  events].
+
+The following example shows the way for each `io.github.resilience4j.circuitbreaker.CircuitBreaker` to consume events.
+
+====
+[source,java]
+----
+Customizer.once(circuitBreaker -> {
+  circuitBreaker.getEventPublisher()
+    .onStateTransition(event -> log.info("{}: {}", event.getCircuitBreakerName(), event.getStateTransition()));
+}, CircuitBreaker::getName)
+----
+====