From 5dce5ee595c0035ddf099904f5616197b14654b1 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Wed, 28 Apr 2021 22:34:16 -0700 Subject: [PATCH] Align adoc filename with anchors See gh-26296 --- .../spring-boot-docs/build.gradle | 4 +- ...tion-ready-features.adoc => actuator.adoc} | 16 ++--- .../docs/asciidoc/anchor-rewrite.properties | 20 +++--- ...s.adoc => auto-configuration-classes.adoc} | 0 .../src/docs/asciidoc/build-tool-plugins.adoc | 6 +- .../{spring-boot-cli.adoc => cli.adoc} | 2 +- ...doc => common-application-properties.adoc} | 2 +- ...adata.adoc => configuration-metadata.adoc} | 4 +- ...versions.adoc => dependency-versions.adoc} | 4 +- .../src/docs/asciidoc/deployment.adoc | 6 +- ...ation-overview.adoc => documentation.adoc} | 36 +++++------ ...le-jar-format.adoc => executable-jar.adoc} | 0 ...pring-boot-features.adoc => features.adoc} | 64 +++++++++---------- .../src/docs/asciidoc/getting-started.adoc | 12 ++-- .../src/docs/asciidoc/howto.adoc | 50 +++++++-------- .../src/docs/asciidoc/index.adoc | 22 +++---- .../src/docs/asciidoc/index.singleadoc | 22 +++---- ...tion.adoc => test-auto-configuration.adoc} | 0 .../{using-spring-boot.adoc => using.adoc} | 6 +- 19 files changed, 138 insertions(+), 138 deletions(-) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{production-ready-features.adoc => actuator.adoc} (98%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-auto-configuration-classes.adoc => auto-configuration-classes.adoc} (100%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{spring-boot-cli.adoc => cli.adoc} (99%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-application-properties.adoc => common-application-properties.adoc} (93%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-configuration-metadata.adoc => configuration-metadata.adoc} (99%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-dependency-versions.adoc => dependency-versions.adoc} (92%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{documentation-overview.adoc => documentation.adoc} (50%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-executable-jar-format.adoc => executable-jar.adoc} (100%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{spring-boot-features.adoc => features.adoc} (98%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{appendix-test-auto-configuration.adoc => test-auto-configuration.adoc} (100%) rename spring-boot-project/spring-boot-docs/src/docs/asciidoc/{using-spring-boot.adoc => using.adoc} (99%) diff --git a/spring-boot-project/spring-boot-docs/build.gradle b/spring-boot-project/spring-boot-docs/build.gradle index 711c742a44..3d8b8a81a9 100644 --- a/spring-boot-project/spring-boot-docs/build.gradle +++ b/spring-boot-project/spring-boot-docs/build.gradle @@ -195,13 +195,13 @@ task documentAutoConfigurationClasses(type: org.springframework.boot.build.autoc task documentDependencyVersions(type: org.springframework.boot.build.constraints.DocumentConstrainedVersions) { dependsOn dependencyVersions constrainedVersions.set(providers.provider { dependencyVersions.constrainedVersions }) - outputFile = file("${buildDir}/docs/generated/dependency-versions.adoc") + outputFile = file("${buildDir}/docs/generated/generated-dependency-versions.adoc") } task documentVersionProperties(type: org.springframework.boot.build.constraints.DocumentVersionProperties) { dependsOn dependencyVersions versionProperties.set(providers.provider { dependencyVersions.versionProperties}) - outputFile = file("${buildDir}/docs/generated/version-properties.adoc") + outputFile = file("${buildDir}/docs/generated/generated-version-properties.adoc") } task documentConfigurationProperties(type: org.springframework.boot.build.context.properties.DocumentConfigurationProperties) { diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc similarity index 98% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc index cd596bebc9..93f58b552e 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc @@ -127,7 +127,7 @@ The following technology-agnostic endpoints are available: Disabled by default. | `startup` -| Shows the <> collected by the `ApplicationStartup`. +| Shows the <> collected by the `ApplicationStartup`. Requires the `SpringApplication` to be configured with a `BufferingApplicationStartup`. | `threaddump` @@ -1007,7 +1007,7 @@ If you prefer not to include routing data sources in the indicator's output, set Applications deployed on Kubernetes can provide information about their internal state with https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes[Container Probes]. Depending on https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[your Kubernetes configuration], the kubelet will call those probes and react to the result. -Spring Boot manages your <> out-of-the-box. +Spring Boot manages your <> out-of-the-box. If deployed in a Kubernetes environment, actuator will gather the "Liveness" and "Readiness" information from the `ApplicationAvailability` interface and use that information in dedicated <>: `LivenessStateHealthIndicator` and `ReadinessStateHealthIndicator`. These indicators will be shown on the global health endpoint (`"/actuator/health"`). They will also be exposed as separate HTTP Probes using <>: `"/actuator/health/liveness"` and `"/actuator/health/readiness"`. @@ -1038,7 +1038,7 @@ These health groups are only enabled automatically if the application is <>. +The `"startupProbe"` is not necessarily needed here as the `"readinessProbe"` fails until all startup tasks are done, see <>. WARNING: If your Actuator endpoints are deployed on a separate management context, be aware that endpoints are then not using the same web infrastructure (port, connection pools, framework components) as the main application. In this case, a probe check could be successful even if the main application does not work properly (for example, it cannot accept new connections). @@ -1063,11 +1063,11 @@ You can, for example, configure additional Health Indicators: By default, Spring Boot does not add other Health Indicators to these groups. The "`liveness`" Probe should not depend on health checks for external systems. -If the <> is broken, Kubernetes will try to solve that problem by restarting the application instance. +If the <> is broken, Kubernetes will try to solve that problem by restarting the application instance. This means that if an external system fails (e.g. a database, a Web API, an external cache), Kubernetes might restart all application instances and create cascading failures. As for the "`readiness`" Probe, the choice of checking external systems must be made carefully by the application developers, i.e. Spring Boot does not include any additional health checks in the readiness probe. -If the <> is unready, Kubernetes will not route traffic to that instance. +If the <> is unready, Kubernetes will not route traffic to that instance. Some external systems might not be shared by application instances, in which case they could quite naturally be included in a readiness probe. Other external systems might not be essential to the application (the application could have circuit breakers and fallbacks), in which case they definitely should not be included. Unfortunately, an external system that is shared by all application instances is common, and you have to make a judgement call: include it in the readiness probe and expect that the application is taken out of service when the external service is down, or leave it out and deal with failures higher up the stack, e.g. using a circuit breaker in the caller. @@ -1088,7 +1088,7 @@ An important aspect of the Kubernetes Probes support is its consistency with the There is a significant difference between the `AvailabilityState` which is the in-memory, internal state of the application and the actual Probe which exposes that state: depending on the phase of application lifecycle, the Probe might not be available. -Spring Boot publishes <>, +Spring Boot publishes <>, and Probes can listen to such events and expose the `AvailabilityState` information. The following tables show the `AvailabilityState` and the state of HTTP connectors at different stages. @@ -2210,7 +2210,7 @@ To add to the default tags, provide one or more ``@Bean``s that implement `WebMv To replace the default tags, provide a `@Bean` that implements `WebMvcTagsProvider`. TIP: In some cases, exceptions handled in Web controllers are not recorded as request metrics tags. -Applications can opt-in and record exceptions by <>. +Applications can opt-in and record exceptions by <>. @@ -2249,7 +2249,7 @@ To add to the default tags, provide one or more ``@Bean``s that implement `WebFl To replace the default tags, provide a `@Bean` that implements `WebFluxTagsProvider`. TIP: In some cases, exceptions handled in controllers and handler functions are not recorded as request metrics tags. -Applications can opt-in and record exceptions by <>. +Applications can opt-in and record exceptions by <>. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties index 266d34b0bf..ba2c27532d 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties @@ -27,7 +27,7 @@ legal -# (documentation-overview.adoc) +# (documentation.adoc) # 1 = Spring Boot Documentation boot-documentation=\ documentation @@ -177,7 +177,7 @@ getting-started.whats=next -# (using-spring-boot.adoc) +# (using.adoc) # 1 = Using Spring Boot using-boot=\ using @@ -348,7 +348,7 @@ using.whats-next -# (spring-boot-features.adoc) +# (features.adoc) # 1 = Spring Boot Features boot-features=\ features @@ -1620,7 +1620,7 @@ features.whats-next -# (production-ready-features.adoc) +# (actuator.adoc) # 1 = Spring Boot Actuator: Production-ready Features production-ready=\ actuator @@ -2178,7 +2178,7 @@ deployment.whats-next -# (spring-boot-cli.adoc) +# (cli.adoc) # 1 = Spring Boot CLI cli=\ cli @@ -2924,7 +2924,7 @@ common-application-properties.testing -# (appendix-configuration-metadata.adoc) +# (configuration-metadata.adoc) # 1 = Configuration Metadata configuration-metadata=\ configuration-metadata @@ -3007,7 +3007,7 @@ configuration-metadata.annotation-processor.adding-additional-metadata -# (appendix-auto-configuration-classes.adoc) +# (auto-configuration-classes.adoc) # 1 = Auto-configuration Classes auto-configuration-classes=\ auto-configuration-classes @@ -3022,7 +3022,7 @@ auto-configuration-classes.actuator -# (appendix-test-auto-configuration.adoc) +# (test-auto-configuration.adoc) # 1 = Test Auto-configuration Annotations test-auto-configuration=\ test-auto-configuration @@ -3033,7 +3033,7 @@ test-auto-configuration.slices -# (appendix-executable-jar-format.adoc) +# (executable-jar.adoc) # 1 = The Executable Jar Format executable-jar=\ executable-jar @@ -3092,7 +3092,7 @@ executable-jar.alternatives -# (appendix-dependency-versions.adoc) +# (dependency-versions.adoc) # 1 = Dependency versions dependency-versions=\ dependency-versions diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-auto-configuration-classes.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/auto-configuration-classes.adoc similarity index 100% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-auto-configuration-classes.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/auto-configuration-classes.adoc diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/build-tool-plugins.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/build-tool-plugins.adoc index 23bfcb6c67..7323c51ed4 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/build-tool-plugins.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/build-tool-plugins.adoc @@ -5,7 +5,7 @@ include::attributes.adoc[] Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a variety of features, including the packaging of executable jars. This section provides more details on both plugins as well as some help should you need to extend an unsupported build system. -If you are just getting started, you might want to read "`<>`" from the "`<>`" section first. +If you are just getting started, you might want to read "`<>`" from the "`<>`" section first. @@ -54,7 +54,7 @@ You need to remember to start Ant using the `-lib` option, as shown in the follo $ ant -lib ---- -TIP: The "`Using Spring Boot`" section includes a more complete example of <>. +TIP: The "`Using Spring Boot`" section includes a more complete example of <>. @@ -186,7 +186,7 @@ This section contains three examples of using `findmainclass`. [[build-tool-plugins.other-build-systems]] == Supporting Other Build Systems If you want to use a build tool other than Maven, Gradle, or Ant, you likely need to develop your own plugin. -Executable jars need to follow a specific format and certain entries need to be written in an uncompressed form (see the "`<>`" section in the appendix for details). +Executable jars need to follow a specific format and certain entries need to be written in an uncompressed form (see the "`<>`" section in the appendix for details). The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to actually generate jars. If you need to, you may use this library directly. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-cli.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/cli.adoc similarity index 99% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-cli.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/cli.adoc index 25405ee0b8..3bd9f37cd1 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-cli.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/cli.adoc @@ -171,7 +171,7 @@ Doing so consults Spring Boot's default dependency metadata to deduce the artifa NOTE: The default metadata is tied to the version of the CLI that you use. It changes only when you move to a new version of the CLI, putting you in control of when the versions of your dependencies may change. -A table showing the dependencies and their versions that are included in the default metadata can be found in the <>. +A table showing the dependencies and their versions that are included in the default metadata can be found in the <>. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-application-properties.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/common-application-properties.adoc similarity index 93% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-application-properties.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/common-application-properties.adoc index 9e23f3228a..e7c35794c6 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-application-properties.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/common-application-properties.adoc @@ -7,7 +7,7 @@ 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 Spring Boot properties and references to the underlying classes that consume them. -TIP: Spring Boot provides various conversion mechanism with advanced value formatting, make sure to review <>. +TIP: Spring Boot provides various conversion mechanism with advanced value formatting, make sure to review <>. 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. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-configuration-metadata.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/configuration-metadata.adoc similarity index 99% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-configuration-metadata.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/configuration-metadata.adoc index 9deb6574f8..2e863616eb 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-configuration-metadata.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/configuration-metadata.adoc @@ -407,7 +407,7 @@ The following table summarizes the list of supported providers: | Handles the property as if it were defined by the type defined by the mandatory `target` parameter. | `logger-name` -| Auto-completes valid logger names and <>. +| Auto-completes valid logger names and <>. Typically, package and class names available in the current project can be auto-completed as well as defined groups. | `spring-bean-reference` @@ -555,7 +555,7 @@ It is actually used internally as a `org.springframework.core.io.Resource` but c [[configuration-metadata.manual-hints.value-providers.logger-name]] ==== Logger Name -The **logger-name** provider auto-completes valid logger names and <>. +The **logger-name** provider auto-completes valid logger names and <>. Typically, package and class names available in the current project can be auto-completed. If groups are enabled (default) and if a custom logger group is identified in the configuration, auto-completion for it should be provided. Specific frameworks may have extra magic logger names that can be supported as well. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/dependency-versions.adoc similarity index 92% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/dependency-versions.adoc index 2d464b81d7..4b756b0684 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/dependency-versions.adoc @@ -13,7 +13,7 @@ This appendix provides details of the dependencies that are managed by Spring Bo The following table provides details of all of the dependency versions that are provided by Spring Boot in its CLI (Command Line Interface), Maven dependency management, and Gradle plugin. When you declare a dependency on one of these artifacts without declaring a version, the version listed in the table is used. -include::dependency-versions.adoc[] +include::generated-dependency-versions.adoc[] @@ -24,4 +24,4 @@ The following table provides all properties that can be used to override the ver Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/build.gradle[`spring-boot-dependencies` build.gradle] for a complete list of dependencies. You can learn how to customize these versions in your application in the <>. -include::version-properties.adoc[] +include::generated-version-properties.adoc[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc index d6f826174c..eef88b99cb 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc @@ -36,7 +36,7 @@ Once you have unpacked the jar file, you can also get an extra boost to startup NOTE: Using the `JarLauncher` over the application's main method has the added benefit of a predictable classpath order. The jar contains a `classpath.idx` file which is used by the `JarLauncher` when constructing the classpath. -More efficient container images can also be created by <> for your dependencies and application classes and resources (which normally change more frequently). +More efficient container images can also be created by <> for your dependencies and application classes and resources (which normally change more frequently). @@ -165,7 +165,7 @@ TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a bett Spring Boot auto-detects Kubernetes deployment environments by checking the environment for `"*_SERVICE_HOST"` and `"*_SERVICE_PORT"` variables. You can override this detection with the configprop:spring.main.cloud-platform[] configuration property. -Spring Boot helps you to <> and export it with <>. +Spring Boot helps you to <> and export it with <>. @@ -856,4 +856,4 @@ Check out the https://www.cloudfoundry.org/[Cloud Foundry], https://www.heroku.c These are just four of the most popular Java PaaS providers. Since Spring Boot is so amenable to cloud-based deployment, you can freely consider other providers as well. -The next section goes on to cover the _<>_, or you can jump ahead to read about _<>_. +The next section goes on to cover the _<>_, or you can jump ahead to read about _<>_. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation-overview.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc similarity index 50% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation-overview.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc index e17d4dd2f8..e342286584 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation-overview.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc @@ -64,37 +64,37 @@ If you are getting started with Spring Boot or 'Spring' in general, start with < [[documentation.using]] == Working with Spring Boot -Ready to actually start using Spring Boot? <>: +Ready to actually start using Spring Boot? <>: -* *Build systems:* <> | <> | <> | <> -* *Best practices:* <> | <> | <> | <> -* *Running your code:* <> | <> | <> | <> -* *Packaging your app:* <> -* *Spring Boot CLI:* <> +* *Build systems:* <> | <> | <> | <> +* *Best practices:* <> | <> | <> | <> +* *Running your code:* <> | <> | <> | <> +* *Packaging your app:* <> +* *Spring Boot CLI:* <> [[documentation.features]] == Learning About Spring Boot Features Need more details about Spring Boot's core features? -<>: +<>: -* *Core Features:* <> | <> | <> | <> -* *Web Applications:* <> | <> -* *Working with data:* <> | <> -* *Messaging:* <> | <> -* *Testing:* <> | <> | <> -* *Extending:* <> | <> +* *Core Features:* <> | <> | <> | <> +* *Web Applications:* <> | <> +* *Working with data:* <> | <> +* *Messaging:* <> | <> +* *Testing:* <> | <> | <> +* *Extending:* <> | <> [[documentation.actuator]] == Moving to Production -When you are ready to push your Spring Boot application to production, we have <> that you might like: +When you are ready to push your Spring Boot application to production, we have <> that you might like: -* *Management endpoints:* <> -* *Connection options:* <> | <> -* *Monitoring:* <> | <> | <> | <> +* *Management endpoints:* <> +* *Connection options:* <> | <> +* *Monitoring:* <> | <> | <> | <> @@ -104,4 +104,4 @@ Finally, we have a few topics for more advanced users: * *Spring Boot Applications Deployment:* <> | <> * *Build tool plugins:* <> | <> -* *Appendix:* <> | <> | <> | <> | <> | <> +* *Appendix:* <> | <> | <> | <> | <> | <> diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-executable-jar-format.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/executable-jar.adoc similarity index 100% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-executable-jar-format.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/executable-jar.adoc diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc similarity index 98% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc index 6d6aeeb605..1d24decbc8 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc @@ -4,7 +4,7 @@ include::attributes.adoc[] This section dives into the details of Spring Boot. Here you can learn about the key features that you may want to use and customize. -If you have not already done so, you might want to read the "<>" and "<>" sections, so that you have a good grounding of the basics. +If you have not already done so, you might want to read the "<>" and "<>" sections, so that you have a good grounding of the basics. @@ -222,7 +222,7 @@ In addition, you can also obtain availability states by injecting the `Applicati The "`Liveness`" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing. A broken "`Liveness`" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. -NOTE: In general, the "Liveness" state should not be based on external checks, such as <>. +NOTE: In general, the "Liveness" state should not be based on external checks, such as <>. If it did, a failing external system (a database, a Web API, an external cache) would trigger massive restarts and cascading failures across the platform. The internal state of Spring Boot applications is mostly represented by the Spring `ApplicationContext`. @@ -262,7 +262,7 @@ We can also update the state of the application, when the application breaks and include::{include-springbootfeatures}/springapplication/availability/LocalCacheVerifier.java[] ---- -Spring Boot provides <>. +Spring Boot provides <>. You can get more guidance about <>. @@ -457,7 +457,7 @@ Properties are considered in the following order (with values from lower items o . `properties` attribute on your tests. Available on {spring-boot-test-module-api}/context/SpringBootTest.html[`@SpringBootTest`] and the <>. . {spring-framework-api}/test/context/TestPropertySource.html[`@TestPropertySource`] annotations on your tests. -. <> in the `$HOME/.config/spring-boot` directory when devtools is active. +. <> in the `$HOME/.config/spring-boot` directory when devtools is active. Config data files are considered in the following order: @@ -482,7 +482,7 @@ For one-off testing, you can launch with a specific command line switch (for exa TIP: The `env` and `configprops` endpoints can be useful in determining why a property has a particular value. You can use these two endpoints to diagnose unexpected property values. -See the "<>" section for details. +See the "<>" section for details. @@ -1180,7 +1180,7 @@ include::{include-springbootfeatures}/externalizedconfiguration/use/MyService.ja ---- TIP: Using `@ConfigurationProperties` also lets you generate metadata files that can be used by IDEs to offer auto-completion for your own keys. -See the <> for details. +See the <> for details. @@ -1561,7 +1561,7 @@ Doing so avoids any problems that may be caused by early instantiation. TIP: The `spring-boot-actuator` module includes an endpoint that exposes all `@ConfigurationProperties` beans. Point your web browser to `/actuator/configprops` or use the equivalent JMX endpoint. -See the "<>" section for details. +See the "<>" section for details. @@ -1578,7 +1578,7 @@ The following table summarizes the features that are supported by `@Configuratio | Yes | Limited (see <>) -| <> +| <> | Yes | No @@ -2564,7 +2564,7 @@ For machine clients, it produces a JSON response with details of the error, the For browser clients, there is a "`whitelabel`" error view that renders the same data in HTML format (to customize it, add a `View` that resolves to `error`). There are a number of `server.error` properties that can be set if you want to customize the default error handling behavior. -See the <> section of the Appendix. +See the <> section of the Appendix. To replace the default behavior completely, you can implement `ErrorController` and register a bean definition of that type or add a bean of type `ErrorAttributes` to use the existing mechanism but replace the contents. @@ -2581,7 +2581,7 @@ include::{include-springbootfeatures}/webapplications/servlet/MyControllerAdvice In the preceding example, if `YourException` is thrown by a controller defined in the same package as `AcmeController`, a JSON representation of the `CustomErrorType` POJO is used instead of the `ErrorAttributes` representation. -In some cases, errors handled at the controller level are not recorded by the <>. +In some cases, errors handled at the controller level are not recorded by the <>. Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute: [source,java,indent=0,subs="verbatim,quotes,attributes"] @@ -2846,7 +2846,7 @@ include::{include-springbootfeatures}/webapplications/webflux/CustomErrorWebExce For a more complete picture, you can also subclass `DefaultErrorWebExceptionHandler` directly and override specific methods. -In some cases, errors handled at the controller or handler function level are not recorded by the <>. +In some cases, errors handled at the controller or handler function level are not recorded by the <>. Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute: [source,java,indent=0,subs="verbatim,quotes,attributes"] @@ -3860,7 +3860,7 @@ The console is auto-configured when the following conditions are met: * You are developing a servlet-based web application. * `com.h2database:h2` is on the classpath. -* You are using <>. +* You are using <>. TIP: If you are not using Spring Boot's developer tools but would still like to make use of H2's console, you can configure the configprop:spring.h2.console.enabled[] property with a value of `true`. @@ -5381,7 +5381,7 @@ You can customize this behaviour using the configprop:spring.kafka.streams.auto- [[features.messaging.kafka.additional-properties]] ==== Additional Kafka Properties -The properties supported by auto configuration are shown in <>. +The properties supported by auto configuration are shown in <>. Note that, for the most part, these properties (hyphenated or camelCase) map directly to the Apache Kafka dotted properties. Refer to the Apache Kafka documentation for details. @@ -6088,7 +6088,7 @@ When testing Spring Boot applications, this is often not required. Spring Boot's `@*Test` annotations search for your primary configuration automatically whenever you do not explicitly define one. The search algorithm works up from the package that contains the test until it finds a class annotated with `@SpringBootApplication` or `@SpringBootConfiguration`. -As long as you <> in a sensible way, your main configuration is usually found. +As long as you <> in a sensible way, your main configuration is usually found. [NOTE] ==== @@ -6301,7 +6301,7 @@ To test that object JSON serialization and deserialization is working as expecte * `Gson` * `Jsonb` -TIP: A list of the auto-configurations that are enabled by `@JsonTest` can be <>. +TIP: A list of the auto-configurations that are enabled by `@JsonTest` can be <>. If you need to configure elements of the auto-configuration, you can use the `@AutoConfigureJsonTesters` annotation. @@ -6336,7 +6336,7 @@ To test whether Spring MVC controllers are working as expected, use the `@WebMvc Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebMvcTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be <>. TIP: If you need to register extra components, such as the Jackson `Module`, you can import additional configuration classes by using `@Import` on your test. @@ -6384,7 +6384,7 @@ To test that {spring-framework-docs}/web-reactive.html[Spring WebFlux] controlle Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebFluxTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configurations that are enabled by `@WebFluxTest` can be <>. +TIP: A list of the auto-configurations that are enabled by `@WebFluxTest` can be <>. TIP: If you need to register extra components, such as Jackson `Module`, you can import additional configuration classes using `@Import` on your test. @@ -6420,7 +6420,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. (For more about using Cassandra with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@DataCassandraTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataCassandraTest` can be <>. The following example shows a typical setup for using Cassandra tests in Spring Boot: @@ -6442,7 +6442,7 @@ This can be disabled using the `showSql()` attribute of the annotation. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataJpaTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be <>. By default, data JPA tests are transactional and roll back at the end of each test. See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details. @@ -6480,7 +6480,7 @@ By default, it configures an in-memory embedded database and a `JdbcTemplate`. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@JdbcTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configurations that are enabled by `@JdbcTest` can be <>. +TIP: A list of the auto-configurations that are enabled by `@JdbcTest` can be <>. By default, JDBC tests are transactional and roll back at the end of each test. See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details. @@ -6503,7 +6503,7 @@ By default, it configures an in-memory embedded database, a `JdbcTemplate`, and Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataJdbcTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configurations that are enabled by `@DataJdbcTest` can be <>. +TIP: A list of the auto-configurations that are enabled by `@DataJdbcTest` can be <>. By default, Data JDBC tests are transactional and roll back at the end of each test. See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details. @@ -6523,7 +6523,7 @@ If you want to replace it with an in-memory database, you can use `@AutoConfigur Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@JooqTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configurations that are enabled by `@JooqTest` can be <>. +TIP: A list of the auto-configurations that are enabled by `@JooqTest` can be <>. `@JooqTest` configures a `DSLContext`. The following example shows the `@JooqTest` annotation in use: @@ -6546,7 +6546,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. (For more about using MongoDB with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be <>. The following class shows the `@DataMongoTest` annotation in use: @@ -6573,7 +6573,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. (For more about using Neo4J with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be <>. The following example shows a typical setup for using Neo4J tests in Spring Boot: @@ -6604,7 +6604,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. (For more about using Redis with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be <>. The following example shows the `@DataRedisTest` annotation in use: @@ -6623,7 +6623,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. (For more about using LDAP with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be <>. The following example shows the `@DataLdapTest` annotation in use: @@ -6649,7 +6649,7 @@ By default, it auto-configures Jackson, GSON, and Jsonb support, configures a `R Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@RestClientTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -TIP: A list of the auto-configuration settings that are enabled by `@RestClientTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@RestClientTest` can be <>. The specific beans that you want to test should be specified by using the `value` or `components` attribute of `@RestClientTest`, as shown in the following example: @@ -6743,7 +6743,7 @@ By default, it configures a mock `WebServiceServer` bean and automatically custo (For more about using Web Services with Spring Boot, see "<>", earlier in this chapter.) -TIP: A list of the auto-configuration settings that are enabled by `@WebServiceClientTest` can be <>. +TIP: A list of the auto-configuration settings that are enabled by `@WebServiceClientTest` can be <>. The following example shows the `@WebServiceClientTest` annotation in use: @@ -6779,7 +6779,7 @@ TIP: A slice or `@AutoConfigure...` annotation can be customized this way as lon [[features.testing.spring-boot-applications.user-configuration-and-slicing]] ==== User Configuration and Slicing -If you <> in a sensible way, your `@SpringBootApplication` class is <> as the configuration of your tests. +If you <> in a sensible way, your `@SpringBootApplication` class is <> as the configuration of your tests. It then becomes important not to litter the application's main class with configuration settings that are specific to a particular area of its functionality. @@ -7253,7 +7253,7 @@ Here are some rules we follow internally to make sure descriptions are consisten * Use `java.time.Duration` rather than `long` and describe the default unit if it differs from milliseconds, e.g. "If a duration suffix is not specified, seconds will be used". * Do not provide the default value in the description unless it has to be determined at runtime. -Make sure to <> so that IDE assistance is available for your keys as well. +Make sure to <> so that IDE assistance is available for your keys as well. You may want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to make sure your keys are properly documented. Using your own starter in a compatible IDE is also a good idea to validate that quality of the metadata. @@ -7468,7 +7468,7 @@ data class KotlinExampleProperties( } ---- -TIP: To generate <> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency. +TIP: To generate <> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency. Note that some features (such as detecting the default value or deprecated items) are not working due to limitations in the model kapt provides. @@ -7662,4 +7662,4 @@ Spring Boot can use that information when serving static resources, but this can If you want to learn more about any of the classes discussed in this section, you can check out the {spring-boot-api}/[Spring Boot API documentation] or you can browse the {spring-boot-code}[source code directly]. If you have specific questions, take a look at the <> section. -If you are comfortable with Spring Boot's core features, you can continue on and read about <>. +If you are comfortable with Spring Boot's core features, you can continue on and read about <>. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started.adoc index 25bde796fd..950f823223 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started.adoc @@ -108,7 +108,7 @@ Ubuntu users can run `sudo apt-get install maven`. Windows users with https://chocolatey.org/[Chocolatey] can run `choco install maven` from an elevated (administrator) prompt. Spring Boot dependencies use the `org.springframework.boot` `groupId`. -Typically, your Maven POM file inherits from the `spring-boot-starter-parent` project and declares dependencies to one or more <>. +Typically, your Maven POM file inherits from the `spring-boot-starter-parent` project and declares dependencies to one or more <>. Spring Boot also provides an optional <> to create executable jars. More details on getting started with Spring Boot and Maven can be found in the {spring-boot-maven-plugin-docs}#getting-started[Getting Started section] of the Maven plugin's reference guide. @@ -121,7 +121,7 @@ Spring Boot is compatible with Gradle 6.8 and 7.x. If you do not already have Gradle installed, you can follow the instructions at https://gradle.org. Spring Boot dependencies can be declared by using the `org.springframework.boot` `group`. -Typically, your project declares dependencies to one or more <>. +Typically, your project declares dependencies to one or more <>. Spring Boot provides a useful <> that can be used to simplify dependency declarations and to create executable jars. .Gradle Wrapper @@ -449,7 +449,7 @@ For simplicity, we continue to use a plain text editor for this example. Spring Boot provides a number of "`Starters`" that let you add jars to your classpath. Our applications for smoke tests use the `spring-boot-starter-parent` in the `parent` section of the POM. The `spring-boot-starter-parent` is a special starter that provides useful Maven defaults. -It also provides a <> section so that you can omit `version` tags for "`blessed`" dependencies. +It also provides a <> section so that you can omit `version` tags for "`blessed`" dependencies. Other "`Starters`" provide dependencies that you are likely to need when developing a specific type of application. Since we are developing a web application, we add a `spring-boot-starter-web` dependency. @@ -604,7 +604,7 @@ An uber jar packages all the classes from all the application's dependencies int The problem with this approach is that it becomes hard to see which libraries are in your application. It can also be problematic if the same filename is used (but with different content) in multiple jars. -Spring Boot takes a <> and lets you actually nest jars directly. +Spring Boot takes a <> and lets you actually nest jars directly. **** To create an executable jar, we need to add the `spring-boot-maven-plugin` to our `pom.xml`. @@ -688,5 +688,5 @@ Hopefully, this section provided some of the Spring Boot basics and got you on y If you are a task-oriented type of developer, you might want to jump over to https://spring.io and check out some of the https://spring.io/guides/[getting started] guides that solve specific "`How do I do that with Spring?`" problems. We also have Spring Boot-specific "`<>`" reference documentation. -Otherwise, the next logical step is to read _<>_. -If you are really impatient, you could also jump ahead and read about _<>_. +Otherwise, the next logical step is to read _<>_. +If you are really impatient, you could also jump ahead and read about _<>_. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc index f688c9d016..04cd6161ec 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc @@ -48,7 +48,7 @@ The Spring Boot auto-configuration tries its best to "`do the right thing`", but There is a really useful `ConditionEvaluationReport` available in any Spring Boot `ApplicationContext`. You can see it if you enable `DEBUG` logging output. -If you use the `spring-boot-actuator` (see <>), there is also a `conditions` endpoint that renders the report in JSON. +If you use the `spring-boot-actuator` (see <>), there is also a `conditions` endpoint that renders the report in JSON. Use that endpoint to debug the application and see what features have been added (and which have not been added) by Spring Boot at runtime. Many more questions can be answered by looking at the source code and the Javadoc. @@ -80,7 +80,7 @@ There is more than one way to register additional customizations: * Declaratively, for all applications, by adding a `META-INF/spring.factories` and packaging a jar file that the applications all use as a library. The `SpringApplication` sends some special `ApplicationEvents` to the listeners (some even before the context is created) and then registers the listeners for events published by the `ApplicationContext` as well. -See "`<>`" in the '`Spring Boot features`' section for a complete list. +See "`<>`" in the '`Spring Boot features`' section for a complete list. It is also possible to customize the `Environment` before the application context is refreshed by using `EnvironmentPostProcessor`. Each implementation should be registered in `META-INF/spring.factories`, as shown in the following example: @@ -112,7 +112,7 @@ This is too late to configure certain properties such as `+logging.*+` and `+spr [[howto.application.context-hierarchy]] === Build an ApplicationContext Hierarchy (Adding a Parent or Root Context) You can use the `ApplicationBuilder` class to create parent/child `ApplicationContext` hierarchies. -See "`<>`" in the '`Spring Boot features`' section for more information. +See "`<>`" in the '`Spring Boot features`' section for more information. @@ -263,7 +263,7 @@ The actual application _now_ shows the banner (as overridden by configuration) a [[howto.properties-and-configuration.external-properties-location]] === Change the Location of External Properties of an Application -By default, properties from different sources are added to the Spring `Environment` in a defined order (see "`<>`" in the '`Spring Boot features`' section for the exact order). +By default, properties from different sources are added to the Spring `Environment` in a defined order (see "`<>`" in the '`Spring Boot features`' section for the exact order). You can also provide the following System properties (or environment variables) to change the behavior: @@ -329,7 +329,7 @@ The preceding example YAML corresponds to the following `application.properties` server.port=9000 ---- -See "`<>`" in the '`Spring Boot features`' section for more information about YAML. +See "`<>`" in the '`Spring Boot features`' section for more information about YAML. @@ -355,7 +355,7 @@ In Spring Boot, you can also set the active profile in `application.properties`, A value set this way is replaced by the System property or environment variable setting but not by the `SpringApplicationBuilder.profiles()` method. Thus, the latter Java API can be used to augment the profiles without changing the defaults. -See "`<>`" in the "`Spring Boot features`" section for more information. +See "`<>`" in the "`Spring Boot features`" section for more information. @@ -402,7 +402,7 @@ There is not (and technically cannot be) an exhaustive list of all supported pro A running application with the Actuator features has a `configprops` endpoint that shows all the bound and bindable properties available through `@ConfigurationProperties`. -The appendix includes an <> example with a list of the most common properties supported by Spring Boot. +The appendix includes an <> example with a list of the most common properties supported by Spring Boot. The definitive list comes from searching the source code for `@ConfigurationProperties` and `@Value` annotations as well as the occasional use of `Binder`. For more about the exact ordering of loading properties, see "<>". @@ -497,7 +497,7 @@ Thanks to relaxed binding of `Environment` values, you can also use configprop:s To switch off the HTTP endpoints completely but still create a `WebApplicationContext`, use `server.port=-1` (doing so is sometimes useful for testing). -For more details, see "`<>`" in the '`Spring Boot Features`' section, or the {spring-boot-autoconfigure-module-code}/web/ServerProperties.java[`ServerProperties`] source code. +For more details, see "`<>`" in the '`Spring Boot Features`' section, or the {spring-boot-autoconfigure-module-code}/web/ServerProperties.java[`ServerProperties`] source code. @@ -656,7 +656,7 @@ As of Undertow 1.4.0+, both `h2` and `h2c` are supported on JDK 8 without any ad === Configure the Web Server Generally, you should first consider using one of the many available configuration keys and customize your web server by adding new entries in your `application.properties` (or `application.yml`, or environment, etc. see "`<>`"). The `server.{asterisk}` namespace is quite useful here, and it includes namespaces like `server.tomcat.{asterisk}`, `server.jetty.{asterisk}` and others, for server-specific features. -See the list of <>. +See the list of <>. The previous sections covered already many common use cases, such as compression, SSL or HTTP/2. However, if a configuration key doesn't exist for your use case, you should then look at {spring-boot-module-api}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`]. @@ -736,7 +736,7 @@ If no `dispatcherType` is specified on a filter registration, `REQUEST` is used. This aligns with the Servlet Specification's default dispatcher type. ==== -Like any other Spring bean, you can define the order of Servlet filter beans; please make sure to check the "`<>`" section. +Like any other Spring bean, you can define the order of Servlet filter beans; please make sure to check the "`<>`" section. @@ -1059,7 +1059,7 @@ These features are described in six enums (in Jackson) that map onto properties |=== For example, to enable pretty print, set `spring.jackson.serialization.indent_output=true`. -Note that, thanks to the use of <>, the case of `indent_output` does not have to match the case of the corresponding enum constant, which is `INDENT_OUTPUT`. +Note that, thanks to the use of <>, the case of `indent_output` does not have to match the case of the corresponding enum constant, which is `INDENT_OUTPUT`. This environment-based configuration is applied to the auto-configured `Jackson2ObjectMapperBuilder` bean and applies to any mappers created by using the builder, including the auto-configured `ObjectMapper` bean. @@ -1261,7 +1261,7 @@ This section answers questions related to using them. [[howto.http-clients.rest-template-proxy-configuration]] === Configure RestTemplate to Use a Proxy -As described in <>, you can use a `RestTemplateCustomizer` with `RestTemplateBuilder` to build a customized `RestTemplate`. +As described in <>, you can use a `RestTemplateCustomizer` with `RestTemplateBuilder` to build a customized `RestTemplate`. This is the recommended approach for creating a `RestTemplate` configured to use a proxy. The exact details of the proxy configuration depend on the underlying client request factory that is being used. @@ -1330,7 +1330,7 @@ By default, Spring Boot picks up the native configuration from its default locat === Configure Logback for Logging If you need to apply customizations to logback beyond those that can be achieved with `application.properties`, you'll need to add a standard logback configuration file. You can add a `logback.xml` file to the root of your classpath for logback to find. -You can also use `logback-spring.xml` if you want to use the <>. +You can also use `logback-spring.xml` if you want to use the <>. TIP: The Logback documentation has a https://logback.qos.ch/manual/configuration.html[dedicated section that covers configuration] in some detail. @@ -1493,7 +1493,7 @@ This section answers questions related to doing so. === Configure a Custom DataSource To configure your own `DataSource`, define a `@Bean` of that type in your configuration. Spring Boot reuses your `DataSource` anywhere one is required, including database initialization. -If you need to externalize some settings, you can bind your `DataSource` to the environment (see "`<>`"). +If you need to externalize some settings, you can bind your `DataSource` to the environment (see "`<>`"). The following example shows how to define a data source in a bean: @@ -1601,7 +1601,7 @@ This example uses a more generic `configuration` sub namespace as the example do NOTE: Because your custom configuration chooses to go with Hikari, `app.datasource.type` has no effect. In practice, the builder is initialized with whatever value you might set there and then overridden by the call to `.type()`. -See "`<>`" in the "`Spring Boot features`" section and the {spring-boot-autoconfigure-module-code}/jdbc/DataSourceAutoConfiguration.java[`DataSourceAutoConfiguration`] class for more details. +See "`<>`" in the "`Spring Boot features`" section and the {spring-boot-autoconfigure-module-code}/jdbc/DataSourceAutoConfiguration.java[`DataSourceAutoConfiguration`] class for more details. @@ -1941,7 +1941,7 @@ Be careful when switching from in-memory to a '`real`' database that you do not You either have to set `ddl-auto` explicitly or use one of the other mechanisms to initialize the database. NOTE: You can output the schema creation by enabling the `org.hibernate.SQL` logger. -This is done for you automatically if you enable the <>. +This is done for you automatically if you enable the <>. In addition, a file named `import.sql` in the root of the classpath is executed on startup if Hibernate creates the schema from scratch (that is, if the `ddl-auto` property is set to `create` or `create-drop`). This can be useful for demos and for testing if you are careful but is probably not something you want to be on the classpath in production. @@ -1967,7 +1967,7 @@ While we do not recommend using multiple data source initialization technologies This will defer data source initialization until after any `EntityManagerFactory` beans have been created and initialized. `schema.sql` can then be used to make additions to any schema creation performed by Hibernate and `data.sql` can be used to populate it. -If you are using a <>, like Flyway or Liquibase, you should use them alone to create and initialize the schema. +If you are using a <>, like Flyway or Liquibase, you should use them alone to create and initialize the schema. Using the basic `schema.sql` and `data.sql` scripts alongside Flyway or Liquibase is not recommended and support will be removed in a future release. @@ -2196,7 +2196,7 @@ See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[Ba [[howto.batch.?running-from-the-command-line]] === Running from the Command Line -Spring Boot converts any command line argument starting with `--` to a property to add to the `Environment`, see <>. +Spring Boot converts any command line argument starting with `--` to a property to add to the `Environment`, see <>. This should not be used to pass arguments to batch jobs. To specify batch arguments on the command line, use the regular format (i.e. without `--`), as shown in the following example: @@ -2238,7 +2238,7 @@ In a standalone application, the Actuator HTTP port defaults to the same as the To make the application listen on a different port, set the external property: configprop:management.server.port[]. To listen on a completely different network address (such as when you have an internal network for management and an external one for user applications), you can also set `management.server.address` to a valid IP address to which the server is able to bind. -For more detail, see the {spring-boot-actuator-autoconfigure-module-code}/web/server/ManagementServerProperties.java[`ManagementServerProperties`] source code and "`<>`" in the "`Production-ready features`" section. +For more detail, see the {spring-boot-actuator-autoconfigure-module-code}/web/server/ManagementServerProperties.java[`ManagementServerProperties`] source code and "`<>`" in the "`Production-ready features`" section. @@ -2257,7 +2257,7 @@ In general, you need a `View` that resolves with a name of `error` or a `@Contro Unless you replaced some of the default configuration, you should find a `BeanNameViewResolver` in your `ApplicationContext`, so a `@Bean` named `error` would be one way of doing that. See {spring-boot-autoconfigure-module-code}/web/servlet/error/ErrorMvcAutoConfiguration.java[`ErrorMvcAutoConfiguration`] for more options. -See also the section on "`<>`" for details of how to register handlers in the servlet container. +See also the section on "`<>`" for details of how to register handlers in the servlet container. @@ -2367,12 +2367,12 @@ This section answers questions about how it works. [[howto.hotswapping.reload-static-content]] === Reload Static Content There are several options for hot reloading. -The recommended approach is to use <>, as it provides additional development-time features, such as support for fast application restarts and LiveReload as well as sensible development-time configuration (such as template caching). +The recommended approach is to use <>, as it provides additional development-time features, such as support for fast application restarts and LiveReload as well as sensible development-time configuration (such as template caching). Devtools works by monitoring the classpath for changes. This means that static resource changes must be "built" for the change to take effect. By default, this happens automatically in Eclipse when you save your changes. In IntelliJ IDEA, the Make Project command triggers the necessary build. -Due to the <>, changes to static resources do not trigger a restart of your application. +Due to the <>, changes to static resources do not trigger a restart of your application. They do, however, trigger a live reload. Alternatively, running in an IDE (especially with debugging on) is a good way to do development (all modern IDEs allow reloading of static resources and usually also allow hot-swapping of Java class changes). @@ -2385,7 +2385,7 @@ You can use that with an external css/js compiler process if you are writing tha [[howto.hotswapping.reload-templates]] === Reload Templates without Restarting the Container Most of the templating technologies supported by Spring Boot include a configuration option to disable caching (described later in this document). -If you use the `spring-boot-devtools` module, these properties are <> for you at development time. +If you use the `spring-boot-devtools` module, these properties are <> for you at development time. @@ -2416,7 +2416,7 @@ The `spring-boot-devtools` module includes support for automatic application res While not as fast as technologies such as https://www.jrebel.com/products/jrebel[JRebel] it is usually significantly faster than a "`cold start`". You should probably give it a try before investigating some of the more complex reload options discussed later in this document. -For more details, see the <> section. +For more details, see the <> section. @@ -2578,7 +2578,7 @@ If your application contains classes that you want to share with other projects, The separate module can then be depended upon by your application and other projects. If you cannot rearrange your code as recommended above, Spring Boot's Maven and Gradle plugins must be configured to produce a separate artifact that is suitable for use as a dependency. -The executable archive cannot be used as a dependency as the <> packages application classes in `BOOT-INF/classes`. +The executable archive cannot be used as a dependency as the <> packages application classes in `BOOT-INF/classes`. This means that they cannot be found when the executable jar is used as a dependency. To produce the two artifacts, one that can be used as a dependency and one that is executable, a classifier must be specified. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc index 234f8703a1..33bf951049 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc @@ -10,22 +10,22 @@ The reference documentation consists of the following sections: [horizontal] <> :: Legal information. -<> :: About the Documentation, Getting Help, First Steps, and more. +<> :: About the Documentation, Getting Help, First Steps, and more. <> :: Introducing Spring Boot, System Requirements, Servlet Containers, Installing Spring Boot, Developing Your First Spring Boot Application -<> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, DevTools, and more. -<> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. -<> :: Monitoring, Metrics, Auditing, and more. +<> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, DevTools, and more. +<> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. +<> :: Monitoring, Metrics, Auditing, and more. <> :: Deploying to the Cloud, Installing as a Unix application. -<> :: Installing the CLI, Using the CLI, Configuring the CLI, and more. +<> :: Installing the CLI, Using the CLI, Configuring the CLI, and more. <> :: Maven Plugin, Gradle Plugin, Antlib, and more. <> :: Application Development, Configuration, Embedded Servers, Data Access, and many more. The reference documentation has the following appendices: [horizontal] -<> :: Common application properties that can be used to configure your application. -<> :: Metadata used to describe configuration properties. -<> :: Auto-configuration classes provided by Spring Boot. -<> :: Test-autoconfiguration annotations used to test slices of your application. -<> :: Spring Boot's executable jars, their launchers, and their format. -<> :: Details of the dependencies that are managed by Spring Boot. +<> :: Common application properties that can be used to configure your application. +<> :: Metadata used to describe configuration properties. +<> :: Auto-configuration classes provided by Spring Boot. +<> :: Test-autoconfiguration annotations used to test slices of your application. +<> :: Spring Boot's executable jars, their launchers, and their format. +<> :: Details of the dependencies that are managed by Spring Boot. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc index 0dd8a6aa2e..cc25156720 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc @@ -7,13 +7,13 @@ include::attributes.adoc[] *{spring-boot-version}* include::legal.adoc[leveloffset=+1] -include::documentation-overview.adoc[leveloffset=+1] +include::documentation.adoc[leveloffset=+1] include::getting-started.adoc[leveloffset=+1] -include::using-spring-boot.adoc[leveloffset=+1] -include::spring-boot-features.adoc[leveloffset=+1] -include::production-ready-features.adoc[leveloffset=+1] +include::using.adoc[leveloffset=+1] +include::features.adoc[leveloffset=+1] +include::actuator.adoc[leveloffset=+1] include::deployment.adoc[leveloffset=+1] -include::spring-boot-cli.adoc[leveloffset=+1] +include::cli.adoc[leveloffset=+1] include::build-tool-plugins.adoc[leveloffset=+1] include::howto.adoc[leveloffset=+1] @@ -22,9 +22,9 @@ include::howto.adoc[leveloffset=+1] [[appendix]] == Appendices -include::appendix-application-properties.adoc[leveloffset=+2] -include::appendix-configuration-metadata.adoc[leveloffset=+2] -include::appendix-auto-configuration-classes.adoc[leveloffset=+2] -include::appendix-test-auto-configuration.adoc[leveloffset=+2] -include::appendix-executable-jar-format.adoc[leveloffset=+2] -include::appendix-dependency-versions.adoc[leveloffset=+2] +include::common-application-properties.adoc[leveloffset=+2] +include::configuration-metadata.adoc[leveloffset=+2] +include::auto-configuration-classes.adoc[leveloffset=+2] +include::test-auto-configuration.adoc[leveloffset=+2] +include::executable-jar.adoc[leveloffset=+2] +include::dependency-versions.adoc[leveloffset=+2] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-test-auto-configuration.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/test-auto-configuration.adoc similarity index 100% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-test-auto-configuration.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/test-auto-configuration.adoc diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc similarity index 99% rename from spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc rename to spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc index a57681dbb3..1dbb9728fa 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc @@ -143,7 +143,7 @@ The following application starters are provided by Spring Boot under the `org.sp .Spring Boot application starters include::starters/application-starters.adoc[] -In addition to the application starters, the following starters can be used to add _<>_ features: +In addition to the application starters, the following starters can be used to add _<>_ features: .Spring Boot production starters include::starters/production-starters.adoc[] @@ -811,7 +811,7 @@ This allows you to share the devtools global configuration with applications tha ==== Profiles are not supported in devtools properties/yaml files. -Any profiles activated in `.spring-boot-devtools.properties` will not affect the loading of <>. +Any profiles activated in `.spring-boot-devtools.properties` will not affect the loading of <>. Profile specific filenames (of the form `spring-boot-devtools-.properties`) and `spring.config.activate.on-profile` documents in both YAML and Properties files are not supported. ==== @@ -940,7 +940,7 @@ Executable jars can be used for production deployment. As they are self-contained, they are also ideally suited for cloud-based deployment. For additional "`production ready`" features, such as health, auditing, and metric REST or JMX end-points, consider adding `spring-boot-actuator`. -See _<>_ for details. +See _<>_ for details.