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 new file mode 100644 index 0000000000..266d34b0bf --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties @@ -0,0 +1,3107 @@ +# +# Migrations +# +#--------------------------------------------------- + + + + +# +# Spring Boot <= 2.4 Migrations +# +#--------------------------------------------------- + + + +# (index.adoc) +# 1 = Spring Boot Reference Documentation +spring-boot-reference-documentation=\ +index + + + +# (legal.adoc) +# 1 = Legal +legal=\ +legal + + + +# (documentation-overview.adoc) +# 1 = Spring Boot Documentation +boot-documentation=\ +documentation + +# 2 == About the Documentation +boot-documentation-about=\ +documentation.about + +# 2 == Getting Help +boot-documentation-getting-help=\ +documentation.getting-help + +# 2 == Upgrading From an Earlier Version +boot-documentation-upgrading=\ +documentation.upgrading + +# 2 == First Steps +boot-documentation-first-steps=\ +documentation.first-steps + +# 2 == Working with Spring Boot +boot-documentation-workingwith=\ +documentation.using + +# 2 == Learning About Spring Boot Features +boot-documentation-learning=\ +documentation.features + +# 2 == Moving to Production +boot-documentation-production=\ +documentation.actuator + +# 2 == Advanced Topics +boot-documentation-advanced=\ +documentation.advanced + + + +# (getting-started.adoc) +# 1 = Getting Started +getting-started=\ +getting-started + +# 2 == Introducing Spring Boot +getting-started-introducing-spring-boot=\ +getting-started.introducing-spring-boot + +# 2 == System Requirements +getting-started-system-requirements=\ +getting-started.system-requirements + +# 3 === Servlet Containers +getting-started-system-requirements-servlet-containers=\ +getting-started.system-requirements.servlet-containers + +# 2 == Installing Spring Boot +getting-started-installing-spring-boot=\ +getting-started.installing + +# 3 === Installation Instructions for the Java Developer +getting-started-installation-instructions-for-java=\ +getting-started.installing.java + +# 4 ==== Maven Installation +getting-started-maven-installation=\ +getting-started.installing.java.maven + +# 4 ==== Gradle Installation +getting-started-gradle-installation=\ +getting-started.installing.java.gradle + +# 3 === Installing the Spring Boot CLI +getting-started-installing-the-cli=\ +getting-started.installing.cli + +# 4 ==== Manual Installation +getting-started-manual-cli-installation=\ +getting-started.installing.cli.manual-installation + +# 4 ==== Installation with SDKMAN! +getting-started-sdkman-cli-installation=\ +getting-started.installing.cli.sdkman + +# 4 ==== OSX Homebrew Installation +getting-started-homebrew-cli-installation=\ +getting-started.installing.cli.homebrew + +# 4 ==== MacPorts Installation +getting-started-macports-cli-installation=\ +getting-started.installing.cli.macports + +# 4 ==== Command-line Completion +getting-started-cli-command-line-completion=\ +getting-started.installing.cli.completion + +# 4 ==== Windows Scoop Installation +getting-started-scoop-cli-installation=\ +getting-started.installing.scoop + +# 4 ==== Quick-start Spring CLI Example +getting-started-cli-example=\ +getting-started.installing.quick-start + +# 3 === Upgrading from an Earlier Version of Spring Boot +getting-started-upgrading-from-an-earlier-version=\ +getting-started.installing.upgrading + +# 2 == Developing Your First Spring Boot Application +getting-started-first-application=\ +getting-started.first-application + +# 3 === Creating the POM +getting-started-first-application-pom=\ +getting-started.first-application.pom + +# 3 === Adding Classpath Dependencies +getting-started-first-application-dependencies=\ +getting-started.first-application.dependencies + +# 3 === Writing the Code +getting-started-first-application-code=\ +getting-started.first-application.code + +# 4 ==== The @RestController and @RequestMapping Annotations +getting-started-first-application-annotations=\ +getting-started.first-application.code.mvc-annotations + +# 4 ==== The @EnableAutoConfiguration Annotation +getting-started-first-application-auto-configuration=\ +getting-started.first-application.code.enable-auto-configuration + +# 4 ==== The "`main`" Method +getting-started-first-application-main-method=\ +getting-started.first-application.code.main-method + +# 3 === Running the Example +getting-started-first-application-run=\ +getting-started.first-application.run + +# 3 === Creating an Executable Jar +getting-started-first-application-executable-jar=\ +getting-started.first-application.executable-jar + +# 2 == What to Read Next +getting-started-whats-next=\ +getting-started.whats=next + + + +# (using-spring-boot.adoc) +# 1 = Using Spring Boot +using-boot=\ +using + +# 2 == Build Systems +using-boot-build-systems=\ +using.build-systems + +# 3 === Dependency Management +using-boot-dependency-management=\ +using.build-systems.dependency-management + +# 3 === Maven +using-boot-maven=\ +using.build-systems.maven + +# 3 === Gradle +using-boot-gradle=\ +using.build-systems.gradle + +# 3 === Ant +using-boot-ant=\ +using.build-systems.ant + +# 3 === Starters +using-boot-starter=\ +using.build-systems.starters + +# 2 == Structuring Your Code +using-boot-structuring-your-code=\ +using.structuring-your-code + +# 3 === Using the "`default`" Package +using-boot-using-the-default-package=\ +using.structuring-your-code.using-the-default-package + +# 3 === Locating the Main Application Class +using-boot-locating-the-main-class=\ +using.structuring-your-code.locating-the-main-class + +# 2 == Configuration Classes +using-boot-configuration-classes=\ +using.configuration-classes + +# 3 === Importing Additional Configuration Classes +using-boot-importing-configuration=\ +using.configuration-classes.importing-additional-configuration + +# 3 === Importing XML Configuration +using-boot-importing-xml-configuration=\ +using.configuration-classes.importing-xml-configuration + +# 2 == Auto-configuration +using-boot-auto-configuration=\ +using.auto-configuration + +# 3 === Gradually Replacing Auto-configuration +using-boot-replacing-auto-configuration=\ +using.auto-configuration.replacing + +# 3 === Disabling Specific Auto-configuration Classes +using-boot-disabling-specific-auto-configuration=\ +using.auto-configuration.disabling-specific + +# 2 == Spring Beans and Dependency Injection +using-boot-spring-beans-and-dependency-injection=\ +using.spring-beans-and-dependency-injection + +# 2 == Using the @SpringBootApplication Annotation +using-boot-using-springbootapplication-annotation=\ +using.using-the-springbootapplication-annotation + +# 2 == Running Your Application +using-boot-running-your-application=\ +using.running-your-application + +# 3 === Running from an IDE +using-boot-running-from-an-ide=\ +using.running-your-application.from-an-ide + +# 3 === Running as a Packaged Application +using-boot-running-as-a-packaged-application=\ +using.running-your-application.as-a-packaged-application + +# 3 === Using the Maven Plugin +using-boot-running-with-the-maven-plugin=\ +using.running-your-application.with-the-maven-plugin + +# 3 === Using the Gradle Plugin +using-boot-running-with-the-gradle-plugin=\ +using.running-your-application.with-the-gradle-plugin + +# 3 === Hot Swapping +using-boot-hot-swapping=\ +using.running-your-application.hot-swapping + +# 2 == Developer Tools +using-boot-devtools=\ +using.devtools + +# 3 === Property Defaults +using-boot-devtools-property-defaults=\ +using.devtools.property-defaults + +# 3 === Automatic Restart +using-boot-devtools-restart=\ +using.devtools.restart + +# 4 ==== Logging changes in condition evaluation +using-boot-devtools-restart-logging-condition-delta=\ +using.devtools.restart.logging-condition-delta + +# 4 ==== Excluding Resources +using-boot-devtools-restart-exclude=\ +using.devtools.restart.excluding-resources + +# 4 ==== Watching Additional Paths +using-boot-devtools-restart-additional-paths=\ +using.devtools.restart.watching-additional-paths + +# 4 ==== Disabling Restart +using-boot-devtools-restart-disable=\ +using.devtools.restart.disable + +# 4 ==== Using a Trigger File +using-boot-devtools-restart-triggerfile=\ +using.devtools.restart.triggerfile + +# 4 ==== Customizing the Restart Classloader +using-boot-devtools-customizing-classload=\ +using.devtools.restart.customizing-the-classload + +# 4 ==== Known Limitations +using-boot-devtools-known-restart-limitations=\ +using.devtools.restart.limitations + +# 3 === LiveReload +using-boot-devtools-livereload=\ +using.devtools.livereload + +# 3 === Global Settings +using-boot-devtools-globalsettings=\ +using.devtools.globalsettings + +# 4 ==== Configuring File System Watcher +configuring-file-system-watcher=\ +using.devtools.globalsettings.configuring-file-system-watcher + +# 3 === Remote Applications +using-boot-devtools-remote=\ +using.devtools.remote-applications + +# 4 ==== Running the Remote Client Application +running-remote-client-application=\ +using.devtools.remote-applications.client + +# 4 ==== Remote Update +using-boot-devtools-remote-update=\ +using.devtools.remote-applications.update + +# 2 == Packaging Your Application for Production +using-boot-packaging-for-production=\ +using.packaging-for-production + +# 2 == What to Read Next +using-boot-whats-next=\ +using.whats-next + + + +# (spring-boot-features.adoc) +# 1 = Spring Boot Features +boot-features=\ +features + +# 2 == SpringApplication +boot-features-spring-application=\ +features.spring-application + +# 3 === Startup Failure +boot-features-startup-failure=\ +features.spring-application.startup-failure + +# 3 === Lazy Initialization +boot-features-lazy-initialization=\ +features.spring-application.lazy-initialization + +# 3 === Customizing the Banner +boot-features-banner=\ +features.spring-application.banner + +# 3 === Customizing SpringApplication +boot-features-customizing-spring-application=\ +features.spring-application.customizing-spring-application + +# 3 === Fluent Builder API +boot-features-fluent-builder-api=\ +features.spring-application.fluent-builder-api + +# 3 === Application Availability +boot-features-application-availability=\ +features.spring-application.application-availability + +# 4 ==== Liveness State +boot-features-application-availability-liveness-state=\ +features.spring-application.application-availability.liveness + +# 4 ==== Readiness State +boot-features-application-availability-readiness-state=\ +features.spring-application.application-availability.readiness + +# 4 ==== Managing the Application Availability State +boot-features-application-availability-managing=\ +features.spring-application.application-availability.managing + +# 3 === Application Events and Listeners +boot-features-application-events-and-listeners=\ +features.spring-application.application-events-and-listeners + +# 3 === Web Environment +boot-features-web-environment=\ +features.spring-application.web-environment + +# 3 === Accessing Application Arguments +boot-features-application-arguments=\ +features.spring-application.application-arguments + +# 3 === Using the ApplicationRunner or CommandLineRunner +boot-features-command-line-runner=\ +features.spring-application.command-line-runner + +# 3 === Application Exit +boot-features-application-exit=\ +features.spring-application.application-exit + +# 3 === Admin Features +boot-features-application-admin=\ +features.spring-application.admin + +# 3 === Application Startup tracking +boot-features-application-startup-tracking=\ +features.spring-application.startup-tracking + +# 2 == Externalized Configuration +boot-features-external-config=\ +features.external-config + +# 3 === Accessing Command Line Properties +boot-features-external-config-command-line-args=\ +features.external-config.command-line-args + +# 3 === JSON Application Properties +boot-features-external-config-application-json=\ +features.external-config.application-json + +# 3 === External Application Properties +boot-features-external-config-files=\ +features.external-config.files + +boot-features-external-config-application-property-files=\ +features.external-config.files + +# 4 ==== Optional Locations +boot-features-external-config-optional-prefix=\ +features.external-config.files.optional-prefix + +# 4 ==== Wildcard Locations +boot-features-external-config-files-wildcards=\ +features.external-config.files.wildcard-locations + +# 4 ==== Profile Specific Files +boot-features-external-config-files-profile-specific=\ +features.external-config.files.profile-specific + +# 4 ==== Importing Additional Data +boot-features-external-config-files-importing=\ +features.external-config.files.importing + +# 4 ==== Importing Extensionless Files +boot-features-external-config-files-importing-extensionless=\ +features.external-config.file.importing-extensionless + +# 4 ==== Using Configuration Trees +boot-features-external-config-files-configtree=\ +features.external-config.files.configtree + +# 4 ==== Property Placeholders +boot-features-external-config-placeholders-in-properties=\ +features.external-config.files.property-placeholders + +# 4 ==== Working with Multi-Document Files +boot-features-external-config-files-multi-document=\ +features.external-config.files.multi-document + +# 4 ==== Activation Properties +boot-features-external-config-file-activation-properties=\ +features.external-config.files.activation-properties + +# 3 === Encrypting Properties +boot-features-encrypting-properties=\ +features.external-config.encrypting + +# 3 === Working with YAML +boot-features-external-config-yaml=\ +features.external-config.yaml + +# 4 ==== Mapping YAML to Properties +boot-features-external-config-yaml-to-properties=\ +features.external-config.yaml.mapping-to-properties + +# 4 ==== Directly Loading YAML +boot-features-external-config-exposing-yaml-to-spring=\ +features.external-config.yaml.directly-loading + +boot-features-external-config-loading-yaml=\ +features.external-config.yaml.directly-loading + +# 3 === Configuring Random Values +boot-features-external-config-random-values=\ +features.external-config.random-values + +# 3 === Configuring System Environment Properties +boot-features-external-config-system-environment=\ +features.external-config.system-environment + +# 3 === Type-safe Configuration Properties +boot-features-external-config-typesafe-configuration-properties=\ +features.external-config.typesafe-configuration-properties + +# 4 ==== JavaBean properties binding +boot-features-external-config-java-bean-binding=\ +features.external-config.typesafe-configuration-properties.java-bean-binding + +# 4 ==== Constructor binding +boot-features-external-config-constructor-binding=\ +features.external-config.typesafe-configuration-properties.constructor-binding + +# 4 ==== Enabling @ConfigurationProperties-annotated types +boot-features-external-config-enabling=\ +features.external-config.typesafe-configuration-properties.enabling-annotated-types + +# 4 ==== Using @ConfigurationProperties-annotated types +boot-features-external-config-using=\ +features.external-config.typesafe-configuration-properties.using-annotated-types + +# 4 ==== Third-party Configuration +boot-features-external-config-3rd-party-configuration=\ +features.external-config.typesafe-configuration-properties.3rd-party-configuration + +# 4 ==== Relaxed Binding +boot-features-external-config-relaxed-binding=\ +features.external-config.typesafe-configuration-properties.relaxed-binding + +# 5 ===== Binding Maps +boot-features-external-config-relaxed-binding-maps=\ +features.external-config.typesafe-configuration-properties.relaxed-binding.maps + +# 5 ===== Binding from Environment Variables +boot-features-external-config-relaxed-binding-from-environment-variables=\ +features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables + +# 4 ==== Merging Complex Types +boot-features-external-config-complex-type-merge=\ +features.external-config.typesafe-configuration-properties.merging-complex-types + +# 4 ==== Properties Conversion +boot-features-external-config-conversion=\ +features.external-config.typesafe-configuration-properties.conversion + +# 5 ===== Converting Durations +boot-features-external-config-conversion-duration=\ +features.external-config.typesafe-configuration-properties.conversion.durations + +# 5 ===== Converting periods +boot-features-external-config-conversion-period=\ +features.external-config.typesafe-configuration-properties.conversion.periods + +# 5 ===== Converting Data Sizes +boot-features-external-config-conversion-datasize=\ +features.external-config.typesafe-configuration-properties.conversion.data-sizes + +# 4 ==== @ConfigurationProperties Validation +boot-features-external-config-validation=\ +features.external-config.typesafe-configuration-properties.validation + +# 4 ==== @ConfigurationProperties vs. @Value +boot-features-external-config-vs-value=\ +features.external-config.typesafe-configuration-properties.vs-value-annotation + +# 2 == Profiles +boot-features-profiles=\ +features.profiles + +# 3 === Adding Active Profiles +boot-features-adding-active-profiles=\ +features.profiles.adding-active-profiles + +# 3 === Profile Groups +boot-features-profiles-groups=\ +features.profiles.groups + +# 3 === Programmatically Setting Profiles +boot-features-programmatically-setting-profiles=\ +features.profiles.programmatically-setting-profiles + +# 3 === Profile-specific Configuration Files +boot-features-profile-specific-configuration=\ +features.profiles.profile-specific-configuration-files + +# 2 == Logging +boot-features-logging=\ +features.logging + +# 3 === Log Format +boot-features-logging-format=\ +features.logging.log-format + +# 3 === Console Output +boot-features-logging-console-output=\ +features.logging.console-output + +# 4 ==== Color-coded Output +boot-features-logging-color-coded-output=\ +features.logging.console-output.color-coded + +# 3 === File Output +boot-features-logging-file-output=\ +features.logging.file-output + +# 3 === File Rotation +boot-features-logging-file-rotation=\ +features.logging.file-rotation + +# 3 === Log Levels +boot-features-custom-log-levels=\ +features.logging.log-levels + +# 3 === Log Groups +boot-features-custom-log-groups=\ +features.logging.log-groups + +# 3 === Using a Log Shutdown Hook +boot-features-log-shutdown-hook=\ +features.logging.shutdown-hook + +# 3 === Custom Log Configuration +boot-features-custom-log-configuration=\ +features.logging.custom-log-configuration + +# 3 === Logback Extensions +boot-features-logback-extensions=\ +features.logging.logback-extensions + +# 4 ==== Profile-specific Configuration +boot-features-logback-extensions-profile-specific=\ +features.logging.logback-extensions.profile-specific + +# 4 ==== Environment Properties +boot-features-logback-environment-properties=\ +features.logging.logback-extensions.environment-properties + +# 2 == Internationalization +boot-features-internationalization=\ +features.internationalization + +# 2 == JSON +boot-features-json=\ +features.json + +# 3 === Jackson +boot-features-json-jackson=\ +features.json.jackson + +# 3 === Gson +boot-features-json-gson=\ +features.json.gson + +# 3 === JSON-B +boot-features-json-json-b=\ +features.json.json-b + +# 2 == Developing Web Applications +boot-features-developing-web-applications=\ +features.developing-web-applications + +# 3 === The "`Spring Web MVC Framework`" +boot-features-spring-mvc=\ +features.developing-web-applications.spring-mvc + +# 4 ==== Spring MVC Auto-configuration +boot-features-spring-mvc-auto-configuration=\ +features.developing-web-applications.spring-mvc.auto-configuration + +# 4 ==== HttpMessageConverters +boot-features-spring-mvc-message-converters=\ +features.developing-web-applications.spring-mvc.message-converters + +# 4 ==== Custom JSON Serializers and Deserializers +boot-features-json-components=\ +features.developing-web-applications.spring-mvc.json + +# 4 ==== MessageCodesResolver +boot-features-spring-message-codes=\ +features.developing-web-applications.spring-mvc.message-codes + +# 4 ==== Static Content +boot-features-spring-mvc-static-content=\ +features.developing-web-applications.spring-mvc.static-content + +# 4 ==== Welcome Page +boot-features-spring-mvc-welcome-page=\ +features.developing-web-applications.spring-mvc.welcome-page + +# 4 ==== Path Matching and Content Negotiation +boot-features-spring-mvc-pathmatch=\ +features.developing-web-applications.spring-mvc.content-negotiation + +# 4 ==== ConfigurableWebBindingInitializer +boot-features-spring-mvc-web-binding-initializer=\ +features.developing-web-applications.spring-mvc.binding-initializer + +# 4 ==== Template Engines +boot-features-spring-mvc-template-engines=\ +features.developing-web-applications.spring-mvc.template-engines + +# 4 ==== Error Handling +boot-features-error-handling=\ +features.developing-web-applications.spring-mvc.error-handling + +# 5 ===== Custom Error Pages +boot-features-error-handling-custom-error-pages=\ +features.developing-web-applications.spring-mvc.error-handling.error-pages + +# 5 ===== Mapping Error Pages outside of Spring MVC +boot-features-error-handling-mapping-error-pages-without-mvc=\ +features.developing-web-applications.spring-mvc.error-handling.error-pages-without-spring-mvc + +# 5 ===== Error handling in a war deployment +boot-features-error-handling-war-deployment=\ +features.developing-web-applications.spring-mvc.error-handling.in-a-war-deployment + +# 4 ==== Spring HATEOAS +boot-features-spring-hateoas=\ +features.developing-web-applications.spring-mvc.spring-hateoas + +# 4 ==== CORS Support +boot-features-cors=\ +features.developing-web-applications.spring-mvc.cors + +# 3 === The "`Spring WebFlux Framework`" +boot-features-webflux=\ +features.developing-web-applications.spring-webflux + +# 4 ==== Spring WebFlux Auto-configuration +boot-features-webflux-auto-configuration=\ +features.developing-web-applications.spring-webflux.auto-configuration + +# 4 ==== HTTP Codecs with HttpMessageReaders and HttpMessageWriters +boot-features-webflux-httpcodecs=\ +features.developing-web-applications.spring-webflux.httpcodecs + +# 4 ==== Static Content +boot-features-webflux-static-content=\ +features.developing-web-applications.spring-webflux.static-content + +# 4 ==== Welcome Page +boot-features-webflux-welcome-page=\ +features.developing-web-applications.spring-webflux.welcome-page + +# 4 ==== Template Engines +boot-features-webflux-template-engines=\ +features.developing-web-applications.spring-webflux.template-engines + +# 4 ==== Error Handling +boot-features-webflux-error-handling=\ +features.developing-web-applications.spring-webflux.error-handling + +# 5 ===== Custom Error Pages +boot-features-webflux-error-handling-custom-error-pages=\ +features.developing-web-applications.spring-webflux.error-handling.error-pages + +# 4 ==== Web Filters +boot-features-webflux-web-filters=\ +features.developing-web-applications.spring-webflux.web-filters + +# 3 === JAX-RS and Jersey +boot-features-jersey=\ +features.developing-web-applications.jersey + +# 3 === Embedded Servlet Container Support +boot-features-embedded-container=\ +features.developing-web-applications.embedded-container + +# 4 ==== Servlets, Filters, and listeners +boot-features-embedded-container-servlets-filters-listeners=\ +features.developing-web-applications.embedded-container.servlets-filters-listeners + +# 5 ===== Registering Servlets, Filters, and Listeners as Spring Beans +boot-features-embedded-container-servlets-filters-listeners-beans=\ +features.developing-web-applications.embedded-container.servlets-filters-listeners.beans + +# 4 ==== Servlet Context Initialization +boot-features-embedded-container-context-initializer=\ +features.developing-web-applications.embedded-container.context-initializer + +# 5 ===== Scanning for Servlets, Filters, and listeners +boot-features-embedded-container-servlets-filters-listeners-scanning=\ +features.developing-web-applications.embedded-container.context-initializer.scanning + +# 4 ==== The ServletWebServerApplicationContext +boot-features-embedded-container-application-context=\ +features.developing-web-applications.embedded-container.application-context + +# 4 ==== Customizing Embedded Servlet Containers +boot-features-customizing-embedded-containers=\ +features.developing-web-applications.embedded-container.customizing + +# 5 ===== Programmatic Customization +boot-features-programmatic-embedded-container-customization=\ +features.developing-web-applications.embedded-container.customizing.programmatic + +# 5 ===== Customizing ConfigurableServletWebServerFactory Directly +boot-features-customizing-configurableservletwebserverfactory-directly=\ +features.developing-web-applications.embedded-container.customizing.direct + +# 4 ==== JSP Limitations +boot-features-jsp-limitations=\ +features.developing-web-applications.embedded-container.jsp-limitations + +# 3 === Embedded Reactive Server Support +boot-features-reactive-server=\ +features.developing-web-applications.reactive-server + +# 3 === Reactive Server Resources Configuration +boot-features-reactive-server-resources=\ +features.developing-web-applications.reactive-server-resources-configuration + +# 2 == Graceful shutdown +boot-features-graceful-shutdown=\ +features.graceful-shutdown + +# 2 == RSocket +boot-features-rsocket=\ +features.rsocket + +# 3 === RSocket Strategies Auto-configuration +boot-features-rsocket-strategies-auto-configuration=\ +features.rsocket.strategies-auto-configuration + +# 3 === RSocket server Auto-configuration +boot-features-rsocket-server-auto-configuration=\ +features.rsocket.server-auto-configuration + +# 3 === Spring Messaging RSocket support +boot-features-rsocket-messaging=\ +features.rsocket.messaging + +# 3 === Calling RSocket Services with RSocketRequester +boot-features-rsocket-requester=\ +features.rsocket.requester + +# 2 == Security +boot-features-security=\ +features.security + +# 3 === MVC Security +boot-features-security-mvc=\ +features.security.spring-mvc + +# 3 === WebFlux Security +boot-features-security-webflux=\ +features.security.spring-webflux + +# 3 === OAuth2 +boot-features-security-oauth2=\ +features.security.oauth2 + +# 4 ==== Client +boot-features-security-oauth2-client=\ +features.security.oauth2.client + +# 5 ===== OAuth2 client registration for common providers +boot-features-security-oauth2-common-providers=\ +features.security.oauth2.client.common-providers + +# 4 ==== Resource Server +boot-features-security-oauth2-server=\ +features.security.oauth2.server + +# 4 ==== Authorization Server +boot-features-security-authorization-server=\ +features.security.oauth2.authorization-server + +# 3 === SAML 2.0 +boot-features-security-saml=\ +features.security.saml2 + +# 4 ==== Relying Party +boot-features-security-saml2-relying-party=\ +features.security.saml2.relying-party + +# 3 === Actuator Security +boot-features-security-actuator=\ +features.security.actuator + +# 4 ==== Cross Site Request Forgery Protection +boot-features-security-csrf=\ +features.security.actuator.csrf + +# 2 == Working with SQL Databases +boot-features-sql=\ +features.sql + +# 3 === Configure a DataSource +boot-features-configure-datasource=\ +features.sql.datasource + +# 4 ==== Embedded Database Support +boot-features-embedded-database-support=\ +features.sql.datasource.embedded + +# 4 ==== Connection to a Production Database +boot-features-connect-to-production-database=\ +features.sql.datasource.production + +# 4 ==== DataSource Configuration +boot-features-connect-to-production-database-configuration=\ +features.sql.datasource.configuration + +# 4 ==== Supported Connection Pools +boot-features-connect-to-production-database-connection-pool=\ +features.sql.datasource.connection-pool + +# 4 ==== Connection to a JNDI DataSource +boot-features-connecting-to-a-jndi-datasource=\ +features.sql.configure-datasource.jndi + +# 3 === Using JdbcTemplate +boot-features-using-jdbc-template=\ +features.sql.jdbc-template + +# 3 === JPA and Spring Data JPA +boot-features-jpa-and-spring-data=\ +features.sql.jpa-and-spring-data + +# 4 ==== Entity Classes +boot-features-entity-classes=\ +features.sql.jpa-and-spring-data.entity-classes + +# 4 ==== Spring Data JPA Repositories +boot-features-spring-data-jpa-repositories=\ +features.sql.jpa-and-spring-data.repositories + +# 4 ==== Creating and Dropping JPA Databases +boot-features-creating-and-dropping-jpa-databases=\ +features.sql.jpa-and-spring-data.creating-and-dropping + +# 4 ==== Open EntityManager in View +boot-features-jpa-in-web-environment=\ +features.sql.jpa-and-spring-data.open-entity-manager-in-view + +# 3 === Spring Data JDBC +boot-features-data-jdbc=\ +features.sql.jdbc + +# 3 === Using H2's Web Console +boot-features-sql-h2-console=\ +features.sql.h2-web-console + +# 4 ==== Changing the H2 Console's Path +boot-features-sql-h2-console-custom-path=\ +features.sql.h2-web-console.custom-path + +# 3 === Using jOOQ +boot-features-jooq=\ +features.sql.jooq + +# 4 ==== Code Generation +boot-features-jooq-codegen=\ +features.sql.jooq.codegen + +# 4 ==== Using DSLContext +boot-features-jooq-dslcontext=\ +features.sql.jooq.dslcontext + +# 4 ==== jOOQ SQL Dialect +boot-features-jooq-sqldialect=\ +features.sql.jooq.sqldialect + +# 4 ==== Customizing jOOQ +boot-features-jooq-customizing=\ +features.sql.jooq.customizing + +# 3 === Using R2DBC +boot-features-r2dbc=\ +features.sql.r2dbc + +# 4 ==== Embedded Database Support +boot-features-r2dbc-embedded-database=\ +features.sql.r2dbc.embedded + +# 4 ==== Using DatabaseClient +boot-features-r2dbc-using-database-client=\ +features.sql.r2dbc.using-database-client + +# 4 ==== Spring Data R2DBC Repositories +boot-features-spring-data-r2dbc-repositories=\ +features.sql.r2dbc.repositories + +# 2 == Working with NoSQL Technologies +boot-features-nosql=\ +features.nosql + +# 3 === Redis +boot-features-redis=\ +features.nosql.redis + +# 4 ==== Connecting to Redis +boot-features-connecting-to-redis=\ +features.nosql.redis.connecting + +# 3 === MongoDB +boot-features-mongodb=\ +features.nosql.mongodb + +# 4 ==== Connecting to a MongoDB Database +boot-features-connecting-to-mongodb=\ +features.nosql.mongodb.connecting + +# 4 ==== MongoTemplate +boot-features-mongo-template=\ +features.nosql.mongodb.template + +# 4 ==== Spring Data MongoDB Repositories +boot-features-spring-data-mongodb-repositories=\ +features.nosql.mongodb.repositories + +boot-features-spring-data-mongo-repositories=\ +features.nosql.mongodb.repositories + +# 4 ==== Embedded Mongo +boot-features-mongo-embedded=\ +features.nosql.mongodb.embedded + +# 3 === Neo4j +boot-features-neo4j=\ +features.nosql.neo4j + +# 4 ==== Connecting to a Neo4j Database +boot-features-connecting-to-neo4j=\ +features.nosql.neo4j.connecting + +# 4 ==== Spring Data Neo4j Repositories +boot-features-spring-data-neo4j-repositories=\ +features.nosql.neo4j.repositories + +# 3 === Solr +boot-features-solr=\ +features.nosql.solr + +# 4 ==== Connecting to Solr +boot-features-connecting-to-solr=\ +features.nosql.solr.connecting + +# 3 === Elasticsearch +boot-features-elasticsearch=\ +features.nosql.elasticsearch + +# 4 ==== Connecting to Elasticsearch using REST clients +boot-features-connecting-to-elasticsearch-rest=\ +features.nosql.elasticsearch.connecting-using-rest + +# 4 ==== Connecting to Elasticsearch using Reactive REST clients +boot-features-connecting-to-elasticsearch-reactive-rest=\ +features.nosql.elasticsearch.connecting-using-reactive-rest + +# 4 ==== Connecting to Elasticsearch by Using Spring Data +boot-features-connecting-to-elasticsearch-spring-data=\ +features.nosql.elasticsearch.connecting-using-spring-data + +# 4 ==== Spring Data Elasticsearch Repositories +boot-features-spring-data-elasticsearch-repositories=\ +features.nosql.elasticsearch.repositories + +# 3 === Cassandra +boot-features-cassandra=\ +features.nosql.cassandra + +# 4 ==== Connecting to Cassandra +boot-features-connecting-to-cassandra=\ +features.nosql.cassandra.connecting + +# 4 ==== Spring Data Cassandra Repositories +boot-features-spring-data-cassandra-repositories=\ +features.nosql.cassandra.repositories + +# 3 === Couchbase +boot-features-couchbase=\ +features.nosql.couchbase + +# 4 ==== Connecting to Couchbase +boot-features-connecting-to-couchbase=\ +features.nosql.couchbase.connecting + +# 4 ==== Spring Data Couchbase Repositories +boot-features-spring-data-couchbase-repositories=\ +features.nosql.couchbase.repositories + +# 3 === LDAP +boot-features-ldap=\ +features.nosql.ldap + +# 4 ==== Connecting to an LDAP Server +boot-features-ldap-connecting=\ +features.nosql.ldap.connecting + +# 4 ==== Spring Data LDAP Repositories +boot-features-ldap-spring-data-repositories=\ +features.nosql.ldap.repositories + +# 4 ==== Embedded In-memory LDAP Server +boot-features-ldap-embedded=\ +features.nosql.ldap.embedded + +# 3 === InfluxDB +boot-features-influxdb=\ +features.nosql.influxdb + +# 4 ==== Connecting to InfluxDB +boot-features-connecting-to-influxdb=\ +features.nosql.influxdb.connecting + +# 2 == Caching +boot-features-caching=\ +features.caching + +# 3 === Supported Cache Providers +boot-features-caching-provider=\ +features.caching.provider + +# 4 ==== Generic +boot-features-caching-provider-generic=\ +features.caching.provider.generic + +# 4 ==== JCache (JSR-107) +boot-features-caching-provider-jcache=\ +features.caching.provider.jcache + +# 4 ==== EhCache 2.x +boot-features-caching-provider-ehcache2=\ +features.caching.provider.ehcache2 + +# 4 ==== Hazelcast +boot-features-caching-provider-hazelcast=\ +features.caching.provider.hazelcast + +# 4 ==== Infinispan +boot-features-caching-provider-infinispan=\ +features.caching.provider.infinispan + +# 4 ==== Couchbase +boot-features-caching-provider-couchbase=\ +features.caching.provider.couchbase + +# 4 ==== Redis +boot-features-caching-provider-redis=\ +features.caching.provider.redis + +# 4 ==== Caffeine +boot-features-caching-provider-caffeine=\ +features.caching.provider.caffeine + +# 4 ==== Simple +boot-features-caching-provider-simple=\ +features.caching.provider.simple + +# 4 ==== None +boot-features-caching-provider-none=\ +features.caching.provider.none + +# 2 == Messaging +boot-features-messaging=\ +features.messaging + +# 3 === JMS +boot-features-jms=\ +features.messaging.jms + +# 4 ==== ActiveMQ Support +boot-features-activemq=\ +features.messaging.jms.activemq + +# 4 ==== ActiveMQ Artemis Support +boot-features-artemis=\ +features.messaging.jms.artemis + +# 4 ==== Using a JNDI ConnectionFactory +boot-features-jms-jndi=\ +features.messaging.jms.jndi + +# 4 ==== Sending a Message +boot-features-using-jms-sending=\ +features.messaging.jms.sending + +# 4 ==== Receiving a Message +boot-features-using-jms-receiving=\ +features.messaging.jms.receiving + +# 3 === AMQP +boot-features-amqp=\ +features.messaging.amqp + +# 4 ==== RabbitMQ support +boot-features-rabbitmq=\ +features.messaging.amqp.rabbitmq + +# 4 ==== Sending a Message +boot-features-using-amqp-sending=\ +features.messaging.amqp.sending + +# 4 ==== Receiving a Message +boot-features-using-amqp-receiving=\ +features.messaging.amqp.receiving + +# 3 === Apache Kafka Support +boot-features-kafka=\ +features.messaging.kafka + +# 4 ==== Sending a Message +boot-features-kafka-sending-a-message=\ +features.messaging.kafka.sending + +# 4 ==== Receiving a Message +boot-features-kafka-receiving-a-message=\ +features.messaging.kafka.receiving + +# 4 ==== Kafka Streams +boot-features-kafka-streams=\ +features.messaging.kafka.streams + +# 4 ==== Additional Kafka Properties +boot-features-kafka-extra-props=\ +features.messaging.kafka.additional-properties + +# 4 ==== Testing with Embedded Kafka +boot-features-embedded-kafka=\ +features.messaging.kafka.embedded + +# 2 == Calling REST Services with RestTemplate +boot-features-resttemplate=\ +features.resttemplate + +# 3 === RestTemplate Customization +boot-features-resttemplate-customization=\ +features.resttemplate.customization + +# 2 == Calling REST Services with WebClient +boot-features-webclient=\ +features.webclient + +# 3 === WebClient Runtime +boot-features-webclient-runtime=\ +features.webclient.runtime + +# 3 === WebClient Customization +boot-features-webclient-customization=\ +features.webclient.customization + +# 2 == Validation +boot-features-validation=\ +features.validation + +# 2 == Sending Email +boot-features-email=\ +features.email + +# 2 == Distributed Transactions with JTA +boot-features-jta=\ +features.jta + +# 3 === Using an Atomikos Transaction Manager +boot-features-jta-atomikos=\ +features.jta.atomikos + +# 3 === Using a Java EE Managed Transaction Manager +boot-features-jta-javaee=\ +features.jta.javaee + +# 3 === Mixing XA and Non-XA JMS Connections +boot-features-jta-mixed-jms=\ +features.jta.mixing-xa-and-non-xa-connections + +# 3 === Supporting an Alternative Embedded Transaction Manager +boot-features-jta-supporting-alternative-embedded=\ +features.jta.supporting-alternative-embedded-transaction-manager + +# 2 == Hazelcast +boot-features-hazelcast=\ +features.hazelcast + +# 2 == Quartz Scheduler +boot-features-quartz=\ +features.quartz + +# 2 == Task Execution and Scheduling +boot-features-task-execution-scheduling=\ +features.task-execution-and-scheduling + +# 2 == Spring Integration +boot-features-integration=\ +features.spring-integration + +# 2 == Spring Session +boot-features-session=\ +features.spring-session + +# 2 == Monitoring and Management over JMX +boot-features-jmx=\ +features.jmx + +# 2 == Testing +boot-features-testing=\ +features.testing + +# 3 === Test Scope Dependencies +boot-features-test-scope-dependencies=\ +features.testing.test-scope-dependencies + +# 3 === Testing Spring Applications +boot-features-testing-spring-applications=\ +features.testing.spring-applications + +# 3 === Testing Spring Boot Applications +boot-features-testing-spring-boot-applications=\ +features.testing.spring-boot-applications + +# 4 ==== Detecting Web Application Type +boot-features-testing-spring-boot-applications-detecting-web-app-type=\ +features.testing.spring-boot-applications.detecting-web-app-type + +# 4 ==== Detecting Test Configuration +boot-features-testing-spring-boot-applications-detecting-config=\ +features.testing.spring-boot-applications.detecting-configuration + +# 4 ==== Excluding Test Configuration +boot-features-testing-spring-boot-applications-excluding-config=\ +features.testing.spring-boot-applications.excluding-configuration + +# 4 ==== Using Application Arguments +boot-features-testing-spring-boot-application-arguments=\ +features.testing.spring-boot-applications.using-application-arguments + +# 4 ==== Testing with a mock environment +boot-features-testing-spring-boot-applications-testing-with-mock-environment=\ +features.testing.spring-boot-applications.with-mock-environment + +# 4 ==== Testing with a running server +boot-features-testing-spring-boot-applications-testing-with-running-server=\ +features.testing.spring-boot-applications.with-running-server + +# 4 ==== Customizing WebTestClient +boot-features-testing-spring-boot-applications-customizing-web-test-client=\ +features.testing.spring-boot-applications.customizing-web-test-client + +# 4 ==== Using JMX +boot-features-testing-spring-boot-applications-jmx=\ +features.testing.spring-boot-applications.jmx + +# 4 ==== Using Metrics +boot-features-testing-spring-boot-applications-metrics=\ +features.testing.spring-boot-applications.metrics + +# 4 ==== Mocking and Spying Beans +boot-features-testing-spring-boot-applications-mocking-beans=\ +features.testing.spring-boot-applications.mocking-beans + +# 4 ==== Auto-configured Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-tests=\ +features.testing.spring-boot-applications.autoconfigured-tests + +# 4 ==== Auto-configured JSON Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-json-tests=\ +features.testing.spring-boot-applications.json-tests + +# 4 ==== Auto-configured Spring MVC Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests=\ +features.testing.spring-boot-applications.spring-mvc-tests + +# 4 ==== Auto-configured Spring WebFlux Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-webflux-tests=\ +features.testing.spring-boot-applications.spring-webflux-tests + +# 4 ==== Auto-configured Data Cassandra Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-cassandra-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-cassandra + +# 4 ==== Auto-configured Data JPA Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-jpa + +# 4 ==== Auto-configured JDBC Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-jdbc-test=\ +features.testing.spring-boot-applications.autoconfigured-jdbc + +# 4 ==== Auto-configured Data JDBC Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-data-jdbc-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-jdbc + +# 4 ==== Auto-configured jOOQ Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-jooq-test=\ +features.testing.spring-boot-applications.autoconfigured-jooq + +# 4 ==== Auto-configured Data MongoDB Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-mongo-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-mongodb + +# 4 ==== Auto-configured Data Neo4j Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-neo4j-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-neo4j + +# 4 ==== Auto-configured Data Redis Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-redis-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-redis + +# 4 ==== Auto-configured Data LDAP Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-ldap-test=\ +features.testing.spring-boot-applications.autoconfigured-spring-data-ldap + +# 4 ==== Auto-configured REST Clients +boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-client=\ +features.testing.spring-boot-applications.autoconfigured-rest-client + +# 4 ==== Auto-configured Spring REST Docs Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs=\ +features.testing.spring-boot-applications.autoconfigured-spring-restdocs + +# 5 ===== Auto-configured Spring REST Docs Tests with Mock MVC +boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-mock-mvc=\ +features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-mock-mvc + +# 5 ===== Auto-configured Spring REST Docs Tests with WebTestClient +boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-web-test-client=\ +features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-web-test-client + +# 5 ===== Auto-configured Spring REST Docs Tests with REST Assured +boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-rest-assured=\ +features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-rest-assured + +# 4 ==== Auto-configured Spring Web Services Tests +boot-features-testing-spring-boot-applications-testing-autoconfigured-webservices=\ +features.testing.spring-boot-applications.autoconfigured-webservices + +# 4 ==== Additional Auto-configuration and Slicing +boot-features-testing-spring-boot-applications-testing-auto-configured-additional-auto-config=\ +features.testing.spring-boot-applications.additional-autoconfiguration-and-slicing + +# 4 ==== User Configuration and Slicing +boot-features-testing-spring-boot-applications-testing-user-configuration=\ +features.testing.spring-boot-applications.user-configuration-and-slicing + +# 4 ==== Using Spock to Test Spring Boot Applications +boot-features-testing-spring-boot-applications-with-spock=\ +features.testing.spring-boot-applications.spock + +# 3 === Test Utilities +boot-features-test-utilities=\ +features.testing.utilities + +# 4 ==== ConfigDataApplicationContextInitializer +boot-features-configfileapplicationcontextinitializer-test-utility=\ +features.testing.utilities.config-data-application-context-initializer + +# 4 ==== TestPropertyValues +boot-features-test-property-values=\ +features.testing.utilities.test-property-values + +# 4 ==== OutputCapture +boot-features-output-capture-test-utility=\ +features.testing.utilities.output-capture + +# 4 ==== TestRestTemplate +boot-features-rest-templates-test-utility=\ +features.testing.utilities.test-rest-template + +# 2 == WebSockets +boot-features-websockets=\ +features.websockets + +# 2 == Web Services +boot-features-webservices=\ +features.webservices + +# 3 === Calling Web Services with WebServiceTemplate +boot-features-webservices-template=\ +features.webservices.template + +# 2 == Creating Your Own Auto-configuration +boot-features-developing-auto-configuration=\ +features.developing-auto-configuration + +# 3 === Understanding Auto-configured Beans +boot-features-understanding-auto-configured-beans=\ +features.developing-auto-configuration.understanding-auto-configured-beans + +# 3 === Locating Auto-configuration Candidates +boot-features-locating-auto-configuration-candidates=\ +features.developing-auto-configuration.locating-auto-configuration-candidates + +# 3 === Condition Annotations +boot-features-condition-annotations=\ +features.developing-auto-configuration.condition-annotations + +# 4 ==== Class Conditions +boot-features-class-conditions=\ +features.developing-auto-configuration.condition-annotations.class-conditions + +# 4 ==== Bean Conditions +boot-features-bean-conditions=\ +features.developing-auto-configuration.condition-annotations.bean-conditions + +# 4 ==== Property Conditions +boot-features-property-conditions=\ +features.developing-auto-configuration.condition-annotations.property-conditions + +# 4 ==== Resource Conditions +boot-features-resource-conditions=\ +features.developing-auto-configuration.condition-annotations.resource-conditions + +# 4 ==== Web Application Conditions +boot-features-web-application-conditions=\ +features.developing-auto-configuration.condition-annotations.web-application-conditions + +# 4 ==== SpEL Expression Conditions +boot-features-spel-conditions=\ +features.developing-auto-configuration.condition-annotations.spel-conditions + +# 3 === Testing your Auto-configuration +boot-features-test-autoconfig=\ +features.developing-auto-configuration.testing + +# 4 ==== Simulating a Web Context +boot-features-test-autoconfig-simulating-web-context=\ +features.developing-auto-configuration.testing.simulating-a-web-context + +# 4 ==== Overriding the Classpath +boot-features-test-autoconfig-overriding-classpath=\ +features.developing-auto-configuration.testing.overriding-classpath + +# 3 === Creating Your Own Starter +boot-features-custom-starter=\ +features.developing-auto-configuration.custom-starter + +# 4 ==== Naming +boot-features-custom-starter-naming=\ +features.developing-auto-configuration.custom-starter.naming + +# 4 ==== Configuration keys +boot-features-custom-starter-configuration-keys=\ +features.developing-auto-configuration.custom-starter.configuration-keys + +# 4 ==== The "`autoconfigure`" Module +boot-features-custom-starter-module-autoconfigure=\ +features.developing-auto-configuration.custom-starter.autoconfigure-module + +# 4 ==== Starter Module +boot-features-custom-starter-module-starter=\ +features.developing-auto-configuration.custom-starter.starter-module + +# 2 == Kotlin support +boot-features-kotlin=\ +features.kotlin + +# 3 === Requirements +boot-features-kotlin-requirements=\ +features.kotlin.requirements + +# 3 === Null-safety +boot-features-kotlin-null-safety=\ +features.kotlin.null-safety + +# 3 === Kotlin API +boot-features-kotlin-api=\ +features.kotlin.api + +# 4 ==== runApplication +boot-features-kotlin-api-runapplication=\ +features.kotlin.api.?run-application + +# 4 ==== Extensions +boot-features-kotlin-api-extensions=\ +features.kotlin.api.extensions + +# 3 === Dependency management +boot-features-kotlin-dependency-management=\ +features.kotlin.dependency-management + +# 3 === @ConfigurationProperties +boot-features-kotlin-configuration-properties=\ +features.kotlin.configuration-properties + +# 3 === Testing +boot-features-kotlin-testing=\ +features.kotlin.testing + +# 3 === Resources +boot-features-kotlin-resources=\ +features.kotlin.resources + +# 4 ==== Further reading +boot-features-kotlin-resources-further-reading=\ +features.kotlin.resources.further-reading + +# 4 ==== Examples +boot-features-kotlin-resources-examples=\ +features.kotlin.resources.examples + +# 2 == Container Images +boot-features-container-images=\ +features.container-images + +# 3 === Layering Docker Images +boot-layering-docker-images=\ +features.container-images.layering + +# 3 === Building Container Images +boot-features-container-images-building=\ +features.container-images.building + +# 4 ==== Dockerfiles +boot-features-container-images-docker=\ +features.container-images.building.dockerfiles + +# 4 ==== Cloud Native Buildpacks +boot-features-container-images-buildpacks=\ +features.container-images.images.buildpacks + +# 2 == What to Read Next +boot-features-whats-next=\ +features.whats-next + + + +# (production-ready-features.adoc) +# 1 = Spring Boot Actuator: Production-ready Features +production-ready=\ +actuator + +# 2 == Enabling Production-ready Features +production-ready-enabling=\ +actuator.enabling + +# 2 == Endpoints +production-ready-endpoints=\ +actuator.endpoints + +# 3 === Enabling Endpoints +production-ready-endpoints-enabling-endpoints=\ +actuator.endpoints.enabling + +# 3 === Exposing Endpoints +production-ready-endpoints-exposing-endpoints=\ +actuator.endpoints.exposing + +# 3 === Securing HTTP Endpoints +production-ready-endpoints-security=\ +actuator.endpoints.security + +# 3 === Configuring Endpoints +production-ready-endpoints-caching=\ +actuator.endpoints.caching + +# 3 === Hypermedia for Actuator Web Endpoints +production-ready-endpoints-hypermedia=\ +actuator.endpoints.hypermedia + +# 3 === CORS Support +production-ready-endpoints-cors=\ +actuator.endpoints.cors + +# 3 === Implementing Custom Endpoints +production-ready-endpoints-custom=\ +actuator.endpoints.implementing-custom + +# 4 ==== Receiving Input +production-ready-endpoints-custom-input=\ +actuator.endpoints.implementing-custom.input + +# 5 ===== Input Type Conversion +production-ready-endpoints-custom-input-conversion=\ +actuator.endpoints.implementing-custom.input.conversion + +# 4 ==== Custom Web Endpoints +production-ready-endpoints-custom-web=\ +actuator.endpoints.implementing-custom.web + +# 5 ===== Web Endpoint Request Predicates +production-ready-endpoints-custom-web-predicate=\ +actuator.endpoints.implementing-custom.web.request-predicates + +# 5 ===== Path +production-ready-endpoints-custom-web-predicate-path=\ +actuator.endpoints.implementing-custom.web.path-predicates + +# 5 ===== HTTP method +production-ready-endpoints-custom-web-predicate-http-method=\ +actuator.endpoints.implementing-custom.web.method-predicates + +# 5 ===== Consumes +production-ready-endpoints-custom-web-predicate-consumes=\ +actuator.endpoints.implementing-custom.web.consumes-predicates + +# 5 ===== Produces +production-ready-endpoints-custom-web-predicate-produces=\ +actuator.endpoints.implementing-custom.web.produces-predicates + +# 5 ===== Web Endpoint Response Status +production-ready-endpoints-custom-web-response-status=\ +actuator.endpoints.implementing-custom.web.response-status + +# 5 ===== Web Endpoint Range Requests +production-ready-endpoints-custom-web-range-requests=\ +actuator.endpoints.implementing-custom.web.range-requests + +# 5 ===== Web Endpoint Security +production-ready-endpoints-custom-web-security=\ +actuator.endpoints.implementing-custom.web.security + +# 4 ==== Servlet Endpoints +production-ready-endpoints-custom-servlet=\ +actuator.endpoints.implementing-custom.servlet + +# 4 ==== Controller Endpoints +production-ready-endpoints-custom-controller=\ +actuator.endpoints.implementing-custom.controller + +# 3 === Health Information +production-ready-health=\ +actuator.endpoints.health + +# 4 ==== Auto-configured HealthIndicators +production-ready-health-indicators=\ +actuator.endpoints.health.auto-configured-health-indicators + +# 4 ==== Writing Custom HealthIndicators +production-ready-health-indicators-writing=\ +actuator.endpoints.health.writing-custom-health-indicators + +# 4 ==== Reactive Health Indicators +reactive-health-indicators=\ +actuator.endpoints.health.reactive-health-indicators + +# 4 ==== Auto-configured ReactiveHealthIndicators +reactive-health-indicators-autoconfigured=\ +actuator.endpoints.health.auto-configured-reactive-health-indicators + +# 4 ==== Health Groups +production-ready-health-groups=\ +actuator.endpoints.health.groups + +# 4 ==== DataSource Health +production-ready-health-datasource=\ +actuator.endpoints.health.datasource + +# 3 === Kubernetes Probes +production-ready-kubernetes-probes=\ +actuator.endpoints.kubernetes-probes + +# 4 ==== Checking External State with Kubernetes Probes +production-ready-kubernetes-probes-external-state=\ +actuator.endpoints.kubernetes-probes.external-state + +# 4 ==== Application Lifecycle and Probe States +production-ready-kubernetes-probes-lifecycle=\ +actuator.endpoints.kubernetes-probes.lifecycle + +# 3 === Application Information +production-ready-application-info=\ +actuator.endpoints.info + +# 4 ==== Auto-configured InfoContributors +production-ready-application-info-autoconfigure=\ +actuator.endpoints.info.auto-configured-info-contributors + +# 4 ==== Custom Application Information +production-ready-application-info-env=\ +actuator.endpoints.info.custom-application-information + +# 4 ==== Git Commit Information +production-ready-application-info-git=\ +actuator.endpoints.info.git-commit-information + +# 4 ==== Build Information +production-ready-application-info-build=\ +actuator.endpoints.info.build-information + +# 4 ==== Writing Custom InfoContributors +production-ready-application-info-custom=\ +actuator.endpoints.info.writing-custom-info-contributors + +# 2 == Monitoring and Management over HTTP +production-ready-monitoring=\ +actuator.monitoring + +# 3 === Customizing the Management Endpoint Paths +production-ready-customizing-management-server-context-path=\ +actuator.monitoring.customizing-management-server-context-path + +# 3 === Customizing the Management Server Port +production-ready-customizing-management-server-port=\ +actuator.monitoring.customizing-management-server-port + +# 3 === Configuring Management-specific SSL +production-ready-management-specific-ssl=\ +actuator.monitoring.management-specific-ssl + +# 3 === Customizing the Management Server Address +production-ready-customizing-management-server-address=\ +actuator.monitoring.customizing-management-server-address + +# 3 === Disabling HTTP Endpoints +production-ready-disabling-http-endpoints=\ +actuator.monitoring.disabling-http-endpoints + +# 2 == Monitoring and Management over JMX +production-ready-jmx=\ +actuator.jmx + +# 3 === Customizing MBean Names +production-ready-custom-mbean-names=\ +actuator.jmx.custom-mbean-names + +# 3 === Disabling JMX Endpoints +production-ready-disable-jmx-endpoints=\ +actuator.jmx.disable-jmx-endpoints + +# 3 === Using Jolokia for JMX over HTTP +production-ready-jolokia=\ +actuator.jmx.jolokia + +# 4 ==== Customizing Jolokia +production-ready-customizing-jolokia=\ +actuator.jmx.jolokia.customizing + +# 4 ==== Disabling Jolokia +production-ready-disabling-jolokia=\ +actuator.jmx.jolokia.disabling + +# 2 == Loggers +production-ready-loggers=\ +actuator.loggers + +# 3 === Configure a Logger +production-ready-logger-configuration=\ +actuator.loggers.configure + +# 2 == Metrics +production-ready-metrics=\ +actuator.metrics + +# 3 === Getting started +production-ready-metrics-getting-started=\ +actuator.metrics.getting-started + +# 3 === Supported Monitoring Systems +production-ready-metrics-export=\ +actuator.metrics.export + +# 4 ==== AppOptics +production-ready-metrics-export-appoptics=\ +actuator.metrics.export.appoptics + +# 4 ==== Atlas +production-ready-metrics-export-atlas=\ +actuator.metrics.export.atlas + +# 4 ==== Datadog +production-ready-metrics-export-datadog=\ +actuator.metrics.export.datadog + +# 4 ==== Dynatrace +production-ready-metrics-export-dynatrace=\ +actuator.metrics.export.dynatrace + +# 4 ==== Elastic +production-ready-metrics-export-elastic=\ +actuator.metrics.export.elastic + +# 4 ==== Ganglia +production-ready-metrics-export-ganglia=\ +actuator.metrics.export.ganglia + +# 4 ==== Graphite +production-ready-metrics-export-graphite=\ +actuator.metrics.export.graphite + +# 4 ==== Humio +production-ready-metrics-export-humio=\ +actuator.metrics.export.humio + +# 4 ==== Influx +production-ready-metrics-export-influx=\ +actuator.metrics.export.influx + +# 4 ==== JMX +production-ready-metrics-export-jmx=\ +actuator.metrics.export.jmx + +# 4 ==== KairosDB +production-ready-metrics-export-kairos=\ +actuator.metrics.export.kairos + +# 4 ==== New Relic +production-ready-metrics-export-newrelic=\ +actuator.metrics.export.newrelic + +# 4 ==== Prometheus +production-ready-metrics-export-prometheus=\ +actuator.metrics.export.prometheus + +# 4 ==== SignalFx +production-ready-metrics-export-signalfx=\ +actuator.metrics.export.signalfx + +# 4 ==== Simple +production-ready-metrics-export-simple=\ +actuator.metrics.export.simple + +# 4 ==== Stackdriver +production-ready-metrics-export-stackdriver=\ +actuator.metrics.export.stackdriver + +# 4 ==== StatsD +production-ready-metrics-export-statsd=\ +actuator.metrics.export.statsd + +# 4 ==== Wavefront +production-ready-metrics-export-wavefront=\ +actuator.metrics.export.wavefront + +# 3 === Supported Metrics and Meters +production-ready-metrics-meter=\ +actuator.metrics.supported + +# 4 ==== JVM Metrics +production-ready-metrics-jvm=\ +actuator.metrics.supported.jvm + +# 4 ==== System Metrics +production-ready-metrics-system=\ +actuator.metrics.supported.system + +# 4 ==== Logger Metrics +production-ready-metrics-logger=\ +actuator.metrics.supported.logger + +# 4 ==== Spring MVC Metrics +production-ready-metrics-spring-mvc=\ +actuator.metrics.supported.spring-mvc + +# 4 ==== Spring WebFlux Metrics +production-ready-metrics-web-flux=\ +actuator.metrics.supported.spring-webflux + +# 4 ==== Jersey Server Metrics +production-ready-metrics-jersey-server=\ +actuator.metrics.supported.jersey + +# 4 ==== HTTP Client Metrics +production-ready-metrics-http-clients=\ +actuator.metrics.supported.http-clients + +# 4 ==== Tomcat Metrics +production-ready-metrics-tomcat=\ +actuator.metrics.supported.tomcat + +# 4 ==== Cache Metrics +production-ready-metrics-cache=\ +actuator.metrics.supported.cache + +# 4 ==== DataSource Metrics +production-ready-metrics-jdbc=\ +actuator.metrics.supported.jdbc + +# 4 ==== Hibernate Metrics +production-ready-metrics-hibernate=\ +actuator.metrics.supported.hibernate + +# 4 ==== Spring Data Repository Metrics +production-ready-metrics-data-repository=\ +actuator.metrics.supported.spring-data-repository + +# 4 ==== RabbitMQ Metrics +production-ready-metrics-rabbitmq=\ +actuator.metrics.supported.rabbitmq + +# 4 ==== Spring Integration Metrics +production-ready-metrics-integration=\ +actuator.metrics.supported.spring-integration + +# 4 ==== Kafka Metrics +production-ready-metrics-kafka=\ +actuator.metrics.supported.kafka + +# 4 ==== MongoDB Metrics +production-ready-metrics-mongodb=\ +actuator.metrics.supported.mongodb + +# 5 ===== Command Metrics +production-ready-metrics-mongodb-command=\ +actuator.metrics.supported.mongodb.command + +# 5 ===== Connection Pool Metrics +production-ready-metrics-mongodb-connectionpool=\ +actuator.metrics.supported.mongodb.connection-pool + +# 4 ==== @Timed Annotation Support +production-ready-metrics-timed-annotation=\ +actuator.metrics.supported.timed-annotation + +# 3 === Registering Custom Metrics +production-ready-metrics-custom=\ +actuator.metrics.registering-custom + +# 3 === Customizing Individual Metrics +production-ready-metrics-customizing=\ +actuator.metrics.customizing + +# 4 ==== Common Tags +production-ready-metrics-common-tags=\ +actuator.metrics.customizing.common-tags + +# 4 ==== Per-meter Properties +production-ready-metrics-per-meter-properties=\ +actuator.metrics.customizing.per-meter-properties + +# 3 === Metrics Endpoint +production-ready-metrics-endpoint=\ +actuator.metrics.endpoint + +# 2 == Auditing +production-ready-auditing=\ +actuator.auditing + +# 3 === Custom Auditing +production-ready-auditing-custom=\ +actuator.auditing.custom + +# 2 == HTTP Tracing +production-ready-http-tracing=\ +actuator.tracing + +# 3 === Custom HTTP tracing +production-ready-http-tracing-custom=\ +actuator.tracing.custom + +# 2 == Process Monitoring +production-ready-process-monitoring=\ +actuator.process-monitoring + +# 3 === Extending Configuration +production-ready-process-monitoring-configuration=\ +actuator.process-monitoring.configuration + +# 3 === Programmatically +production-ready-process-monitoring-programmatically=\ +actuator.process-monitoring.programmatically + +# 2 == Cloud Foundry Support +production-ready-cloudfoundry=\ +actuator.cloud-foundry + +# 3 === Disabling Extended Cloud Foundry Actuator Support +production-ready-cloudfoundry-disable=\ +actuator.cloud-foundry.disable + +# 3 === Cloud Foundry Self-signed Certificates +production-ready-cloudfoundry-ssl=\ +actuator.cloud-foundry.ssl + +# 3 === Custom Context Path +production-ready-custom-context-path=\ +actuator.cloud-foundry.custom-context-path + +# 2 == What to Read Next +production-ready-whats-next=\ +actuator.whats-next + + + +# (deployment.adoc) +# 1 = Deploying Spring Boot Applications +deployment=\ +deployment + +# 2 == Deploying to Containers +containers-deployment=\ +deployment.containers + +# 2 == Deploying to the Cloud +cloud-deployment=\ +deployment.cloud + +# 3 === Cloud Foundry +cloud-deployment-cloud-foundry=\ +deployment.cloud.cloud-foundry + +# 4 ==== Binding to Services +cloud-deployment-cloud-foundry-services=\ +deployment.cloud.cloud-foundry.binding-to-services + +# 3 === Kubernetes +cloud-deployment-kubernetes=\ +deployment.cloud.kubernetes + +# 4 ==== Kubernetes Container Lifecycle +cloud-deployment-kubernetes-container-lifecycle=\ +deployment.cloud.kubernetes.container-lifecycle + +# 3 === Heroku +cloud-deployment-heroku=\ +deployment.cloud.heroku + +# 3 === OpenShift +cloud-deployment-openshift=\ +deployment.cloud.openshift + +# 3 === Amazon Web Services (AWS) +cloud-deployment-aws=\ +deployment.cloud.aws + +# 4 ==== AWS Elastic Beanstalk +cloud-deployment-aws-beanstalk=\ +deployment.cloud.aws.beanstalk + +# 5 ===== Using the Tomcat Platform +cloud-deployment-aws-tomcat-platform=\ +deployment.cloud.aws.beanstalk.tomcat-platform + +# 5 ===== Using the Java SE Platform +cloud-deployment-aws-java-se-platform=\ +deployment.cloud.aws.beanstalk.java-se-platform + +# 4 ==== Summary +cloud-deployment-aws-summary=\ +deployment.cloud.aws.summary + +# 3 === Boxfuse and Amazon Web Services +cloud-deployment-boxfuse=\ +deployment.cloud.boxfuse + +# 3 === Google Cloud +cloud-deployment-gae=\ +deployment.cloud.google + +# 2 == Installing Spring Boot Applications +deployment-install=\ +deployment.installing + +# 3 === Supported Operating Systems +deployment-install-supported-operating-systems=\ +deployment.installing.supported-operating-systems + +# 3 === Unix/Linux Services +deployment-service=\ +deployment.installing.nix-services + +# 4 ==== Installation as an init.d Service (System V) +deployment-initd-service=\ +deployment.installing.nix-services.init-d + +# 5 ===== Securing an init.d Service +deployment-initd-service-securing=\ +deployment.installing.nix-services.init-d.securing + +# 4 ==== Installation as a systemd Service +deployment-systemd-service=\ +deployment.installing.nix-services.system-d + +# 4 ==== Customizing the Startup Script +deployment-script-customization=\ +deployment.installing.nix-services.script-customization + +# 5 ===== Customizing the Start Script When It Is Written +deployment-script-customization-when-it-written=\ +deployment.installing.nix-services.script-customization.when-written + +# 5 ===== Customizing a Script When It Runs +deployment-script-customization-when-it-runs=\ +deployment.installing.nix-services.script-customization.when-running + +# 3 === Microsoft Windows Services +deployment-windows=\ +deployment.installing.windows-services + +# 2 == What to Read Next +deployment-whats-next=\ +deployment.whats-next + + + +# (spring-boot-cli.adoc) +# 1 = Spring Boot CLI +cli=\ +cli + +# 2 == Installing the CLI +cli-installation=\ +cli.installation + +# 2 == Using the CLI +cli-using-the-cli=\ +cli.using-the-cli + +# 3 === Running Applications with the CLI +cli-run=\ +cli.using-the-cli.run + +# 4 ==== Deduced "`grab`" Dependencies +cli-deduced-grab-annotations=\ +cli.using-the-cli.run.deduced-grab-annotations + +# 4 ==== Deduced "`grab`" Coordinates +cli-default-grab-deduced-coordinates=\ +cli.using-the-cli.run.deduced-grab-coordinates + +# 4 ==== Default Import Statements +cli-default-import-statements=\ +cli.using-the-cli.run.default-import-statements + +# 4 ==== Automatic Main Method +cli-automatic-main-method=\ +cli.using-the-cli.run.automatic-main-method + +# 4 ==== Custom Dependency Management +cli-default-grab-deduced-coordinates-custom-dependency-management=\ +cli.using-the-cli.run.custom-dependency-management + +# 3 === Applications with Multiple Source Files +cli-multiple-source-files=\ +cli.using-the-cli.multiple-source-files + +# 3 === Packaging Your Application +cli-jar=\ +cli.using-the-cli.packaging + +# 3 === Initialize a New Project +cli-init=\ +cli.using-the-cli.initialize-new-project + +# 3 === Using the Embedded Shell +cli-shell=\ +cli.using-the-cli.embedded-shell + +# 3 === Adding Extensions to the CLI +cli-install-uninstall=\ +cli.using-the-cli.extensions + +# 2 == Developing Applications with the Groovy Beans DSL +cli-groovy-beans-dsl=\ +cli.groovy-beans-dsl + +# 2 == Configuring the CLI with settings.xml +cli-maven-settings=\ +cli.maven-setting + +# 2 == What to Read Next +cli-whats-next=\ +cli.whats-next + + + +# (build-tool-plugins.adoc) +# 1 = Build Tool Plugins +build-tool-plugins=\ +build-tool-plugins + +# 2 == Spring Boot Maven Plugin +build-tool-plugins-maven-plugin=\ +build-tool-plugins.maven + +# 2 == Spring Boot Gradle Plugin +build-tool-plugins-gradle-plugin=\ +build-tool-plugins.gradle + +# 2 == Spring Boot AntLib Module +build-tool-plugins-antlib=\ +build-tool-plugins.antlib + +# 3 === Spring Boot Ant Tasks +spring-boot-ant-tasks=\ +build-tool-plugins.antlib.tasks + +# 4 ==== Using the "`exejar`" Task +spring-boot-ant-exejar=\ +build-tool-plugins.antlib.tasks.exejar + +# 4 ==== Examples +spring-boot-ant-exejar-examples=\ +build-tool-plugins.antlib.tasks.examples + +# 3 === Using the "`findmainclass`" Task +spring-boot-ant-findmainclass=\ +build-tool-plugins.antlib.findmainclass + +# 4 ==== Examples +spring-boot-ant-findmainclass-examples=\ +build-tool-plugins.antlib.findmainclass.examples + +# 2 == Supporting Other Build Systems +build-tool-plugins-other-build-systems=\ +build-tool-plugins.other-build-systems + +# 3 === Repackaging Archives +build-tool-plugins-repackaging-archives=\ +build-tool-plugins.other-build-systems.repackaging-archives + +# 3 === Nested Libraries +build-tool-plugins-nested-libraries=\ +build-tool-plugins.other-build-systems.nested-libraries + +# 3 === Finding a Main Class +build-tool-plugins-find-a-main-class=\ +build-tool-plugins.other-build-systems.finding-main-class + +# 3 === Example Repackage Implementation +build-tool-plugins-repackage-implementation=\ +build-tool-plugins.other-build-systems.example-repackage-implementation + +# 2 == What to Read Next +build-tool-plugins-whats-next=\ +build-tool-plugins.whats-next + + + +# (howto.adoc) +# 1 = "`How-to`" Guides +howto=\ +howto + +# 2 == Spring Boot Application +howto-spring-boot-application=\ +howto.application + +# 3 === Create Your Own FailureAnalyzer +howto-failure-analyzer=\ +howto.application.failure-analyzer + +# 3 === Troubleshoot Auto-configuration +howto-troubleshoot-auto-configuration=\ +howto.application.troubleshoot-auto-configuration + +# 3 === Customize the Environment or ApplicationContext Before It Starts +howto-customize-the-environment-or-application-context=\ +howto.application.customize-the-environment-or-application-context + +# 3 === Build an ApplicationContext Hierarchy (Adding a Parent or Root Context) +howto-build-an-application-context-hierarchy=\ +howto.application.context-hierarchy + +# 3 === Create a Non-web Application +howto-create-a-non-web-application=\ +howto.application.non-web-application + +# 2 == Properties and Configuration +howto-properties-and-configuration=\ +howto.properties-and-configuration + +# 3 === Automatically Expand Properties at Build Time +howto-automatic-expansion=\ +howto.properties-and-configuration.expand-properties + +# 4 ==== Automatic Property Expansion Using Maven +howto-automatic-expansion-maven=\ +howto.properties-and-configuration.expand-properties.maven + +# 4 ==== Automatic Property Expansion Using Gradle +howto-automatic-expansion-gradle=\ +howto.properties-and-configuration.expand-properties.gradle + +# 3 === Externalize the Configuration of SpringApplication +howto-externalize-configuration=\ +howto.properties-and-configuration.externalize-configuration + +# 3 === Change the Location of External Properties of an Application +howto-change-the-location-of-external-properties=\ +howto.properties-and-configuration.external-properties-location + +# 3 === Use '`Short`' Command Line Arguments +howto-use-short-command-line-arguments=\ +howto.properties-and-configuration.short-command-line-arguments + +# 3 === Use YAML for External Properties +howto-use-yaml-for-external-properties=\ +howto.properties-and-configuration.yaml + +# 3 === Set the Active Spring Profiles +howto-set-active-spring-profiles=\ +howto.properties-and-configuration.set-active-spring-profiles + +# 3 === Change Configuration Depending on the Environment +howto-change-configuration-depending-on-the-environment=\ +howto.properties-and-configuration.change-configuration-depending-on-the-environment + +# 3 === Discover Built-in Options for External Properties +howto-discover-build-in-options-for-external-properties=\ +howto.properties-and-configuration.discover-build-in-options-for-external-properties + +# 2 == Embedded Web Servers +howto-embedded-web-servers=\ +howto.webserver + +# 3 === Use Another Web Server +howto-use-another-web-server=\ +howto.webserver.use-another + +# 3 === Disabling the Web Server +howto-disable-web-server=\ +howto.webserver.disable + +# 3 === Change the HTTP Port +howto-change-the-http-port=\ +howto.webserver.change-port + +# 3 === Use a Random Unassigned HTTP Port +howto-user-a-random-unassigned-http-port=\ +howto.webserver.use-random-port + +# 3 === Discover the HTTP Port at Runtime +howto-discover-the-http-port-at-runtime=\ +howto.webserver.discover-port + +# 3 === Enable HTTP Response Compression +how-to-enable-http-response-compression=\ +howto.webserver.enable-response-compression + +# 3 === Configure SSL +howto-configure-ssl=\ +howto.webserver.configure-ssl + +# 3 === Configure HTTP/2 +howto-configure-http2=\ +howto.webserver.configure-http2 + +# 4 ==== HTTP/2 with Tomcat +howto-configure-http2-tomcat=\ +howto.webserver.configure-http2.tomcat + +# 4 ==== HTTP/2 with Jetty +howto-configure-http2-jetty=\ +howto.webserver.configure-http2.jetty + +# 4 ==== HTTP/2 with Reactor Netty +howto-configure-http2-netty=\ +howto.webserver.configure-http2.netty + +# 4 ==== HTTP/2 with Undertow +howto-configure-http2-undertow=\ +howto.webserver.configure-http2.undertow + +# 3 === Configure the Web Server +howto-configure-webserver=\ +howto.webserver.configure + +# 3 === Add a Servlet, Filter, or Listener to an Application +howto-add-a-servlet-filter-or-listener=\ +howto.webserver.add-servlet-filter-listener + +# 4 ==== Add a Servlet, Filter, or Listener by Using a Spring Bean +howto-add-a-servlet-filter-or-listener-as-spring-bean=\ +howto.webserver.add-servlet-filter-listener.spring-bean + +# 5 ===== Disable Registration of a Servlet or Filter +howto-disable-registration-of-a-servlet-or-filter=\ +howto.webserver.add-servlet-filter-listener.spring-bean.disable + +# 4 ==== Add Servlets, Filters, and Listeners by Using Classpath Scanning +howto-add-a-servlet-filter-or-listener-using-scanning=\ +howto.webserver.add-servlet-filter-listener.using-scanning + +# 3 === Configure Access Logging +howto-configure-accesslogs=\ +howto.webserver.configure-access-logs + +# 3 === Running Behind a Front-end Proxy Server +howto-use-behind-a-proxy-server=\ +howto.webserver.use-behind-a-proxy-server + +# 4 ==== Customize Tomcat's Proxy Configuration +howto-customize-tomcat-behind-a-proxy-server=\ +howto.webserver.use-behind-a-proxy-server.tomcat + +# 3 === Enable Multiple Connectors with Tomcat +howto-enable-multiple-connectors-in-tomcat=\ +howto.webserver.enable-multiple-connectors-in-tomcat + +# 3 === Use Tomcat's LegacyCookieProcessor +howto-use-tomcat-legacycookieprocessor=\ +howto.webserver.use-tomcat-legacycookieprocessor + +# 3 === Enable Tomcat's MBean Registry +howto-enable-tomcat-mbean-registry=\ +howto.webserver.enable-tomcat-mbean-registry + +# 3 === Enable Multiple Listeners with Undertow +howto-enable-multiple-listeners-in-undertow=\ +howto.webserver.enable-multiple-listeners-in-undertow + +# 3 === Create WebSocket Endpoints Using @ServerEndpoint +howto-create-websocket-endpoints-using-serverendpoint=\ +howto.webserver.create-websocket-endpoints-using-serverendpoint + +# 2 == Spring MVC +howto-spring-mvc=\ +howto.spring-mvc + +# 3 === Write a JSON REST Service +howto-write-a-json-rest-service=\ +howto.spring-mvc.write-json-rest-service + +# 3 === Write an XML REST Service +howto-write-an-xml-rest-service=\ +howto.spring-mvc.write-xml-rest-service + +# 3 === Customize the Jackson ObjectMapper +howto-customize-the-jackson-objectmapper=\ +howto.spring-mvc.customize-jackson-objectmapper + +# 3 === Customize the @ResponseBody Rendering +howto-customize-the-responsebody-rendering=\ +howtospring-mvc.customize-responsebody-rendering + +# 3 === Handling Multipart File Uploads +howto-multipart-file-upload-configuration=\ +howto.spring-mvc.multipart-file-uploads + +# 3 === Switch Off the Spring MVC DispatcherServlet +howto-switch-off-the-spring-mvc-dispatcherservlet=\ +howto.spring-mvc.switch-off-dispatcherservlet + +# 3 === Switch off the Default MVC Configuration +howto-switch-off-default-mvc-configuration=\ +howto.spring-mvc.switch-off-default-configuration + +# 3 === Customize ViewResolvers +howto-customize-view-resolvers=\ +howto.spring-mvc.customize-view-resolvers + +# 2 == Testing With Spring Security +howto-use-test-with-spring-security=\ +howto.testing-with-spring-security + +# 2 == Jersey +howto-jersey=\ +howto.jersey + +# 3 === Secure Jersey endpoints with Spring Security +howto-jersey-spring-security=\ +howto.jersey.spring-security + +# 3 === Use Jersey Alongside Another Web Framework +howto-jersey-alongside-another-web-framework=\ +howto.jersey.alongside-another-web-framework + +# 2 == HTTP Clients +howto-http-clients=\ +howto.http-clients + +# 3 === Configure RestTemplate to Use a Proxy +howto-http-clients-proxy-configuration=\ +howto.http-clients.rest-template-proxy-configuration + +# 3 === Configure the TcpClient used by a Reactor Netty-based WebClient +howto-webclient-reactor-netty-customization=\ +howto.http-clients.webclient-reactor-netty-customization + +# 2 == Logging +howto-logging=\ +howto.logging + +# 3 === Configure Logback for Logging +howto-configure-logback-for-logging=\ +howto.logging.logback + +# 4 ==== Configure Logback for File-only Output +howto-configure-logback-for-logging-fileonly=\ +howto.logging.logback.file-only-output + +# 3 === Configure Log4j for Logging +howto-configure-log4j-for-logging=\ +howto.logging.log4j + +# 4 ==== Use YAML or JSON to Configure Log4j 2 +howto-configure-log4j-for-logging-yaml-or-json-config=\ +howto.logging.log4j.yaml-or-json-config + +# 2 == Data Access +howto-data-access=\ +howto.data-access + +# 3 === Configure a Custom DataSource +howto-configure-a-datasource=\ +howto.data-access.configure-custom-datasource + +# 3 === Configure Two DataSources +howto-two-datasources=\ +howto.data-access.configure-two-datasources + +# 3 === Use Spring Data Repositories +howto-use-spring-data-repositories=\ +howto.data-access.spring-data-repositories + +# 3 === Separate @Entity Definitions from Spring Configuration +howto-separate-entity-definitions-from-spring-configuration=\ +howto.data-access.separate-entity-definitions-from-spring-configuration + +# 3 === Configure JPA Properties +howto-configure-jpa-properties=\ +howto.data-access.jpa-properties + +# 3 === Configure Hibernate Naming Strategy +howto-configure-hibernate-naming-strategy=\ +howto.data-access.configure-hibernate-naming-strategy + +# 3 === Configure Hibernate Second-Level Caching +howto-configure-hibernate-second-level-caching=\ +howto.data-access.configure-hibernate-second-level-caching + +# 3 === Use Dependency Injection in Hibernate Components +howto-use-dependency-injection-hibernate-components=\ +howto.data-access.dependency-injection-in-hibernate-components + +# 3 === Use a Custom EntityManagerFactory +howto-use-custom-entity-manager=\ +howto.data-access.use-custom-entity-manager + +# 3 === Using Multiple EntityManagerFactories +howto-use-multiple-entity-managers=\ +howto.data-access.use-multiple-entity-managers + +howto-use-two-entity-managers=\ +howto.data-access.use-multiple-entity-managers + +# 3 === Use a Traditional persistence.xml File +howto-use-traditional-persistence-xml=\ +howto.data-access.use-traditional-persistence-xml + +# 3 === Use Spring Data JPA and Mongo Repositories +howto-use-spring-data-jpa--and-mongo-repositories=\ +howto.data-access.use-spring-data-jpa-and-mongo-repositories + +# 3 === Customize Spring Data's Web Support +howto-use-customize-spring-datas-web-support=\ +howto.data-access.customize-spring-data-web-support + +# 3 === Expose Spring Data Repositories as REST Endpoint +howto-use-exposing-spring-data-repositories-rest-endpoint=\ +howto.data-access.exposing-spring-data-repositories-as-rest + +# 3 === Configure a Component that is Used by JPA +howto-configure-a-component-that-is-used-by-JPA=\ +howto.data-access.configure-a-component-that-is-used-by-jpa + +# 3 === Configure jOOQ with Two DataSources +howto-configure-jOOQ-with-multiple-datasources=\ +howto.data-access.configure-jooq-with-multiple-datasources + +# 2 == Database Initialization +howto-database-initialization=\ +howto.data-initialization + +# 3 === Initialize a Database Using JPA +howto-initialize-a-database-using-jpa=\ +howto.data-initialization.using-jpa + +# 3 === Initialize a Database Using Hibernate +howto-initialize-a-database-using-hibernate=\ +howto.data-initialization.using-hibernate + +# 3 === Initialize a Database Using Basic SQL Scripts +howto-initialize-a-database-using-basic-scripts=\ +howto.data-initialization.using-basic-sql-scripts + +# 3 === Initialize a Spring Batch Database +howto-initialize-a-spring-batch-database=\ +howto.data-initialization.batch + +# 3 === Use a Higher-level Database Migration Tool +howto-use-a-higher-level-database-migration-tool=\ +howto.data-initialization.migration-tool + +# 4 ==== Execute Flyway Database Migrations on Startup +howto-execute-flyway-database-migrations-on-startup=\ +howto.data-initialization.migration-tool.flyway + +# 4 ==== Execute Liquibase Database Migrations on Startup +howto-execute-liquibase-database-migrations-on-startup=\ +howto.data-initialization.migration-tool.liquibase + +# 3 === Depend Upon an Initialized Database +howto-initialize-a-database-configuring-dependencies=\ +howto.data-initialization.dependencies + +# 4 ==== Detect a Database Initializer +howto-initialize-a-database-configuring-dependencies-initializer-detection=\ +howto.data-initialization.dependencies.initializer-detection + +# 4 ==== Detect a Bean That Depends On Database Initialization +howto-initialize-a-database-configuring-dependencies-depends-on-initialization-detection=\ +howto.data-initialization.dependencies.depends-on-initialization-detection + +# 2 == Messaging +howto-messaging=\ +howto.messaging + +# 3 === Disable Transacted JMS Session +howto-jms-disable-transaction=\ +howto.messaging.disable-transacted-jms-session + +# 2 == Batch Applications +howto-batch-applications=\ +howto.batch + +# 3 === Specifying a Batch Data Source +howto-spring-batch-specifying-a-data-source=\ +howto.batch.specifying-a-data-source + +# 3 === Running Spring Batch Jobs on Startup +howto-spring-batch-running-jobs-on-startup=\ +howto.batch.running-jobs-on-startup + +# 3 === Running from the Command Line +howto-spring-batch-running-command-line=\ +howto.batch.?running-from-the-command-line + +# 3 === Storing the Job Repository +howto-spring-batch-storing-job-repository=\ +howto.batch.storing-job-repository + +# 2 == Actuator +howto-actuator=\ +howto.actuator + +# 3 === Change the HTTP Port or Address of the Actuator Endpoints +howto-change-the-http-port-or-address-of-the-actuator-endpoints=\ +howto.actuator.change-http-port-or-address + +# 3 === Customize the '`whitelabel`' Error Page +howto-customize-the-whitelabel-error-page=\ +howto.actuator.customize-whitelabel-error-page + +# 3 === Sanitize Sensitive Values +howto-sanitize-sensitive-values=\ +howto.actuator.sanitize-sensitive-values + +howto-sanitize-sensible-values=\ +howto.actuator.sanitize-sensitive-values + +# 3 === Map Health Indicators to Micrometer Metrics +howto-map-health-indicators-to-metrics=\ +howto.actuator.map-health-indicators-to-metrics + +# 2 == Security +howto-security=\ +howto.security + +# 3 === Switch off the Spring Boot Security Configuration +howto-switch-off-spring-boot-security-configuration=\ +howto.security.switch-off-spring-boot-configuration + +# 3 === Change the UserDetailsService and Add User Accounts +howto-change-the-user-details-service-and-add-user-accounts=\ +howto.security.change-user-details-service-and-add-user-accounts + +# 3 === Enable HTTPS When Running behind a Proxy Server +howto-enable-https=\ +howto.security.enable-https + +# 2 == Hot Swapping +howto-hotswapping=\ +howto.hotswapping + +# 3 === Reload Static Content +howto-reload-static-content=\ +howto.hotswapping.reload-static-content + +# 3 === Reload Templates without Restarting the Container +howto-reload-thymeleaf-template-content=\ +howto.hotswapping.reload-templates + +# 4 ==== Thymeleaf Templates +howto-reload-thymeleaf-content=\ +howto.hotswapping.reload-templates.thymeleaf + +# 4 ==== FreeMarker Templates +howto-reload-freemarker-content=\ +howto.hotswapping.reload-templates.freemarker + +# 4 ==== Groovy Templates +howto-reload-groovy-template-content=\ +howto.hotswapping.reload-templates.groovy + +# 3 === Fast Application Restarts +howto-reload-fast-restart=\ +howto.hotswapping.fast-application-restarts + +# 3 === Reload Java Classes without Restarting the Container +howto-reload-java-classes-without-restarting=\ +howto.hotswapping.reload-java-classes-without-restarting + +# 2 == Build +howto-build=\ +howto.build + +# 3 === Generate Build Information +howto-build-info=\ +howto.build.generate-info + +# 3 === Generate Git Information +howto-git-info=\ +howto.build.generate-git-info + +# 3 === Customize Dependency Versions +howto-customize-dependency-versions=\ +howto.build.customize-dependency-versions + +# 3 === Create an Executable JAR with Maven +howto-create-an-executable-jar-with-maven=\ +howto.build.create-an-executable-jar-with-maven + +# 3 === Use a Spring Boot Application as a Dependency +howto-create-an-additional-executable-jar=\ +howto.build.use-a-spring-boot-application-as-dependency + +# 3 === Extract Specific Libraries When an Executable Jar Runs +howto-extract-specific-libraries-when-an-executable-jar-runs=\ +howto.build.extract-specific-libraries-when-an-executable-jar-runs + +# 3 === Create a Non-executable JAR with Exclusions +howto-create-a-nonexecutable-jar=\ +howto.build.create-a-nonexecutable-jar + +# 3 === Remote Debug a Spring Boot Application Started with Maven +howto-remote-debug-maven-run=\ +howto.build.remote-debug-maven + +# 3 === Build an Executable Archive from Ant without Using spring-boot-antlib +howto-build-an-executable-archive-with-ant=\ +howto.build.build-an-executable-archive-with-ant-without-using-spring-boot-antlib + +# 2 == Traditional Deployment +howto-traditional-deployment=\ +howto.traditional-deployment + +# 3 === Create a Deployable War File +howto-create-a-deployable-war-file=\ +howto.howto.traditional-deployment.war + +# 3 === Convert an Existing Application to Spring Boot +howto-convert-an-existing-application-to-spring-boot=\ +howto.howto.traditional-deployment.convert-existing-application + +# 3 === Deploying a WAR to WebLogic +howto-weblogic=\ +howto.howto.traditional-deployment.weblogic + +# 3 === Use Jedis Instead of Lettuce +howto-use-jedis-instead-of-lettuce=\ +howto.howto.traditional-deployment.jedis-instead-of-lettuce + +# 3 === Use Testcontainers for integration testing +howto-testcontainers=\ +howto.howto.traditional-deployment.testcontainers + + + +# (appendix-application-properties.adoc) +# 1 = Common Application properties +common-application-properties=\ +common-application-properties + +# 2 == Core Properties [[core-properties]] +common-application-properties-core=\ +common-application-properties.core + +# 2 == Cache Properties [[cache-properties]] +common-application-properties-cache=\ +common-application-properties.cache + +# 2 == Mail Properties [[mail-properties]] +common-application-properties-mail=\ +common-application-properties.mail + +# 2 == JSON Properties [[json-properties]] +common-application-properties-json=\ +common-application-properties.json + +# 2 == Data Properties [[data-properties]] +common-application-properties-data=\ +common-application-properties.data + +# 2 == Transaction Properties [[transaction-properties]] +common-application-properties-transaction=\ +common-application-properties.transaction + +# 2 == Data Migration Properties [[data-migration-properties]] +common-application-properties-data-migration=\ +common-application-properties.data-migration + +# 2 == Integration Properties [[integration-properties]] +common-application-properties-integration=\ +common-application-properties.integration + +# 2 == Web Properties [[web-properties]] +common-application-properties-web=\ +common-application-properties.web + +# 2 == Templating Properties [[templating-properties]] +common-application-properties-templating=\ +common-application-properties.templating + +# 2 == Server Properties [[server-properties]] +common-application-properties-server=\ +common-application-properties.server + +# 2 == Security Properties [[security-properties]] +common-application-properties-security=\ +common-application-properties.security + +# 2 == RSocket Properties [[rsocket-properties]] +common-application-properties-rsocket=\ +common-application-properties.rsocket + +# 2 == Actuator Properties [[actuator-properties]] +common-application-properties-actuator=\ +common-application-properties.actuator + +# 2 == Devtools Properties [[devtools-properties]] +common-application-properties-devtools=\ +common-application-properties.devtools + +# 2 == Testing Properties [[testing-properties]] +common-application-properties-testing=\ +common-application-properties.testing + + + +# (appendix-configuration-metadata.adoc) +# 1 = Configuration Metadata +configuration-metadata=\ +configuration-metadata + +# 2 == Metadata Format +configuration-metadata-format=\ +configuration-metadata.format + +# 3 === Group Attributes +configuration-metadata-group-attributes=\ +configuration-metadata.format.group + +# 3 === Property Attributes +configuration-metadata-property-attributes=\ +configuration-metadata.format.property + +# 3 === Hint Attributes +configuration-metadata-hints-attributes=\ +configuration-metadata.format.hints + +# 3 === Repeated Metadata Items +configuration-metadata-repeated-items=\ +configuration-metadata.format.repeated-items + +# 2 == Providing Manual Hints +configuration-metadata-providing-manual-hints=\ +configuration-metadata.manual-hints + +# 3 === Value Hint +configuration-metadata-providing-manual-hints-value-hint=\ +configuration-metadata.manual-hints.value-hint + +# 3 === Value Providers +configuration-metadata-providing-manual-hints-value-providers=\ +configuration-metadata.manual-hints.value-providers + +# 4 ==== Any +configuration-metadata-providing-manual-hints-any=\ +configuration-metadata.manual-hints.value-providers.any + +# 4 ==== Class Reference +configuration-metadata-providing-manual-hints-class-reference=\ +configuration-metadata.manual-hints.value-providers.class-reference + +# 4 ==== Handle As +configuration-metadata-providing-manual-hints-handle-as=\ +configuration-metadata.manual-hints.value-providers.handle-as + +# 4 ==== Logger Name +configuration-metadata-providing-manual-hints-logger-name=\ +configuration-metadata.manual-hints.value-providers.logger-name + +# 4 ==== Spring Bean Reference +configuration-metadata-providing-manual-hints-spring-bean-reference=\ +configuration-metadata.manual-hints.value-providers.spring-bean-reference + +# 4 ==== Spring Profile Name +configuration-metadata-providing-manual-hints-spring-profile-name=\ +configuration-metadata.manual-hints.value-providers.spring-profile-name + +# 2 == Generating Your Own Metadata by Using the Annotation Processor +configuration-metadata-annotation-processor=\ +configuration-metadata.annotation-processor + +# 3 === Configuring the Annotation Processor +configuration-metadata-annotation-processor-setup=\ +configuration-metadata.annotation-processor.configuring + +# 3 === Automatic Metadata Generation +configuration-metadata-annotation-processor-metadata-generation=\ +configuration-metadata.annotation-processor.automatic-metadata-generation + +# 4 ==== Nested Properties +configuration-metadata-annotation-processor-metadata-generation-nested=\ +configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties + +# 3 === Adding Additional Metadata +configuration-metadata-additional-metadata=\ +configuration-metadata.annotation-processor.adding-additional-metadata + + + +# (appendix-auto-configuration-classes.adoc) +# 1 = Auto-configuration Classes +auto-configuration-classes=\ +auto-configuration-classes + +# 2 == spring-boot-autoconfigure +auto-configuration-classes-from-autoconfigure-module=\ +auto-configuration-classes.core + +# 2 == spring-boot-actuator-autoconfigure +auto-configuration-classes-from-actuator=\ +auto-configuration-classes.actuator + + + +# (appendix-test-auto-configuration.adoc) +# 1 = Test Auto-configuration Annotations +test-auto-configuration=\ +test-auto-configuration + +# 2 == Test Slices +test-auto-configuration-slices=\ +test-auto-configuration.slices + + + +# (appendix-executable-jar-format.adoc) +# 1 = The Executable Jar Format +executable-jar=\ +executable-jar + +# 2 == Nested JARs +executable-jar-nested-jars=\ +executable-jar.nested-jars + +# 3 === The Executable Jar File Structure +executable-jar-jar-file-structure=\ +executable-jar.nested-jars.jar-structure + +# 3 === The Executable War File Structure +executable-jar-war-file-structure=\ +executable-jar.nested-jars.war-structure + +# 3 === Index Files +executable-jar-war-index-files=\ +executable-jar.nested-jars.index-files + +# 3 === Classpath Index +executable-jar-war-index-files-classpath=\ +executable-jar.nested-jars.classpath-index + +# 3 === Layer Index +executable-jar-war-index-files-layers=\ +executable-jar.nested-jars.layer-index + +# 2 == Spring Boot's "`JarFile`" Class +executable-jar-jarfile=\ +executable-jar.jarfile-class + +# 3 === Compatibility with the Standard Java "`JarFile`" +executable-jar-jarfile-compatibility=\ +executable-jar.jarfile-class.compatibilty + +# 2 == Launching Executable Jars +executable-jar-launching=\ +executable-jar.launching + +# 3 === Launcher Manifest +executable-jar-launcher-manifest=\ +executable-jar.launching.manifest + +# 2 == PropertiesLauncher Features +executable-jar-property-launcher-features=\ +executable-jar.property-launcher + +# 2 == Executable Jar Restrictions +executable-jar-restrictions=\ +executable-jar.restrictions + +# 2 == Alternative Single Jar Solutions +executable-jar-alternatives=\ +executable-jar.alternatives + + + +# (appendix-dependency-versions.adoc) +# 1 = Dependency versions +dependency-versions=\ +dependency-versions + +# 2 == Managed Dependency Coordinates +dependency-versions-coordinates=\ +dependency-versions.coordinates + +# 2 == Version Properties +dependency-versions-properties=\ +dependency-versions.properties + 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/appendix-application-properties.adoc index 723ff99ad5..9e23f3228a 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/appendix-application-properties.adoc @@ -7,103 +7,103 @@ 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. -[[common-application-properties-core]] +[[common-application-properties.core]] == Core Properties [[core-properties]] include::config-docs/core.adoc[] -[[common-application-properties-cache]] +[[common-application-properties.cache]] == Cache Properties [[cache-properties]] include::config-docs/cache.adoc[] -[[common-application-properties-mail]] +[[common-application-properties.mail]] == Mail Properties [[mail-properties]] include::config-docs/mail.adoc[] -[[common-application-properties-json]] +[[common-application-properties.json]] == JSON Properties [[json-properties]] include::config-docs/json.adoc[] -[[common-application-properties-data]] +[[common-application-properties.data]] == Data Properties [[data-properties]] include::config-docs/data.adoc[] -[[common-application-properties-transaction]] +[[common-application-properties.transaction]] == Transaction Properties [[transaction-properties]] include::config-docs/transaction.adoc[] -[[common-application-properties-data-migration]] +[[common-application-properties.data-migration]] == Data Migration Properties [[data-migration-properties]] include::config-docs/data-migration.adoc[] -[[common-application-properties-integration]] +[[common-application-properties.integration]] == Integration Properties [[integration-properties]] include::config-docs/integration.adoc[] -[[common-application-properties-web]] +[[common-application-properties.web]] == Web Properties [[web-properties]] include::config-docs/web.adoc[] -[[common-application-properties-templating]] +[[common-application-properties.templating]] == Templating Properties [[templating-properties]] include::config-docs/templating.adoc[] -[[common-application-properties-server]] +[[common-application-properties.server]] == Server Properties [[server-properties]] include::config-docs/server.adoc[] -[[common-application-properties-security]] +[[common-application-properties.security]] == Security Properties [[security-properties]] include::config-docs/security.adoc[] -[[common-application-properties-rsocket]] +[[common-application-properties.rsocket]] == RSocket Properties [[rsocket-properties]] include::config-docs/rsocket.adoc[] -[[common-application-properties-actuator]] +[[common-application-properties.actuator]] == Actuator Properties [[actuator-properties]] include::config-docs/actuator.adoc[] -[[common-application-properties-devtools]] +[[common-application-properties.devtools]] == Devtools Properties [[devtools-properties]] include::config-docs/devtools.adoc[] -[[common-application-properties-testing]] +[[common-application-properties.testing]] == Testing Properties [[testing-properties]] include::config-docs/testing.adoc[] 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/appendix-auto-configuration-classes.adoc index 0c004b0ad6..ac61000f28 100644 --- 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/appendix-auto-configuration-classes.adoc @@ -9,7 +9,7 @@ Remember to also look at the conditions report in your application for more deta -[[auto-configuration-classes-from-autoconfigure-module]] +[[auto-configuration-classes.core]] == spring-boot-autoconfigure The following auto-configuration classes are from the `spring-boot-autoconfigure` module: @@ -17,7 +17,7 @@ include::auto-configuration-classes/spring-boot-autoconfigure.adoc[] -[[auto-configuration-classes-from-actuator]] +[[auto-configuration-classes.actuator]] == spring-boot-actuator-autoconfigure The following auto-configuration classes are from the `spring-boot-actuator-autoconfigure` module: 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/appendix-configuration-metadata.adoc index 6a37e69ea7..9deb6574f8 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/appendix-configuration-metadata.adoc @@ -7,11 +7,11 @@ Spring Boot jars include metadata files that provide details of all supported co The files are designed to let IDE developers offer contextual help and "`code completion`" as users are working with `application.properties` or `application.yml` files. The majority of the metadata file is generated automatically at compile time by processing all items annotated with `@ConfigurationProperties`. -However, it is possible to <> for corner cases or more advanced use cases. +However, it is possible to <> for corner cases or more advanced use cases. -[[configuration-metadata-format]] +[[configuration-metadata.format]] == Metadata Format Configuration metadata files are located inside jars under `META-INF/spring-configuration-metadata.json`. They use a JSON format with items categorized under either "`groups`" or "`properties`" and additional values hints categorized under "hints", as shown in the following example: @@ -98,7 +98,7 @@ For example, when a developer is configuring the configprop:spring.jpa.hibernate -[[configuration-metadata-group-attributes]] +[[configuration-metadata.format.group]] === Group Attributes The JSON object contained in the `groups` array can contain the attributes shown in the following table: @@ -139,7 +139,7 @@ The JSON object contained in the `groups` array can contain the attributes shown -[[configuration-metadata-property-attributes]] +[[configuration-metadata.format.property]] === Property Attributes The JSON object contained in the `properties` array can contain the attributes described in the following table: @@ -254,7 +254,7 @@ Doing so is particularly useful when a `replacement` is provided. -[[configuration-metadata-hints-attributes]] +[[configuration-metadata.format.hints]] === Hint Attributes The JSON object contained in the `hints` array can contain the attributes shown in the following table: @@ -317,7 +317,7 @@ The JSON object contained in the `providers` attribute of each `hint` element ca -[[configuration-metadata-repeated-items]] +[[configuration-metadata.format.repeated-items]] === Repeated Metadata Items Objects with the same "`property`" and "`group`" name can appear multiple times within a metadata file. For example, you could bind two separate classes to the same prefix, with each having potentially overlapping property names. @@ -325,7 +325,7 @@ While the same names appearing in the metadata multiple times should not be comm -[[configuration-metadata-providing-manual-hints]] +[[configuration-metadata.manual-hints]] == Providing Manual Hints To improve the user experience and further assist the user in configuring a given property, you can provide additional metadata that: @@ -334,10 +334,10 @@ To improve the user experience and further assist the user in configuring a give -[[configuration-metadata-providing-manual-hints-value-hint]] +[[configuration-metadata.manual-hints.value-hint]] === Value Hint The `name` attribute of each hint refers to the `name` of a property. -In the <>, we provide five values for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`, and `create-drop`. +In the <>, we provide five values for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`, and `create-drop`. Each value may have a description as well. If your property is of type `Map`, you can provide hints for both the keys and the values (but not for the map itself). @@ -356,7 +356,7 @@ Assume a `sample.contexts` maps magic `String` values to an integer, as shown in ---- The magic values are (in this example) are `sample1` and `sample2`. -In order to offer additional content assistance for the keys, you could add the following JSON to <>: +In order to offer additional content assistance for the keys, you could add the following JSON to <>: [source,json,indent=0] ---- @@ -380,7 +380,7 @@ If your IDE supports it, this is by far the most effective approach to auto-comp -[[configuration-metadata-providing-manual-hints-value-providers]] +[[configuration-metadata.manual-hints.value-providers]] === Value Providers Providers are a powerful way to attach semantics to a property. In this section, we define the official providers that you can use for your own hints. @@ -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` @@ -424,7 +424,7 @@ If no provider for a given property is supported, no special content assistance -[[configuration-metadata-providing-manual-hints-any]] +[[configuration-metadata.manual-hints.value-providers.any]] ==== Any The special **any** provider value permits any additional values to be provided. Regular value validation based on the property type should be applied if this is supported. @@ -459,7 +459,7 @@ Note that, in the preceding example, any other value is also allowed. -[[configuration-metadata-providing-manual-hints-class-reference]] +[[configuration-metadata.manual-hints.value-providers.class-reference]] ==== Class Reference The **class-reference** provider auto-completes classes available in the project. This provider supports the following parameters: @@ -503,7 +503,7 @@ The following metadata snippet corresponds to the standard `server.servlet.jsp.c -[[configuration-metadata-providing-manual-hints-handle-as]] +[[configuration-metadata.manual-hints.value-providers.handle-as]] ==== Handle As The **handle-as** provider lets you substitute the type of the property to a more high-level type. This typically happens when the property has a `java.lang.String` type, because you do not want your configuration classes to rely on classes that may not be on the classpath. @@ -553,9 +553,9 @@ It is actually used internally as a `org.springframework.core.io.Resource` but c -[[configuration-metadata-providing-manual-hints-logger-name]] +[[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. @@ -640,7 +640,7 @@ As Spring Boot defines a few logger groups out-of-the-box, dedicated value hints -[[configuration-metadata-providing-manual-hints-spring-bean-reference]] +[[configuration-metadata.manual-hints.value-providers.spring-bean-reference]] ==== Spring Bean Reference The **spring-bean-reference** provider auto-completes the beans that are defined in the configuration of the current project. This provider supports the following parameters: @@ -680,7 +680,7 @@ If you provide that hint, you still need to transform the bean name into an actu -[[configuration-metadata-providing-manual-hints-spring-profile-name]] +[[configuration-metadata.manual-hints.value-providers.spring-profile-name]] ==== Spring Profile Name The **spring-profile-name** provider auto-completes the Spring profiles that are defined in the configuration of the current project. @@ -702,14 +702,14 @@ The following metadata snippet corresponds to the standard `spring.profiles.acti -[[configuration-metadata-annotation-processor]] +[[configuration-metadata.annotation-processor]] == Generating Your Own Metadata by Using the Annotation Processor You can easily generate your own configuration metadata file from items annotated with `@ConfigurationProperties` by using the `spring-boot-configuration-processor` jar. The jar includes a Java annotation processor which is invoked as your project is compiled. -[[configuration-metadata-annotation-processor-setup]] +[[configuration-metadata.annotation-processor.configuring]] === Configuring the Annotation Processor To use the processor, include a dependency on `spring-boot-configuration-processor`. @@ -763,7 +763,7 @@ You could also let the AspectJ plugin run all the processing and disable annotat -[[configuration-metadata-annotation-processor-metadata-generation]] +[[configuration-metadata.annotation-processor.automatic-metadata-generation]] === Automatic Metadata Generation The processor picks up both classes and methods that are annotated with `@ConfigurationProperties`. @@ -807,7 +807,7 @@ The annotation processor applies a number of heuristics to extract the default v Default values have to be provided statically. In particular, do not refer to a constant defined in another class. Also, the annotation processor cannot auto-detect default values for ``Enum``s and ``Collections``s. -For cases where the default value could not be detected, <> should be provided. +For cases where the default value could not be detected, <> should be provided. Consider the following example: [source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"] @@ -831,7 +831,7 @@ Consider the following example: } ---- -In order to document default values for properties in the class above, you could add the following content to <>: +In order to document default values for properties in the class above, you could add the following content to <>: [source,json,indent=0] ---- @@ -851,7 +851,7 @@ NOTE: Only the `name` of the property is required to document additional metadat -[[configuration-metadata-annotation-processor-metadata-generation-nested]] +[[configuration-metadata.annotation-processor.automatic-metadata-generation.nested-properties]] ==== Nested Properties The annotation processor automatically considers inner classes as nested properties. Rather than documenting the `ip` and `port` at the root of the namespace, we could create a sub-namespace for it. @@ -888,7 +888,7 @@ TIP: This has no effect on collections and maps, as those types are automaticall -[[configuration-metadata-additional-metadata]] +[[configuration-metadata.annotation-processor.adding-additional-metadata]] === Adding Additional Metadata Spring Boot's configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a `@ConfigurationProperties` bean. You may also need to tune some attributes of an existing key. 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/appendix-dependency-versions.adoc index 172a0cdc90..2d464b81d7 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/appendix-dependency-versions.adoc @@ -7,7 +7,7 @@ This appendix provides details of the dependencies that are managed by Spring Bo -[[dependency-versions-coordinates]] +[[dependency-versions.coordinates]] == Managed Dependency Coordinates 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. @@ -17,7 +17,7 @@ include::dependency-versions.adoc[] -[[dependency-versions-properties]] +[[dependency-versions.properties]] == Version Properties The following table provides all properties that can be used to override the versions managed by Spring Boot. 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/appendix-executable-jar-format.adoc index 70a9d2f60b..b68e6646ce 100644 --- 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/appendix-executable-jar-format.adoc @@ -10,7 +10,7 @@ If you need to create executable jars from a different build system or if you ar -[[executable-jar-nested-jars]] +[[executable-jar.nested-jars]] == Nested JARs Java does not provide any standard way to load nested jar files (that is, jar files that are themselves contained within a jar). This can be problematic if you need to distribute a self-contained application that can be run from the command line without unpacking. @@ -23,7 +23,7 @@ Spring Boot takes a different approach and lets you actually nest jars directly. -[[executable-jar-jar-file-structure]] +[[executable-jar.nested-jars.jar-structure]] === The Executable Jar File Structure Spring Boot Loader-compatible jar files should be structured in the following way: @@ -53,7 +53,7 @@ Dependencies should be placed in a nested `BOOT-INF/lib` directory. -[[executable-jar-war-file-structure]] +[[executable-jar.nested-jars.war-structure]] === The Executable War File Structure Spring Boot Loader-compatible war files should be structured in the following way: @@ -87,7 +87,7 @@ Any dependencies that are required when running embedded but are not required wh -[[executable-jar-war-index-files]] +[[executable-jar.nested-jars.index-files]] === Index Files Spring Boot Loader-compatible jar and war archives can include additional index files under the `BOOT-INF/` directory. A `classpath.idx` file can be provided for both jars and wars, and it provides the ordering that jars should be added to the classpath. @@ -98,7 +98,7 @@ These files, however, are _not_ parsed internally as YAML and they must be writt -[[executable-jar-war-index-files-classpath]] +[[executable-jar.nested-jars.classpath-index]] === Classpath Index The classpath index file can be provided in `BOOT-INF/classpath.idx`. It provides a list of jar names (including the directory) in the order that they should be added to the classpath. @@ -130,7 +130,7 @@ The index file would look like this: -[[executable-jar-war-index-files-layers]] +[[executable-jar.nested-jars.layer-index]] === Layer Index The layers index file can be provided in `BOOT-INF/layers.idx`. It provides a list of layers and the parts of the jar that should be contained within them. @@ -154,7 +154,7 @@ A typical example of a layers index would be: -[[executable-jar-jarfile]] +[[executable-jar.jarfile-class]] == Spring Boot's "`JarFile`" Class The core class used to support loading nested jars is `org.springframework.boot.loader.jar.JarFile`. It lets you load jar content from a standard jar file or from nested child jar data. @@ -181,7 +181,7 @@ We do not need to unpack the archive, and we do not need to read all entry data -[[executable-jar-jarfile-compatibility]] +[[executable-jar.jarfile-class.compatibilty]] === Compatibility with the Standard Java "`JarFile`" Spring Boot Loader strives to remain compatible with existing code and libraries. `org.springframework.boot.loader.jar.JarFile` extends from `java.util.jar.JarFile` and should work as a drop-in replacement. @@ -189,7 +189,7 @@ The `getURL()` method returns a `URL` that opens a connection compatible with `j -[[executable-jar-launching]] +[[executable-jar.launching]] == Launching Executable Jars The `org.springframework.boot.loader.Launcher` class is a special bootstrap class that is used as an executable jar's main entry point. It is the actual `Main-Class` in your jar file, and it is used to setup an appropriate `URLClassLoader` and ultimately call your `main()` method. @@ -204,7 +204,7 @@ You can add additional locations by setting an environment variable called `LOAD -[[executable-jar-launcher-manifest]] +[[executable-jar.launching.manifest]] === Launcher Manifest You need to specify an appropriate `Launcher` as the `Main-Class` attribute of `META-INF/MANIFEST.MF`. The actual class that you want to launch (that is, the class that contains a `main` method) should be specified in the `Start-Class` attribute. @@ -230,7 +230,7 @@ The classpath is deduced from the nested jars. -[[executable-jar-property-launcher-features]] +[[executable-jar.property-launcher]] == PropertiesLauncher Features `PropertiesLauncher` has a few special features that can be enabled with external properties (System properties, environment variables, manifest entries, or `loader.properties`). The following table describes these properties: @@ -314,7 +314,7 @@ The following rules apply to working with `PropertiesLauncher`: -[[executable-jar-restrictions]] +[[executable-jar.restrictions]] == Executable Jar Restrictions You need to consider the following restrictions when working with a Spring Boot Loader packaged application: @@ -337,7 +337,7 @@ For this reason, you should consider a different logging implementation. -[[executable-jar-alternatives]] +[[executable-jar.alternatives]] == Alternative Single Jar Solutions If the preceding restrictions mean that you cannot use Spring Boot Loader, consider the following alternatives: 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/appendix-test-auto-configuration.adoc index bb5876804a..08accb5ff4 100644 --- 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/appendix-test-auto-configuration.adoc @@ -7,7 +7,7 @@ This appendix describes the `@…Test` auto-configuration annotations that Sprin -[[test-auto-configuration-slices]] +[[test-auto-configuration.slices]] == Test Slices The following table lists the various `@…Test` annotations that can be used to test slices of your application and the auto-configuration that they import by default: 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 c6c2b51308..23bfcb6c67 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,11 +5,11 @@ 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. -[[build-tool-plugins-maven-plugin]] +[[build-tool-plugins.maven]] == Spring Boot Maven Plugin The Spring Boot Maven Plugin provides Spring Boot support in Maven, letting you package executable jar or war archives and run an application "`in-place`". To use it, you must use Maven 3.2 (or later). @@ -21,7 +21,7 @@ Please refer to the plugin's documentation to learn more: -[[build-tool-plugins-gradle-plugin]] +[[build-tool-plugins.gradle]] == Spring Boot Gradle Plugin The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, letting you package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`. It requires Gradle 6.8 or 7.x. @@ -32,7 +32,7 @@ Please refer to the plugin's documentation to learn more: -[[build-tool-plugins-antlib]] +[[build-tool-plugins.antlib]] == Spring Boot AntLib Module The Spring Boot AntLib module provides basic Spring Boot support for Apache Ant. You can use the module to create executable jars. @@ -54,20 +54,20 @@ 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 <>. -[[spring-boot-ant-tasks]] +[[build-tool-plugins.antlib.tasks]] === Spring Boot Ant Tasks Once the `spring-boot-antlib` namespace has been declared, the following additional tasks are available: -* <> -* <> +* <> +* <> -[[spring-boot-ant-exejar]] +[[build-tool-plugins.antlib.tasks.exejar]] ==== Using the "`exejar`" Task You can use the `exejar` task to create a Spring Boot executable jar. The following attributes are supported by the task: @@ -104,7 +104,7 @@ The following nested elements can be used with the task: -[[spring-boot-ant-exejar-examples]] +[[build-tool-plugins.antlib.tasks.examples]] ==== Examples This section shows two examples of Ant tasks. @@ -134,7 +134,7 @@ This section shows two examples of Ant tasks. -[[spring-boot-ant-findmainclass]] +[[build-tool-plugins.antlib.findmainclass]] === Using the "`findmainclass`" Task The `findmainclass` task is used internally by `exejar` to locate a class declaring a `main`. If necessary, you can also use this task directly in your build. @@ -159,7 +159,7 @@ The following attributes are supported: -[[spring-boot-ant-findmainclass-examples]] +[[build-tool-plugins.antlib.findmainclass.examples]] ==== Examples This section contains three examples of using `findmainclass`. @@ -183,7 +183,7 @@ This section contains three examples of using `findmainclass`. -[[build-tool-plugins-other-build-systems]] +[[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). @@ -193,7 +193,7 @@ If you need to, you may use this library directly. -[[build-tool-plugins-repackaging-archives]] +[[build-tool-plugins.other-build-systems.repackaging-archives]] === Repackaging Archives To repackage an existing archive so that it becomes a self-contained executable archive, use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a single constructor argument that refers to an existing jar or war archive. @@ -202,7 +202,7 @@ Various settings can also be configured on the repackager before it is run. -[[build-tool-plugins-nested-libraries]] +[[build-tool-plugins.other-build-systems.nested-libraries]] === Nested Libraries When repackaging an archive, you can include references to dependency files by using the `org.springframework.boot.loader.tools.Libraries` interface. We do not provide any concrete implementations of `Libraries` here as they are usually build-system-specific. @@ -211,14 +211,14 @@ If your archive already includes libraries, you can use `Libraries.NONE`. -[[build-tool-plugins-find-a-main-class]] +[[build-tool-plugins.other-build-systems.finding-main-class]] === Finding a Main Class If you do not use `Repackager.setMainClass()` to specify a main class, the repackager uses https://asm.ow2.io/[ASM] to read class files and tries to find a suitable class with a `public static void main(String[] args)` method. An exception is thrown if more than one candidate is found. -[[build-tool-plugins-repackage-implementation]] +[[build-tool-plugins.other-build-systems.example-repackage-implementation]] === Example Repackage Implementation The following example shows a typical repackage implementation: @@ -237,7 +237,7 @@ The following example shows a typical repackage implementation: -[[build-tool-plugins-whats-next]] +[[build-tool-plugins.whats-next]] == What to Read Next If you are interested in how the build tool plugins work, you can look at the {spring-boot-code}/spring-boot-project/spring-boot-tools[`spring-boot-tools`] module on GitHub. More technical details of the executable jar format are covered in <>. 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 da40e7ada1..d6f826174c 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 @@ -9,7 +9,7 @@ This section covers some of the more common deployment scenarios. -[[containers-deployment]] +[[deployment.containers]] == Deploying to Containers If you are running your application from a container, you can use an executable jar, but it is also often an advantage to explode it and run it in a different way. Certain PaaS implementations may also choose to unpack archives before they run. @@ -36,11 +36,11 @@ 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). -[[cloud-deployment]] +[[deployment.cloud]] == Deploying to the Cloud Spring Boot's executable jars are ready-made for most popular cloud PaaS (Platform-as-a-Service) providers. These providers tend to require that you "`bring your own container`". @@ -55,11 +55,11 @@ It minimizes divergence between development and production environments. Ideally, your application, like a Spring Boot executable jar, has everything that it needs to run packaged within it. -In this section, we look at what it takes to get the <> in the "`Getting Started`" section up and running in the Cloud. +In this section, we look at what it takes to get the <> in the "`Getting Started`" section up and running in the Cloud. -[[cloud-deployment-cloud-foundry]] +[[deployment.cloud.cloud-foundry]] === Cloud Foundry Cloud Foundry provides default buildpacks that come into play if no other buildpack is specified. The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java buildpack] has excellent support for Spring applications, including Spring Boot. @@ -127,7 +127,7 @@ In the preceding example, you could find it at `\https://acloudyspringtime.cfapp -[[cloud-deployment-cloud-foundry-services]] +[[deployment.cloud.cloud-foundry.binding-to-services]] ==== Binding to Services By default, metadata about the running application as well as service connection information is exposed to the application as environment variables (for example: `$VCAP_SERVICES`). This architecture decision is due to Cloud Foundry's polyglot (any language and platform can be supported as a buildpack) nature. @@ -160,16 +160,16 @@ TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a bett -[[cloud-deployment-kubernetes]] +[[deployment.cloud.kubernetes]] === Kubernetes 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 <>. -[[cloud-deployment-kubernetes-container-lifecycle]] +[[deployment.cloud.kubernetes.container-lifecycle]] ==== Kubernetes Container Lifecycle When Kubernetes deletes an application instance, the shutdown process involves several subsystems concurrently: shutdown hooks, unregistering the service, removing the instance from the load-balancer... Because this shutdown processing happens in parallel (and due to the nature of distributed systems), there is a window during which traffic can be routed to a pod that has also begun its shutdown processing. @@ -190,11 +190,11 @@ spec: command: ["sh", "-c", "sleep 10"] ---- -Once the pre-stop hook has completed, SIGTERM will be sent to the container and <> will begin, allowing any remaining in-flight requests to complete. +Once the pre-stop hook has completed, SIGTERM will be sent to the container and <> will begin, allowing any remaining in-flight requests to complete. -[[cloud-deployment-heroku]] +[[deployment.cloud.heroku]] === Heroku Heroku is another popular PaaS platform. To customize Heroku builds, you provide a `Procfile`, which provides the incantation required to deploy an application. @@ -263,7 +263,7 @@ For more details, refer to https://devcenter.heroku.com/articles/deploying-sprin -[[cloud-deployment-openshift]] +[[deployment.cloud.openshift]] === OpenShift https://www.openshift.com/[OpenShift] has many resources describing how to deploy Spring Boot applications, including: @@ -274,7 +274,7 @@ https://www.openshift.com/[OpenShift] has many resources describing how to deplo -[[cloud-deployment-aws]] +[[deployment.cloud.aws]] === Amazon Web Services (AWS) Amazon Web Services offers multiple ways to install Spring Boot-based applications, either as traditional web applications (war) or as executable jar files with an embedded web server. The options include: @@ -290,14 +290,14 @@ In this document, we describe to approach using AWS Elastic Beanstalk. -[[cloud-deployment-aws-beanstalk]] +[[deployment.cloud.aws.beanstalk]] ==== AWS Elastic Beanstalk As described in the official https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_Java.html[Elastic Beanstalk Java guide], there are two main options to deploy a Java application. You can either use the "`Tomcat Platform`" or the "`Java SE platform`". -[[cloud-deployment-aws-tomcat-platform]] +[[deployment.cloud.aws.beanstalk.tomcat-platform]] ===== Using the Tomcat Platform This option applies to Spring Boot projects that produce a war file. No special configuration is required. @@ -305,7 +305,7 @@ You need only follow the official guide. -[[cloud-deployment-aws-java-se-platform]] +[[deployment.cloud.aws.beanstalk.java-se-platform]] ===== Using the Java SE Platform This option applies to Spring Boot projects that produce a jar file and run an embedded web container. Elastic Beanstalk environments run an nginx instance on port 80 to proxy the actual application, running on port 5000. @@ -347,14 +347,14 @@ You can also create single instance environments by using the CLI and the follow -[[cloud-deployment-aws-summary]] +[[deployment.cloud.aws.summary]] ==== Summary This is one of the easiest ways to get to AWS, but there are more things to cover, such as how to integrate Elastic Beanstalk into any CI / CD tool, use the Elastic Beanstalk Maven plugin instead of the CLI, and others. There is a https://exampledriven.wordpress.com/2017/01/09/spring-boot-aws-elastic-beanstalk-example/[blog post] covering these topics more in detail. -[[cloud-deployment-boxfuse]] +[[deployment.cloud.boxfuse]] === Boxfuse and Amazon Web Services https://boxfuse.com/[Boxfuse] works by turning your Spring Boot executable jar or war into a minimal VM image that can be deployed unchanged either on VirtualBox or on AWS. Boxfuse comes with deep integration for Spring Boot and uses the information from your Spring Boot configuration file to automatically configure ports and health check URLs. @@ -402,7 +402,7 @@ See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spr -[[cloud-deployment-gae]] +[[deployment.cloud.google]] === Google Cloud Google Cloud has several options that can be used to launch Spring Boot applications. The easiest to get started with is probably App Engine, but you could also find ways to run Spring Boot in a container with Container Engine or on a virtual machine with Compute Engine. @@ -458,10 +458,10 @@ Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the -[[deployment-install]] +[[deployment.installing]] == Installing Spring Boot Applications In addition to running Spring Boot applications by using `java -jar`, it is also possible to make fully executable applications for Unix systems. -A fully executable jar can be executed like any other executable binary or it can be <>. +A fully executable jar can be executed like any other executable binary or it can be <>. This helps when installing and managing Spring Boot applications in common production environments. CAUTION: Fully executable jars work by embedding an extra script at the front of the file. @@ -500,22 +500,22 @@ The directory containing the jar is used as your application's working directory -[[deployment-install-supported-operating-systems]] +[[deployment.installing.supported-operating-systems]] === Supported Operating Systems The default script supports most Linux distributions and is tested on CentOS and Ubuntu. Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`. -[[deployment-service]] +[[deployment.installing.nix-services]] === Unix/Linux Services Spring Boot application can be easily started as Unix/Linux services by using either `init.d` or `systemd`. -[[deployment-initd-service]] +[[deployment.installing.nix-services.init-d]] ==== Installation as an init.d Service (System V) -If you configured Spring Boot's Maven or Gradle plugin to generate a <>, and you do not use a custom `embeddedLaunchScript`, your application can be used as an `init.d` service. +If you configured Spring Boot's Maven or Gradle plugin to generate a <>, and you do not use a custom `embeddedLaunchScript`, your application can be used as an `init.d` service. To do so, symlink the jar to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands. The script supports the following features: @@ -551,7 +551,7 @@ For example, on Debian, you could use the following command: -[[deployment-initd-service-securing]] +[[deployment.installing.nix-services.init-d.securing]] ===== Securing an init.d Service NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service. It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs. @@ -602,7 +602,7 @@ Use `chmod` so that the file can only be read by the owner and use `chown` to ma -[[deployment-systemd-service]] +[[deployment.installing.nix-services.system-d]] ==== Installation as a systemd Service `systemd` is the successor of the System V init system and is now being used by many modern Linux distributions. Although you can continue to use `init.d` scripts with `systemd`, it is also possible to launch Spring Boot applications by using `systemd` '`service`' scripts. @@ -643,7 +643,7 @@ Refer to `man systemctl` for more details. -[[deployment-script-customization]] +[[deployment.installing.nix-services.script-customization]] ==== Customizing the Startup Script The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways. For most people, using the default script along with a few customizations is usually enough. @@ -651,7 +651,7 @@ If you find you cannot customize something that you need to, use the `embeddedLa -[[deployment-script-customization-when-it-written]] +[[deployment.installing.nix-services.script-customization.when-written]] ===== Customizing the Start Script When It Is Written It often makes sense to customize elements of the start script as it is written into the jar file. For example, init.d scripts can provide a "`description`". @@ -759,7 +759,7 @@ The following property substitutions are supported with the default script: -[[deployment-script-customization-when-it-runs]] +[[deployment.installing.nix-services.script-customization.when-running]] ===== Customizing a Script When It Runs For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <>. @@ -838,11 +838,11 @@ For example, a jar named `/var/myapp/myapp.jar` uses the configuration file name TIP: If you do not like having the config file next to the jar file, you can set a `CONF_FOLDER` environment variable to customize the location of the config file. -To learn about securing this file appropriately, see <>. +To learn about securing this file appropriately, see <>. -[[deployment-windows]] +[[deployment.installing.windows-services]] === Microsoft Windows Services A Spring Boot application can be started as a Windows service by using https://github.com/kohsuke/winsw[`winsw`]. @@ -850,7 +850,7 @@ A (https://github.com/snicoll/spring-boot-daemon[separately maintained sample]) -[[deployment-whats-next]] +[[deployment.whats-next]] == What to Read Next Check out the https://www.cloudfoundry.org/[Cloud Foundry], https://www.heroku.com/[Heroku], https://www.openshift.com[OpenShift], and https://boxfuse.com[Boxfuse] web sites for more information about the kinds of features that a PaaS can offer. These are just four of the most popular Java PaaS providers. 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-overview.adoc index a383074abd..e17d4dd2f8 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-overview.adoc @@ -1,4 +1,4 @@ -[[boot-documentation]] +[[documentation]] = Spring Boot Documentation include::attributes.adoc[] @@ -7,7 +7,7 @@ It serves as a map for the rest of the document. -[[boot-documentation-about]] +[[documentation.about]] == About the Documentation The Spring Boot reference guide is available as: @@ -21,7 +21,7 @@ Copies of this document may be made for your own use and for distribution to oth -[[boot-documentation-getting-help]] +[[documentation.getting-help]] == Getting Help If you have trouble with Spring Boot, we would like to help. @@ -40,7 +40,7 @@ If you find problems with the docs or if you want to improve them, please {sprin -[[boot-documentation-upgrading]] +[[documentation.upgrading]] == Upgrading From an Earlier Version Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project {github-wiki}[wiki]. Follow the links in the {github-wiki}#release-notes[release notes] section to find the version that you want to upgrade to. @@ -52,56 +52,56 @@ You should always ensure that you are running a {github-wiki}/Supported-Versions -[[boot-documentation-first-steps]] +[[documentation.first-steps]] == First Steps If you are getting started with Spring Boot or 'Spring' in general, start with <>: -* *From scratch:* <> | <> | <> -* *Tutorial:* <> | <> -* *Running your example:* <> | <> +* *From scratch:* <> | <> | <> +* *Tutorial:* <> | <> +* *Running your example:* <> | <> -[[boot-documentation-workingwith]] +[[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:* <> +* *Build systems:* <> | <> | <> | <> +* *Best practices:* <> | <> | <> | <> +* *Running your code:* <> | <> | <> | <> +* *Packaging your app:* <> * *Spring Boot CLI:* <> -[[boot-documentation-learning]] +[[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:* <> | <> -[[boot-documentation-production]] +[[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:* <> | <> | <> | <> -[[boot-documentation-advanced]] +[[documentation.advanced]] == Advanced Topics Finally, we have a few topics for more advanced users: -* *Spring Boot Applications Deployment:* <> | <> -* *Build tool plugins:* <> | <> +* *Spring Boot Applications Deployment:* <> | <> +* *Build tool plugins:* <> | <> * *Appendix:* <> | <> | <> | <> | <> | <> 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 f46a54bb8a..25bde796fd 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 @@ -9,7 +9,7 @@ We then walk you through building your first Spring Boot application, discussing -[[getting-started-introducing-spring-boot]] +[[getting-started.introducing-spring-boot]] == Introducing Spring Boot Spring Boot helps you to create stand-alone, production-grade Spring-based Applications that you can run. We take an opinionated view of the Spring platform and third-party libraries, so that you can get started with minimum fuss. @@ -27,7 +27,7 @@ Our primary goals are: -[[getting-started-system-requirements]] +[[getting-started.system-requirements]] == System Requirements Spring Boot {spring-boot-version} requires https://www.java.com[Java 8] and is compatible up to Java 16 (included). {spring-framework-docs}/[Spring Framework {spring-framework-version}] or above is also required. @@ -46,7 +46,7 @@ Explicit build support is provided for the following build tools: -[[getting-started-system-requirements-servlet-containers]] +[[getting-started.system-requirements.servlet-containers]] === Servlet Containers Spring Boot supports the following embedded servlet containers: @@ -70,7 +70,7 @@ You can also deploy Spring Boot applications to any Servlet 3.1+ compatible cont -[[getting-started-installing-spring-boot]] +[[getting-started.installing]] == Installing Spring Boot Spring Boot can be used with "`classic`" Java development tools or installed as a command line tool. Either way, you need https://www.java.com[Java SDK v1.8] or higher. @@ -81,12 +81,12 @@ Before you begin, you should check your current Java installation by using the f $ java -version ---- -If you are new to Java development or if you want to experiment with Spring Boot, you might want to try the <> (Command Line Interface) first. +If you are new to Java development or if you want to experiment with Spring Boot, you might want to try the <> (Command Line Interface) first. Otherwise, read on for "`classic`" installation instructions. -[[getting-started-installation-instructions-for-java]] +[[getting-started.installing.java]] === Installation Instructions for the Java Developer You can use Spring Boot in the same way as any standard Java library. To do so, include the appropriate `+spring-boot-*.jar+` files on your classpath. @@ -97,7 +97,7 @@ Although you _could_ copy Spring Boot jars, we generally recommend that you use -[[getting-started-maven-installation]] +[[getting-started.installing.java.maven]] ==== Maven Installation Spring Boot is compatible with Apache Maven 3.3 or above. If you do not already have Maven installed, you can follow the instructions at https://maven.apache.org. @@ -108,21 +108,21 @@ 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 <>. -Spring Boot also provides an optional <> to create executable jars. +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. -[[getting-started-gradle-installation]] +[[getting-started.installing.java.gradle]] ==== Gradle Installation 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 <>. -Spring Boot provides a useful <> that can be used to simplify dependency declarations and to create executable jars. +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 **** @@ -135,7 +135,7 @@ More details on getting started with Spring Boot and Gradle can be found in the -[[getting-started-installing-the-cli]] +[[getting-started.installing.cli]] === Installing the Spring Boot CLI The Spring Boot CLI (Command Line Interface) is a command line tool that you can use to quickly prototype with Spring. It lets you run https://groovy-lang.org/[Groovy] scripts, which means that you have a familiar Java-like syntax without so much boilerplate code. @@ -144,7 +144,7 @@ You do not need to use the CLI to work with Spring Boot, but it is definitely th -[[getting-started-manual-cli-installation]] +[[getting-started.installing.cli.manual-installation]] ==== Manual Installation You can download the Spring CLI distribution from the Spring software repository: @@ -160,7 +160,7 @@ Alternatively, you can use `java -jar` with the `.jar` file (the script helps yo -[[getting-started-sdkman-cli-installation]] +[[getting-started.installing.cli.sdkman]] ==== Installation with SDKMAN! SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions of various binary SDKs, including Groovy and the Spring Boot CLI. Get SDKMAN! from https://sdkman.io and install Spring Boot by using the following commands: @@ -206,7 +206,7 @@ You can see it by running the following command: -[[getting-started-homebrew-cli-installation]] +[[getting-started.installing.cli.homebrew]] ==== OSX Homebrew Installation If you are on a Mac and use https://brew.sh/[Homebrew], you can install the Spring Boot CLI by using the following commands: @@ -223,7 +223,7 @@ In that case, run `brew update` and try again. -[[getting-started-macports-cli-installation]] +[[getting-started.installing.cli.macports]] ==== MacPorts Installation If you are on a Mac and use https://www.macports.org/[MacPorts], you can install the Spring Boot CLI by using the following command: @@ -234,7 +234,7 @@ If you are on a Mac and use https://www.macports.org/[MacPorts], you can install -[[getting-started-cli-command-line-completion]] +[[getting-started.installing.cli.completion]] ==== Command-line Completion The Spring Boot CLI includes scripts that provide command completion for the https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29[BASH] and https://en.wikipedia.org/wiki/Z_shell[zsh] shells. You can `source` the script (also named `spring`) in any shell or put it in your personal or system-wide bash completion initialization. @@ -252,7 +252,7 @@ NOTE: If you install the Spring Boot CLI by using Homebrew or MacPorts, the comm -[[getting-started-scoop-cli-installation]] +[[getting-started.installing.scoop]] ==== Windows Scoop Installation If you are on a Windows and use https://scoop.sh/[Scoop], you can install the Spring Boot CLI by using the following commands: @@ -269,7 +269,7 @@ In that case, run `scoop update` and try again. -[[getting-started-cli-example]] +[[getting-started.installing.quick-start]] ==== Quick-start Spring CLI Example You can use the following web application to test your installation. To start, create a file called `app.groovy`, as follows: @@ -307,7 +307,7 @@ You should see the following output: -[[getting-started-upgrading-from-an-earlier-version]] +[[getting-started.installing.upgrading]] === Upgrading from an Earlier Version of Spring Boot If you are upgrading from the `1.x` release of Spring Boot, check the {github-wiki}/Spring-Boot-2.0-Migration-Guide["`migration guide`" on the project wiki] that provides detailed upgrade instructions. Check also the {github-wiki}["`release notes`"] for a list of "`new and noteworthy`" features for each release. @@ -330,11 +330,11 @@ WARNING: Properties that are added late to the environment, such as when using ` NOTE: Once you're done with the migration, please make sure to remove this module from your project's dependencies. To upgrade an existing CLI installation, use the appropriate package manager command (for example, `brew upgrade`). -If you manually installed the CLI, follow the <>, remembering to update your `PATH` environment variable to remove any older references. +If you manually installed the CLI, follow the <>, remembering to update your `PATH` environment variable to remove any older references. -[[getting-started-first-application]] +[[getting-started.first-application]] == Developing Your First Spring Boot Application This section describes how to develop a small "`Hello World!`" web application that highlights some of Spring Boot's key features. We use Maven to build this project, since most IDEs support it. @@ -345,7 +345,7 @@ The https://spring.io[spring.io] web site contains many "`Getting Started`" http If you need to solve a specific problem, check there first. You can shortcut the steps below by going to https://start.spring.io and choosing the "Web" starter from the dependencies searcher. -Doing so generates a new project structure so that you can <>. +Doing so generates a new project structure so that you can <>. Check the https://github.com/spring-io/start.spring.io/blob/main/USING.adoc[start.spring.io user guide] for more details. ==== @@ -372,7 +372,7 @@ Subsequent instructions assume that you have created a suitable directory and th -[[getting-started-first-application-pom]] +[[getting-started.first-application.pom]] === Creating the POM We need to start by creating a Maven `pom.xml` file. The `pom.xml` is the recipe that is used to build your project. @@ -444,12 +444,12 @@ For simplicity, we continue to use a plain text editor for this example. -[[getting-started-first-application-dependencies]] +[[getting-started.first-application.dependencies]] === Adding Classpath Dependencies 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. @@ -480,7 +480,7 @@ If you run `mvn dependency:tree` again, you see that there are now a number of a -[[getting-started-first-application-code]] +[[getting-started.first-application.code]] === Writing the Code To finish our application, we need to create a single Java file. By default, Maven compiles sources from `src/main/java`, so you need to create that directory structure and then add a file named `src/main/java/Example.java` to contain the following code: @@ -512,7 +512,7 @@ We step through the important parts in the next few sections. -[[getting-started-first-application-annotations]] +[[getting-started.first-application.code.mvc-annotations]] ==== The @RestController and @RequestMapping Annotations The first annotation on our `Example` class is `@RestController`. This is known as a _stereotype_ annotation. @@ -528,7 +528,7 @@ See the {spring-framework-docs}/web.html#mvc[MVC section] in the Spring Referenc -[[getting-started-first-application-auto-configuration]] +[[getting-started.first-application.code.enable-auto-configuration]] ==== The @EnableAutoConfiguration Annotation The second class-level annotation is `@EnableAutoConfiguration`. This annotation tells Spring Boot to "`guess`" how you want to configure Spring, based on the jar dependencies that you have added. @@ -543,7 +543,7 @@ Spring Boot still does its best to auto-configure your application. -[[getting-started-first-application-main-method]] +[[getting-started.first-application.code.main-method]] ==== The "`main`" Method The final part of our application is the `main` method. This is a standard method that follows the Java convention for an application entry point. @@ -554,7 +554,7 @@ The `args` array is also passed through to expose any command-line arguments. -[[getting-started-first-application-run]] +[[getting-started.first-application.run]] === Running the Example At this point, your application should work. Since you used the `spring-boot-starter-parent` POM, you have a useful `run` goal that you can use to start the application. @@ -589,7 +589,7 @@ To gracefully exit the application, press `ctrl-c`. -[[getting-started-first-application-executable-jar]] +[[getting-started.first-application.executable-jar]] === Creating an Executable Jar We finish our example by creating a completely self-contained executable jar file that we could run in production. Executable jars (sometimes called "`fat jars`") are archives containing your compiled classes along with all of the jar dependencies that your code needs to run. @@ -682,11 +682,11 @@ As before, to exit the application, press `ctrl-c`. -[[getting-started-whats-next]] +[[getting-started.whats=next]] == What to Read Next Hopefully, this section provided some of the Spring Boot basics and got you on your way to writing your own applications. 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 04585b2134..f688c9d016 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 @@ -13,13 +13,13 @@ If you want to add a '`how-to`', send us a {spring-boot-code}[pull request]. -[[howto-spring-boot-application]] +[[howto.application]] == Spring Boot Application This section includes topics relating directly to Spring Boot applications. -[[howto-failure-analyzer]] +[[howto.application.failure-analyzer]] === Create Your Own FailureAnalyzer {spring-boot-module-api}/diagnostics/FailureAnalyzer.html[`FailureAnalyzer`] is a great way to intercept an exception on startup and turn it into a human-readable message, wrapped in a {spring-boot-module-api}/diagnostics/FailureAnalysis.html[`FailureAnalysis`]. Spring Boot provides such an analyzer for application-context-related exceptions, JSR-303 validations, and more. @@ -42,13 +42,13 @@ NOTE: If you need access to the `BeanFactory` or the `Environment`, your `Failur -[[howto-troubleshoot-auto-configuration]] +[[howto.application.troubleshoot-auto-configuration]] === Troubleshoot Auto-configuration The Spring Boot auto-configuration tries its best to "`do the right thing`", but sometimes things fail, and it can be hard to tell why. 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. @@ -69,7 +69,7 @@ When reading the code, remember the following rules of thumb: -[[howto-customize-the-environment-or-application-context]] +[[howto.application.customize-the-environment-or-application-context]] === Customize the Environment or ApplicationContext Before It Starts A `SpringApplication` has `ApplicationListeners` and `ApplicationContextInitializers` that are used to apply customizations to the context or environment. Spring Boot loads a number of such customizations for use internally from `META-INF/spring.factories`. @@ -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: @@ -109,14 +109,14 @@ This is too late to configure certain properties such as `+logging.*+` and `+spr -[[howto-build-an-application-context-hierarchy]] +[[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. -[[howto-create-a-non-web-application]] +[[howto.application.non-web-application]] === Create a Non-web Application Not all Spring applications have to be web applications (or web services). If you want to execute some code in a `main` method but also bootstrap a Spring application to set up the infrastructure to use, you can use the `SpringApplication` features of Spring Boot. @@ -127,20 +127,20 @@ Application code that you want to run as your business logic can be implemented -[[howto-properties-and-configuration]] +[[howto.properties-and-configuration]] == Properties and Configuration This section includes topics about setting and reading properties and configuration settings and their interaction with Spring Boot applications. -[[howto-automatic-expansion]] +[[howto.properties-and-configuration.expand-properties]] === Automatically Expand Properties at Build Time Rather than hardcoding some properties that are also specified in your project's build configuration, you can automatically expand them by instead using the existing build configuration. This is possible in both Maven and Gradle. -[[howto-automatic-expansion-maven]] +[[howto.properties-and-configuration.expand-properties.maven]] ==== Automatic Property Expansion Using Maven You can automatically expand properties from the Maven project by using resource filtering. If you use the `spring-boot-starter-parent`, you can then refer to your Maven '`project properties`' with `@..@` placeholders, as shown in the following example: @@ -194,7 +194,7 @@ If that property is not set to `false`, these may be expanded by the build. -[[howto-automatic-expansion-gradle]] +[[howto.properties-and-configuration.expand-properties.gradle]] ==== Automatic Property Expansion Using Gradle You can automatically expand properties from the Gradle project by configuring the Java plugin's `processResources` task to do so, as shown in the following example: @@ -220,7 +220,7 @@ To use Spring property placeholders together with automatic expansion, escape th -[[howto-externalize-configuration]] +[[howto.properties-and-configuration.externalize-configuration]] === Externalize the Configuration of SpringApplication A `SpringApplication` has bean properties (mainly setters), so you can use its Java API as you create the application to modify its behavior. Alternatively, you can externalize the configuration by setting properties in `+spring.main.*+`. @@ -261,9 +261,9 @@ The actual application _now_ shows the banner (as overridden by configuration) a -[[howto-change-the-location-of-external-properties]] +[[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: @@ -280,7 +280,7 @@ See {spring-boot-module-code}/context/config/ConfigFileApplicationListener.java[ -[[howto-use-short-command-line-arguments]] +[[howto.properties-and-configuration.short-command-line-arguments]] === Use '`Short`' Command Line Arguments Some people like to use (for example) `--port=9000` instead of `--server.port=9000` to set configuration properties on the command line. You can enable this behavior by using placeholders in `application.properties`, as shown in the following example: @@ -299,7 +299,7 @@ In those two platforms, the `PORT` environment variable is set automatically and -[[howto-use-yaml-for-external-properties]] +[[howto.properties-and-configuration.yaml]] === Use YAML for External Properties YAML is a superset of JSON and, as such, is a convenient syntax for storing external properties in a hierarchical format, as shown in the following example: @@ -329,11 +329,11 @@ 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. -[[howto-set-active-spring-profiles]] +[[howto.properties-and-configuration.set-active-spring-profiles]] === Set the Active Spring Profiles The Spring `Environment` has an API for this, but you would normally set a System property (configprop:spring.profiles.active[]) or an OS environment variable (configprop:spring.profiles.active[format=envvar]). Also, you can launch your application with a `-D` argument (remember to put it before the main class or jar archive), as follows: @@ -355,13 +355,13 @@ 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. -[[howto-change-configuration-depending-on-the-environment]] +[[howto.properties-and-configuration.change-configuration-depending-on-the-environment]] === Change Configuration Depending on the Environment -Spring Boot supports multi-document YAML and Properties files (see <> for details) which can be activated conditionally based on the active profiles. +Spring Boot supports multi-document YAML and Properties files (see <> for details) which can be activated conditionally based on the active profiles. If a document contains a `spring.config.activate.on-profile` key, then the profiles value (a comma-separated list of profiles or a profile expression) is fed into the Spring `Environment.acceptsProfiles()` method. If the profile expression matches then that document is included in the final merge (otherwise, it is not), as shown in the following example: @@ -395,7 +395,7 @@ Later values override earlier values. -[[howto-discover-build-in-options-for-external-properties]] +[[howto.properties-and-configuration.discover-build-in-options-for-external-properties]] === Discover Built-in Options for External Properties Spring Boot binds external properties from `application.properties` (or `.yml` files and other places) into an application at runtime. There is not (and technically cannot be) an exhaustive list of all supported properties in a single location, because contributions can come from additional jar files on your classpath. @@ -404,11 +404,11 @@ A running application with the Actuator features has a `configprops` endpoint th 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 "<>". +For more about the exact ordering of loading properties, see "<>". -[[howto-embedded-web-servers]] +[[howto.webserver]] == Embedded Web Servers Each Spring Boot web application includes an embedded web server. This feature leads to a number of how-to questions, including how to change the embedded server and how to configure the embedded server. @@ -416,7 +416,7 @@ This section answers those questions. -[[howto-use-another-web-server]] +[[howto.webserver.use-another]] === Use Another Web Server Many Spring Boot starters include default embedded containers. @@ -476,7 +476,7 @@ NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient` cla -[[howto-disable-web-server]] +[[howto.webserver.disable]] === Disabling the Web Server If your classpath contains the necessary bits to start a web server, Spring Boot will automatically start it. To disable this behavior configure the `WebApplicationType` in your `application.properties`, as shown in the following example: @@ -490,24 +490,24 @@ To disable this behavior configure the `WebApplicationType` in your `application -[[howto-change-the-http-port]] +[[howto.webserver.change-port]] === Change the HTTP Port In a standalone application, the main HTTP port defaults to `8080` but can be set with configprop:server.port[] (for example, in `application.properties` or as a System property). Thanks to relaxed binding of `Environment` values, you can also use configprop:server.port[format=envvar] (for example, as an OS environment variable). 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. -[[howto-user-a-random-unassigned-http-port]] +[[howto.webserver.use-random-port]] === Use a Random Unassigned HTTP Port To scan for a free port (using OS natives to prevent clashes) use `server.port=0`. -[[howto-discover-the-http-port-at-runtime]] +[[howto.webserver.discover-port]] === Discover the HTTP Port at Runtime You can access the port the server is running on from log output or from the `WebServerApplicationContext` through its `WebServer`. The best way to get that and be sure it has been initialized is to add a `@Bean` of type `ApplicationListener` and pull the container out of the event when it is published. @@ -537,7 +537,7 @@ Contrary to a test, application code callbacks are processed early (before the v -[[how-to-enable-http-response-compression]] +[[howto.webserver.enable-response-compression]] === Enable HTTP Response Compression HTTP response compression is supported by Jetty, Tomcat, and Undertow. It can be enabled in `application.properties`, as follows: @@ -567,7 +567,7 @@ You can configure this behavior by setting the configprop:server.compression.mim -[[howto-configure-ssl]] +[[howto.webserver.configure-ssl]] === Configure SSL SSL can be configured declaratively by setting the various `+server.ssl.*+` properties, typically in `application.properties` or `application.yml`. The following example shows setting SSL properties in `application.properties`: @@ -591,7 +591,7 @@ We recommend using `application.properties` to configure HTTPS, as the HTTP conn -[[howto-configure-http2]] +[[howto.webserver.configure-http2]] === Configure HTTP/2 You can enable HTTP/2 support in your Spring Boot application with the configprop:server.http2.enabled[] configuration property. Both `h2` (HTTP/2 over TLS) and `h2c` (HTTP/2 over TCP) are supported. @@ -601,7 +601,7 @@ The details of the `h2` support depend on the chosen web server and the applicat -[[howto-configure-http2-tomcat]] +[[howto.webserver.configure-http2.tomcat]] ==== HTTP/2 with Tomcat Spring Boot ships by default with Tomcat 9.0.x which supports `h2c` out of the box and `h2` out of the box when using JDK 9 or later. Alternatively, `h2` can be used on JDK 8 if the `libtcnative` library and its dependencies are installed on the host operating system. @@ -621,7 +621,7 @@ This error is not fatal, and the application still starts with HTTP/1.1 SSL supp -[[howto-configure-http2-jetty]] +[[howto.webserver.configure-http2.jetty]] ==== HTTP/2 with Jetty For HTTP/2 support, Jetty requires the additional `org.eclipse.jetty.http2:http2-server` dependency. To use `h2c` no other dependencies are required. @@ -633,7 +633,7 @@ To use `h2`, you also need to choose one of the following dependencies, dependin -[[howto-configure-http2-netty]] +[[howto.webserver.configure-http2.netty]] ==== HTTP/2 with Reactor Netty The `spring-boot-webflux-starter` is using by default Reactor Netty as a server. Reactor Netty supports `h2c` using JDK 8 or later with no additional dependencies. @@ -646,15 +646,15 @@ Developers can choose to import only the required dependencies using a classifie -[[howto-configure-http2-undertow]] +[[howto.webserver.configure-http2.undertow]] ==== HTTP/2 with Undertow As of Undertow 1.4.0+, both `h2` and `h2c` are supported on JDK 8 without any additional dependencies. -[[howto-configure-webserver]] +[[howto.webserver.configure]] === 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 "`<>`"). +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 <>. @@ -711,16 +711,16 @@ When you do so, auto-configured customizers are still applied on your custom fac -[[howto-add-a-servlet-filter-or-listener]] +[[howto.webserver.add-servlet-filter-listener]] === Add a Servlet, Filter, or Listener to an Application In a servlet stack application, i.e. with the `spring-boot-starter-web`, there are two ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other listeners supported by the Servlet API to your application: -* <> -* <> +* <> +* <> -[[howto-add-a-servlet-filter-or-listener-as-spring-bean]] +[[howto.webserver.add-servlet-filter-listener.spring-bean]] ==== Add a Servlet, Filter, or Listener by Using a Spring Bean To add a `Servlet`, `Filter`, or Servlet `*Listener` by using a Spring bean, you must provide a `@Bean` definition for it. Doing so can be very useful when you want to inject configuration or dependencies. @@ -736,13 +736,13 @@ 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. -[[howto-disable-registration-of-a-servlet-or-filter]] +[[howto.webserver.add-servlet-filter-listener.spring-bean.disable]] ===== Disable Registration of a Servlet or Filter -As <>, any `Servlet` or `Filter` beans are registered with the servlet container automatically. +As <>, any `Servlet` or `Filter` beans are registered with the servlet container automatically. To disable registration of a particular `Filter` or `Servlet` bean, create a registration bean for it and mark it as disabled, as shown in the following example: [source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"] @@ -757,14 +757,14 @@ To disable registration of a particular `Filter` or `Servlet` bean, create a reg -[[howto-add-a-servlet-filter-or-listener-using-scanning]] +[[howto.webserver.add-servlet-filter-listener.using-scanning]] ==== Add Servlets, Filters, and Listeners by Using Classpath Scanning `@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically registered with an embedded servlet container by annotating a `@Configuration` class with `@ServletComponentScan` and specifying the package(s) containing the components that you want to register. By default, `@ServletComponentScan` scans from the package of the annotated class. -[[howto-configure-accesslogs]] +[[howto.webserver.configure-access-logs]] === Configure Access Logging Access logs can be configured for Tomcat, Undertow, and Jetty through their respective namespaces. @@ -814,7 +814,7 @@ For more details, see the Jetty documentation. -[[howto-use-behind-a-proxy-server]] +[[howto.webserver.use-behind-a-proxy-server]] === Running Behind a Front-end Proxy Server If your application is running behind a proxy, a load-balancer or in the cloud, the request information (like the host, port, scheme...) might change along the way. Your application may be running on `10.10.10.10:8080`, but HTTP clients should only see `example.org`. @@ -837,7 +837,7 @@ In all other instances, it defaults to `NONE`. -[[howto-customize-tomcat-behind-a-proxy-server]] +[[howto.webserver.use-behind-a-proxy-server.tomcat]] ==== Customize Tomcat's Proxy Configuration If you use Tomcat, you can additionally configure the names of the headers used to carry "`forwarded`" information, as shown in the following example: @@ -868,7 +868,7 @@ You can take complete control of the configuration of Tomcat's `RemoteIpValve` b -[[howto-enable-multiple-connectors-in-tomcat]] +[[howto.webserver.enable-multiple-connectors-in-tomcat]] === Enable Multiple Connectors with Tomcat You can add an `org.apache.catalina.connector.Connector` to the `TomcatServletWebServerFactory`, which can allow multiple connectors, including HTTP and HTTPS connectors, as shown in the following example: @@ -879,7 +879,7 @@ include::{include-howto}/embeddedwebservers/TomcatMultipleConnectorsConfiguratio -[[howto-use-tomcat-legacycookieprocessor]] +[[howto.webserver.use-tomcat-legacycookieprocessor]] === Use Tomcat's LegacyCookieProcessor By default, the embedded Tomcat used by Spring Boot does not support "Version 0" of the Cookie format, so you may see the following error: @@ -899,7 +899,7 @@ include::{include-howto}/embeddedwebservers/LegacyCookieProcessorConfiguration.j -[[howto-enable-tomcat-mbean-registry]] +[[howto.webserver.enable-tomcat-mbean-registry]] === Enable Tomcat's MBean Registry Embedded Tomcat's MBean registry is disabled by default. This minimizes Tomcat's memory footprint. @@ -915,7 +915,7 @@ server: -[[howto-enable-multiple-listeners-in-undertow]] +[[howto.webserver.enable-multiple-listeners-in-undertow]] === Enable Multiple Listeners with Undertow Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and add a listener to the `Builder`, as shown in the following example: @@ -926,7 +926,7 @@ include::{include-howto}/embeddedwebservers/UndertowMultipleListenersConfigurati -[[howto-create-websocket-endpoints-using-serverendpoint]] +[[howto.webserver.create-websocket-endpoints-using-serverendpoint]] === Create WebSocket Endpoints Using @ServerEndpoint If you want to use `@ServerEndpoint` in a Spring Boot application that used an embedded container, you must declare a single `ServerEndpointExporter` `@Bean`, as shown in the following example: @@ -943,7 +943,7 @@ When deployed to a standalone servlet container, this role is performed by a ser -[[howto-spring-mvc]] +[[howto.spring-mvc]] == Spring MVC Spring Boot has a number of starters that include Spring MVC. Note that some starters include a dependency on Spring MVC rather than include it directly. @@ -951,7 +951,7 @@ This section answers common questions about Spring MVC and Spring Boot. -[[howto-write-a-json-rest-service]] +[[howto.spring-mvc.write-json-rest-service]] === Write a JSON REST Service Any Spring `@RestController` in a Spring Boot application should render JSON response by default as long as Jackson2 is on the classpath, as shown in the following example: @@ -973,7 +973,7 @@ Note that, in a browser, you might sometimes see XML responses, because browsers -[[howto-write-an-xml-rest-service]] +[[howto.spring-mvc.write-xml-rest-service]] === Write an XML REST Service If you have the Jackson XML extension (`jackson-dataformat-xml`) on the classpath, you can use it to render XML responses. The previous example that we used for JSON would work. @@ -1013,7 +1013,7 @@ NOTE: To get the server to render XML instead of JSON, you might have to send an -[[howto-customize-the-jackson-objectmapper]] +[[howto.spring-mvc.customize-jackson-objectmapper]] === Customize the Jackson ObjectMapper Spring MVC (client and server side) uses `HttpMessageConverters` to negotiate content conversion in an HTTP exchange. If Jackson is on the classpath, you already get the default converter(s) provided by `Jackson2ObjectMapperBuilder`, an instance of which is auto-configured for you. @@ -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. @@ -1076,11 +1076,11 @@ If you provide any `@Beans` of type `MappingJackson2HttpMessageConverter`, they Also, a convenience bean of type `HttpMessageConverters` is provided (and is always available if you use the default MVC configuration). It has some useful methods to access the default and user-enhanced message converters. -See the "`<>`" section and the {spring-boot-autoconfigure-module-code}/web/servlet/WebMvcAutoConfiguration.java[`WebMvcAutoConfiguration`] source code for more details. +See the "`<>`" section and the {spring-boot-autoconfigure-module-code}/web/servlet/WebMvcAutoConfiguration.java[`WebMvcAutoConfiguration`] source code for more details. -[[howto-customize-the-responsebody-rendering]] +[[howtospring-mvc.customize-responsebody-rendering]] === Customize the @ResponseBody Rendering Spring uses `HttpMessageConverters` to render `@ResponseBody` (or responses from `@RestController`). You can contribute additional converters by adding beans of the appropriate type in a Spring Boot context. @@ -1096,7 +1096,7 @@ See the {spring-boot-autoconfigure-module-code}/web/servlet/WebMvcAutoConfigurat -[[howto-multipart-file-upload-configuration]] +[[howto.spring-mvc.multipart-file-uploads]] === Handling Multipart File Uploads Spring Boot embraces the Servlet 3 `javax.servlet.http.Part` API to support uploading files. By default, Spring Boot configures Spring MVC with a maximum size of 1MB per file and a maximum of 10MB of file data in a single request. @@ -1111,7 +1111,7 @@ NOTE: It is recommended to use the container's built-in support for multipart up -[[howto-switch-off-the-spring-mvc-dispatcherservlet]] +[[howto.spring-mvc.switch-off-dispatcherservlet]] === Switch Off the Spring MVC DispatcherServlet By default, all content is served from the root of your application (`/`). If you would rather map to a different path, you can configure one as follows: @@ -1131,14 +1131,14 @@ Configuring the `DispatcherServlet` yourself is unusual but if you really need t -[[howto-switch-off-default-mvc-configuration]] +[[howto.spring-mvc.switch-off-default-configuration]] === Switch off the Default MVC Configuration The easiest way to take complete control over MVC configuration is to provide your own `@Configuration` with the `@EnableWebMvc` annotation. Doing so leaves all MVC configuration in your hands. -[[howto-customize-view-resolvers]] +[[howto.spring-mvc.customize-view-resolvers]] === Customize ViewResolvers A `ViewResolver` is a core component of Spring MVC, translating view names in `@Controller` to actual `View` implementations. Note that `ViewResolvers` are mainly used in UI applications, rather than REST-style services (a `View` is not used to render a `@ResponseBody`). @@ -1189,7 +1189,7 @@ For more detail, see the following sections: -[[howto-use-test-with-spring-security]] +[[howto.testing-with-spring-security]] == Testing With Spring Security Spring Security provides support for running tests as a specific user. For example, the test in the snippet below will run with an authenticated user that has the `ADMIN` role. @@ -1211,12 +1211,12 @@ For additional details on Spring Security's testing support, refer to Spring Sec -[[howto-jersey]] +[[howto.jersey]] == Jersey -[[howto-jersey-spring-security]] +[[howto.jersey.spring-security]] === Secure Jersey endpoints with Spring Security Spring Security can be used to secure a Jersey-based web application in much the same way as it can be used to secure a Spring MVC-based web application. However, if you want to use Spring Security's method-level security with Jersey, you must configure Jersey to use `setStatus(int)` rather `sendError(int)`. @@ -1231,7 +1231,7 @@ include::{include-howto}/jersey/JerseySetStatusOverSendErrorConfig.java[tag=*] -[[howto-jersey-alongside-another-web-framework]] +[[howto.jersey.alongside-another-web-framework]] === Use Jersey Alongside Another Web Framework To use Jersey alongside another web framework, such as Spring MVC, it should be configured so that it will allow the other framework to handle requests that it cannot handle. First, configure Jersey to use a Filter rather than a Servlet by configuring the configprop:spring.jersey.type[] application property with a value of `filter`. @@ -1252,16 +1252,16 @@ Second, configure your `ResourceConfig` to forward requests that would have resu -[[howto-http-clients]] +[[howto.http-clients]] == HTTP Clients Spring Boot offers a number of starters that work with HTTP clients. This section answers questions related to using them. -[[howto-http-clients-proxy-configuration]] +[[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. @@ -1274,7 +1274,7 @@ include::{include-springbootfeatures}/resttemplate/RestTemplateProxyCustomizer.j -[[howto-webclient-reactor-netty-customization]] +[[howto.http-clients.webclient-reactor-netty-customization]] === Configure the TcpClient used by a Reactor Netty-based WebClient When Reactor Netty is on the classpath a Reactor Netty-based `WebClient` is auto-configured. To customize the client's handling of network connections, provide a `ClientHttpConnector` bean. @@ -1290,7 +1290,7 @@ This ensures efficient sharing of resources for the server receiving requests an -[[howto-logging]] +[[howto.logging]] == Logging Spring Boot has no mandatory logging dependency, except for the Commons Logging API, which is typically provided by Spring Framework's `spring-jcl` module. To use https://logback.qos.ch[Logback], you need to include it and `spring-jcl` on the classpath. @@ -1326,11 +1326,11 @@ By default, Spring Boot picks up the native configuration from its default locat -[[howto-configure-logback-for-logging]] +[[howto.logging.logback]] === 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. @@ -1379,7 +1379,7 @@ Any `logback-spring.groovy` files will not be detected. -[[howto-configure-logback-for-logging-fileonly]] +[[howto.logging.logback.file-only-output]] ==== Configure Logback for File-only Output If you want to disable console logging and write output only to a file, you need a custom `logback-spring.xml` that imports `file-appender.xml` but not `console-appender.xml`, as shown in the following example: @@ -1407,7 +1407,7 @@ You also need to add `logging.file.name` to your `application.properties` or `ap -[[howto-configure-log4j-for-logging]] +[[howto.logging.log4j]] === Configure Log4j for Logging Spring Boot supports https://logging.apache.org/log4j/2.x/[Log4j 2] for logging configuration if it is on the classpath. If you use the starters for assembling dependencies, you have to exclude Logback and then include log4j 2 instead. @@ -1462,7 +1462,7 @@ NOTE: To ensure that debug logging performed using `java.util.logging` is routed -[[howto-configure-log4j-for-logging-yaml-or-json-config]] +[[howto.logging.log4j.yaml-or-json-config]] ==== Use YAML or JSON to Configure Log4j 2 In addition to its default XML configuration format, Log4j 2 also supports YAML and JSON configuration files. To configure Log4j 2 to use an alternative configuration file format, add the appropriate dependencies to the classpath and name your configuration files to match your chosen file format, as shown in the following example: @@ -1482,18 +1482,18 @@ To configure Log4j 2 to use an alternative configuration file format, add the ap -[[howto-data-access]] +[[howto.data-access]] == Data Access Spring Boot includes a number of starters for working with data sources. This section answers questions related to doing so. -[[howto-configure-a-datasource]] +[[howto.data-access.configure-custom-datasource]] === 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,11 +1601,11 @@ 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. -[[howto-two-datasources]] +[[howto.data-access.configure-two-datasources]] === Configure Two DataSources If you need to configure multiple data sources, you can apply the same tricks that are described in the previous section. You must, however, mark one of the `DataSource` instances as `@Primary`, because various auto-configurations down the road expect to be able to get one by type. @@ -1653,7 +1653,7 @@ Note that each `configuration` sub namespace provides advanced settings based on -[[howto-use-spring-data-repositories]] +[[howto.data-access.spring-data-repositories]] === Use Spring Data Repositories Spring Data can create implementations of `@Repository` interfaces of various flavors. Spring Boot handles all of that for you, as long as those `@Repositories` are included in the same package (or a sub-package) of your `@EnableAutoConfiguration` class. @@ -1669,7 +1669,7 @@ For more about Spring Data, see the {spring-data}[Spring Data project page]. -[[howto-separate-entity-definitions-from-spring-configuration]] +[[howto.data-access.separate-entity-definitions-from-spring-configuration]] === Separate @Entity Definitions from Spring Configuration Spring Boot tries to guess the location of your `@Entity` definitions, based on the `@EnableAutoConfiguration` it finds. To get more control, you can use the `@EntityScan` annotation, as shown in the following example: @@ -1688,7 +1688,7 @@ To get more control, you can use the `@EntityScan` annotation, as shown in the f -[[howto-configure-jpa-properties]] +[[howto.data-access.jpa-properties]] === Configure JPA Properties Spring Data JPA already provides some vendor-independent configuration options (such as those for SQL logging), and Spring Boot exposes those options and a few more for Hibernate as external configuration properties. Some of them are automatically detected according to the context so you should not have to set them. @@ -1728,7 +1728,7 @@ This takes precedence to anything that is applied by the auto-configuration. -[[howto-configure-hibernate-naming-strategy]] +[[howto.data-access.configure-hibernate-naming-strategy]] === Configure Hibernate Naming Strategy Hibernate uses {hibernate-docs}#naming[two different naming strategies] to map names from the object model to the corresponding database names. The fully qualified class name of the physical and the implicit strategy implementations can be configured by setting the `spring.jpa.hibernate.naming.physical-strategy` and `spring.jpa.hibernate.naming.implicit-strategy` properties, respectively. @@ -1763,7 +1763,7 @@ See {spring-boot-autoconfigure-module-code}/orm/jpa/HibernateJpaAutoConfiguratio -[[howto-configure-hibernate-second-level-caching]] +[[howto.data-access.configure-hibernate-second-level-caching]] === Configure Hibernate Second-Level Caching Hibernate {hibernate-docs}#caching[second-level cache] can be configured for a range of cache providers. Rather than configuring Hibernate to lookup the cache provider again, it is better to provide the one that is available in the context whenever possible. @@ -1782,7 +1782,7 @@ For details, refer to {hibernate-docs}#caching-provider-jcache[the Hibernate use -[[howto-use-dependency-injection-hibernate-components]] +[[howto.data-access.dependency-injection-in-hibernate-components]] === Use Dependency Injection in Hibernate Components By default, Spring Boot registers a `BeanContainer` implementation that uses the `BeanFactory` so that converters and entity listeners can use regular dependency injection. @@ -1790,15 +1790,15 @@ You can disable or tune this behaviour by registering a `HibernatePropertiesCust -[[howto-use-custom-entity-manager]] +[[howto.data-access.use-custom-entity-manager]] === Use a Custom EntityManagerFactory To take full control of the configuration of the `EntityManagerFactory`, you need to add a `@Bean` named '`entityManagerFactory`'. Spring Boot auto-configuration switches off its entity manager in the presence of a bean of that type. -[[howto-use-two-entity-managers]] -[[howto-use-multiple-entity-managers]] +[[howto.data-access.use-multiple-entity-managers]] +[[howto.data-access.use-multiple-entity-managers]] === Using Multiple EntityManagerFactories If you need to use JPA against multiple data sources, you likely need one `EntityManagerFactory` per data source. The `LocalContainerEntityManagerFactoryBean` from Spring ORM allows you to configure an `EntityManagerFactory` for your needs. @@ -1842,7 +1842,7 @@ If you use Spring Data, you need to configure `@EnableJpaRepositories` according -[[howto-use-traditional-persistence-xml]] +[[howto.data-access.use-traditional-persistence-xml]] === Use a Traditional persistence.xml File Spring Boot will not search for or use a `META-INF/persistence.xml` by default. If you prefer to use a traditional `persistence.xml`, you need to define your own `@Bean` of type `LocalEntityManagerFactoryBean` (with an ID of '`entityManagerFactory`') and set the persistence unit name there. @@ -1851,7 +1851,7 @@ See {spring-boot-autoconfigure-module-code}/orm/jpa/JpaBaseConfiguration.java[`J -[[howto-use-spring-data-jpa--and-mongo-repositories]] +[[howto.data-access.use-spring-data-jpa-and-mongo-repositories]] === Use Spring Data JPA and Mongo Repositories Spring Data JPA and Spring Data Mongo can both automatically create `Repository` implementations for you. If they are both present on the classpath, you might have to do some extra configuration to tell Spring Boot which repositories to create. @@ -1865,7 +1865,7 @@ To work with them, change the names of the annotations and flags accordingly. -[[howto-use-customize-spring-datas-web-support]] +[[howto.data-access.customize-spring-data-web-support]] === Customize Spring Data's Web Support Spring Data provides web support that simplifies the use of Spring Data repositories in a web application. Spring Boot provides properties in the `spring.data.web` namespace for customizing its configuration. @@ -1873,7 +1873,7 @@ Note that if you are using Spring Data REST, you must use the properties in the -[[howto-use-exposing-spring-data-repositories-rest-endpoint]] +[[howto.data-access.exposing-spring-data-repositories-as-rest]] === Expose Spring Data Repositories as REST Endpoint Spring Data REST can expose the `Repository` implementations as REST endpoints for you, provided Spring MVC has been enabled for the application. @@ -1886,7 +1886,7 @@ If you need to specify an order, make sure it is higher than 0. -[[howto-configure-a-component-that-is-used-by-JPA]] +[[howto.data-access.configure-a-component-that-is-used-by-jpa]] === Configure a Component that is Used by JPA If you want to configure a component that JPA uses, then you need to ensure that the component is initialized before JPA. When the component is auto-configured, Spring Boot takes care of this for you. @@ -1902,7 +1902,7 @@ include::{include-howto}/dataaccess/ElasticsearchEntityManagerFactoryDependsOnPo -[[howto-configure-jOOQ-with-multiple-datasources]] +[[howto.data-access.configure-jooq-with-multiple-datasources]] === Configure jOOQ with Two DataSources If you need to use jOOQ with multiple data sources, you should create your own `DSLContext` for each one. Refer to {spring-boot-autoconfigure-module-code}/jooq/JooqAutoConfiguration.java[JooqAutoConfiguration] for more details. @@ -1911,7 +1911,7 @@ TIP: In particular, `JooqExceptionTranslator` and `SpringTransactionProvider` ca -[[howto-database-initialization]] +[[howto.data-initialization]] == Database Initialization An SQL database can be initialized in different ways depending on what your stack is. Of course, you can also do it manually, provided the database is a separate process. @@ -1919,7 +1919,7 @@ It is recommended to use a single mechanism for schema generation. -[[howto-initialize-a-database-using-jpa]] +[[howto.data-initialization.using-jpa]] === Initialize a Database Using JPA JPA has features for DDL generation, and these can be set up to run on startup against the database. This is controlled through two external properties: @@ -1930,7 +1930,7 @@ This is controlled through two external properties: -[[howto-initialize-a-database-using-hibernate]] +[[howto.data-initialization.using-hibernate]] === Initialize a Database Using Hibernate You can set `spring.jpa.hibernate.ddl-auto` explicitly and the standard Hibernate property values are `none`, `validate`, `update`, `create`, and `create-drop`. Spring Boot chooses a default value for you based on whether it thinks your database is embedded. @@ -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. @@ -1949,7 +1949,7 @@ It is a Hibernate feature (and has nothing to do with Spring). -[[howto-initialize-a-database-using-basic-scripts]] +[[howto.data-initialization.using-basic-sql-scripts]] === Initialize a Database Using Basic SQL Scripts Spring Boot can automatically create the schema (DDL scripts) of your JDBC `DataSource` or R2DBC `ConnectionFactory` and initialize it (DML scripts). It loads SQL from the standard root classpath locations: `schema.sql` and `data.sql`, respectively. @@ -1967,12 +1967,12 @@ 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. -[[howto-initialize-a-spring-batch-database]] +[[howto.data-initialization.batch]] === Initialize a Spring Batch Database If you use Spring Batch, it comes pre-packaged with SQL initialization scripts for most popular database platforms. Spring Boot can detect your database type and execute those scripts on startup. @@ -1991,13 +1991,13 @@ You can also switch off the initialization explicitly by setting `spring.batch.j -[[howto-use-a-higher-level-database-migration-tool]] +[[howto.data-initialization.migration-tool]] === Use a Higher-level Database Migration Tool Spring Boot supports two higher-level migration tools: https://flywaydb.org/[Flyway] and https://www.liquibase.org/[Liquibase]. -[[howto-execute-flyway-database-migrations-on-startup]] +[[howto.data-initialization.migration-tool.flyway]] ==== Execute Flyway Database Migrations on Startup To automatically run Flyway database migrations on startup, add the `org.flywaydb:flyway-core` to your classpath. @@ -2065,7 +2065,7 @@ With that setup, migrations in `dev/db/migration` run only when the `dev` profil -[[howto-execute-liquibase-database-migrations-on-startup]] +[[howto.data-initialization.migration-tool.liquibase]] ==== Execute Liquibase Database Migrations on Startup To automatically run Liquibase database migrations on startup, add the `org.liquibase:liquibase-core` to your classpath. @@ -2090,7 +2090,7 @@ See {spring-boot-autoconfigure-module-code}/liquibase/LiquibaseProperties.java[` -[[howto-initialize-a-database-configuring-dependencies]] +[[howto.data-initialization.dependencies]] === Depend Upon an Initialized Database Database initialization is performed while the application is starting up as part of application context refresh. To allow an initialized database to be accessed during startup, beans that act as database initializers and beans that require that database to have been initialized are detected automatically. @@ -2099,7 +2099,7 @@ If, during startup, your application tries to access the database and it has not -[[howto-initialize-a-database-configuring-dependencies-initializer-detection]] +[[howto.data-initialization.dependencies.initializer-detection]] ==== Detect a Database Initializer Spring Boot will automatically detect beans of the following types that initialize an SQL database: @@ -2115,7 +2115,7 @@ To have other beans be detected, register an implementation of `DatabaseInitiali -[[howto-initialize-a-database-configuring-dependencies-depends-on-initialization-detection]] +[[howto.data-initialization.dependencies.depends-on-initialization-detection]] ==== Detect a Bean That Depends On Database Initialization Spring Boot will automatically detect beans of the following types that depends upon database initialization: @@ -2131,14 +2131,14 @@ Alternatively, annotate the bean's class or its `@Bean` method with `@DependsOnD -[[howto-messaging]] +[[howto.messaging]] == Messaging Spring Boot offers a number of starters that include messaging. This section answers questions that arise from using messaging with Spring Boot. -[[howto-jms-disable-transaction]] +[[howto.messaging.disable-transacted-jms-session]] === Disable Transacted JMS Session If your JMS broker does not support transacted sessions, you have to disable the support of transactions altogether. If you create your own `JmsListenerContainerFactory`, there is nothing to do, since, by default it cannot be transacted. @@ -2163,14 +2163,14 @@ The preceding example overrides the default factory, and it should be applied to -[[howto-batch-applications]] +[[howto.batch]] == Batch Applications A number of questions often arise when people use Spring Batch from within a Spring Boot application. This section addresses those questions. -[[howto-spring-batch-specifying-a-data-source]] +[[howto.batch.specifying-a-data-source]] === Specifying a Batch Data Source By default, batch applications require a `DataSource` to store job details. Spring Batch expects a single `DataSource` by default. @@ -2183,7 +2183,7 @@ For more info about Spring Batch, see the {spring-batch}[Spring Batch project pa -[[howto-spring-batch-running-jobs-on-startup]] +[[howto.batch.running-jobs-on-startup]] === Running Spring Batch Jobs on Startup Spring Batch auto-configuration is enabled by adding `@EnableBatchProcessing` to one of your `@Configuration` classes. @@ -2194,9 +2194,9 @@ See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[Ba -[[howto-spring-batch-running-command-line]] +[[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: @@ -2217,7 +2217,7 @@ This provides only one argument to the batch job: `someParameter=someValue`. -[[howto-spring-batch-storing-job-repository]] +[[howto.batch.storing-job-repository]] === Storing the Job Repository Spring Batch requires a data store for the `Job` repository. If you use Spring Boot, you must use an actual database. @@ -2225,24 +2225,24 @@ Note that it can be an in-memory database, see {spring-batch-docs}job.html#confi -[[howto-actuator]] +[[howto.actuator]] == Actuator Spring Boot includes the Spring Boot Actuator. This section answers questions that often arise from its use. -[[howto-change-the-http-port-or-address-of-the-actuator-endpoints]] +[[howto.actuator.change-http-port-or-address]] === Change the HTTP Port or Address of the Actuator Endpoints In a standalone application, the Actuator HTTP port defaults to the same as the main HTTP port. 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. -[[howto-customize-the-whitelabel-error-page]] +[[howto.actuator.customize-whitelabel-error-page]] === Customize the '`whitelabel`' Error Page Spring Boot installs a '`whitelabel`' error page that you see in a browser client if you encounter a server error (machine clients consuming JSON and other media types should see a sensible response with the right error code). @@ -2257,12 +2257,12 @@ 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. -[[howto-sanitize-sensible-values]] -[[howto-sanitize-sensitive-values]] +[[howto.actuator.sanitize-sensitive-values]] +[[howto.actuator.sanitize-sensitive-values]] === Sanitize Sensitive Values Information returned by the `env` and `configprops` endpoints can be somewhat sensitive so keys matching certain patterns are sanitized by default (i.e. their values are replaced by `+******+`). Spring Boot uses sensible defaults for such keys: any key ending with the word "password", "secret", "key", "token", "vcap_services", "sun.java.command" is entirely sanitized. Additionally, any key that holds the word `credentials` (configured as a regular expression, i.e. `+*credentials.*+`) as part of the key is also entirely sanitized. @@ -2285,7 +2285,7 @@ Alternatively, additional patterns can be configured using configprop:management -[[howto-map-health-indicators-to-metrics]] +[[howto.actuator.map-health-indicators-to-metrics]] === Map Health Indicators to Micrometer Metrics Spring Boot health indicators return a `Status` type to indicate the overall system health. If you want to monitor or alert on levels of health for a particular application, you can export these statuses as metrics via Micrometer. @@ -2301,7 +2301,7 @@ include::{include-howto}/actuator/MetricsHealthMicrometerExport.java[tag=*] -[[howto-security]] +[[howto.security]] == Security This section addresses questions about security when working with Spring Boot, including questions that arise from using Spring Security with Spring Boot. @@ -2309,13 +2309,13 @@ For more about Spring Security, see the {spring-security}[Spring Security projec -[[howto-switch-off-spring-boot-security-configuration]] +[[howto.security.switch-off-spring-boot-configuration]] === Switch off the Spring Boot Security Configuration If you define a `@Configuration` with a `WebSecurityConfigurerAdapter` or a `SecurityFilterChain` bean in your application, it switches off the default webapp security settings in Spring Boot. -[[howto-change-the-user-details-service-and-add-user-accounts]] +[[howto.security.change-user-details-service-and-add-user-accounts]] === Change the UserDetailsService and Add User Accounts If you provide a `@Bean` of type `AuthenticationManager`, `AuthenticationProvider`, or `UserDetailsService`, the default `@Bean` for `InMemoryUserDetailsManager` is not created. This means you have the full feature set of Spring Security available (such as {spring-security-docs}#servlet-authentication[various authentication options]). @@ -2324,7 +2324,7 @@ The easiest way to add user accounts is to provide your own `UserDetailsService` -[[howto-enable-https]] +[[howto.security.enable-https]] === Enable HTTPS When Running behind a Proxy Server Ensuring that all your main endpoints are only available over HTTPS is an important chore for any application. If you use Tomcat as a servlet container, then Spring Boot adds Tomcat's own `RemoteIpValve` automatically if it detects some environment settings, and you should be able to rely on the `HttpServletRequest` to report whether it is secure or not (even downstream of a proxy server that handles the real SSL termination). @@ -2357,22 +2357,22 @@ To configure Spring Security to require a secure channel for all (or some) reque -[[howto-hotswapping]] +[[howto.hotswapping]] == Hot Swapping Spring Boot supports hot swapping. This section answers questions about how it works. -[[howto-reload-static-content]] +[[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). @@ -2382,59 +2382,59 @@ You can use that with an external css/js compiler process if you are writing tha -[[howto-reload-thymeleaf-template-content]] +[[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. -[[howto-reload-thymeleaf-content]] +[[howto.hotswapping.reload-templates.thymeleaf]] ==== Thymeleaf Templates If you use Thymeleaf, set `spring.thymeleaf.cache` to `false`. See {spring-boot-autoconfigure-module-code}/thymeleaf/ThymeleafAutoConfiguration.java[`ThymeleafAutoConfiguration`] for other Thymeleaf customization options. -[[howto-reload-freemarker-content]] +[[howto.hotswapping.reload-templates.freemarker]] ==== FreeMarker Templates If you use FreeMarker, set `spring.freemarker.cache` to `false`. See {spring-boot-autoconfigure-module-code}/freemarker/FreeMarkerAutoConfiguration.java[`FreeMarkerAutoConfiguration`] for other FreeMarker customization options. -[[howto-reload-groovy-template-content]] +[[howto.hotswapping.reload-templates.groovy]] ==== Groovy Templates If you use Groovy templates, set `spring.groovy.template.cache` to `false`. See {spring-boot-autoconfigure-module-code}/groovy/template/GroovyTemplateAutoConfiguration.java[`GroovyTemplateAutoConfiguration`] for other Groovy customization options. -[[howto-reload-fast-restart]] +[[howto.hotswapping.fast-application-restarts]] === Fast Application Restarts The `spring-boot-devtools` module includes support for automatic application restarts. 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. -[[howto-reload-java-classes-without-restarting]] +[[howto.hotswapping.reload-java-classes-without-restarting]] === Reload Java Classes without Restarting the Container Many modern IDEs (Eclipse, IDEA, and others) support hot swapping of bytecode. Consequently, if you make a change that does not affect class or method signatures, it should reload cleanly with no side effects. -[[howto-build]] +[[howto.build]] == Build Spring Boot includes build plugins for Maven and Gradle. This section answers common questions about these plugins. -[[howto-build-info]] +[[howto.build.generate-info]] === Generate Build Information Both the Maven plugin and the Gradle plugin allow generating build information containing the coordinates, name, and version of the project. The plugins can also be configured to add additional properties through configuration. @@ -2477,7 +2477,7 @@ TIP: See the {spring-boot-gradle-plugin-docs}#integrating-with-actuator-build-in -[[howto-git-info]] +[[howto.build.generate-git-info]] === Generate Git Information Both Maven and Gradle allow generating a `git.properties` file containing information about the state of your `git` source code repository when the project was built. @@ -2513,7 +2513,7 @@ Using this format lets the time be parsed into a `Date` and its format, when ser -[[howto-customize-dependency-versions]] +[[howto.build.customize-dependency-versions]] === Customize Dependency Versions The `spring-boot-dependencies` POM manages the versions of common dependencies. The Spring Boot plugins for Maven and Gradle allow these managed dependency versions to be customized using build properties. @@ -2527,7 +2527,7 @@ To override dependency versions in Gradle, see {spring-boot-gradle-plugin-docs}# -[[howto-create-an-executable-jar-with-maven]] +[[howto.build.create-an-executable-jar-with-maven]] === Create an Executable JAR with Maven The `spring-boot-maven-plugin` can be used to create an executable "`fat`" JAR. If you use the `spring-boot-starter-parent` POM, you can declare the plugin and your jars are repackaged as follows: @@ -2571,14 +2571,14 @@ See the {spring-boot-maven-plugin-docs}#repackage[plugin documentation] for full -[[howto-create-an-additional-executable-jar]] +[[howto.build.use-a-spring-boot-application-as-dependency]] === Use a Spring Boot Application as a Dependency Like a war file, a Spring Boot application is not intended to be used as a dependency. If your application contains classes that you want to share with other projects, the recommended approach is to move that code into a separate module. 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. @@ -2603,7 +2603,7 @@ To configure a classifier of `exec` in Maven, you can use the following configur -[[howto-extract-specific-libraries-when-an-executable-jar-runs]] +[[howto.build.extract-specific-libraries-when-an-executable-jar-runs]] === Extract Specific Libraries When an Executable Jar Runs Most nested libraries in an executable jar do not need to be unpacked in order to run. However, certain libraries can have problems. @@ -2638,7 +2638,7 @@ For example, to indicate that JRuby should be flagged for unpacking by using the -[[howto-create-a-nonexecutable-jar]] +[[howto.build.create-a-nonexecutable-jar]] === Create a Non-executable JAR with Exclusions Often, if you have an executable and a non-executable jar as two separate build products, the executable version has additional configuration files that are not needed in a library jar. For example, the `application.yml` configuration file might be excluded from the non-executable JAR. @@ -2677,7 +2677,7 @@ In Maven, the executable jar must be the main artifact and you can add a classif -[[howto-remote-debug-maven-run]] +[[howto.build.remote-debug-maven]] === Remote Debug a Spring Boot Application Started with Maven To attach a remote debugger to a Spring Boot application that was started with Maven, you can use the `jvmArguments` property of the {spring-boot-maven-plugin-docs}[maven plugin]. @@ -2685,7 +2685,7 @@ See {spring-boot-maven-plugin-docs}#run-example-debug[this example] for more det -[[howto-build-an-executable-archive-with-ant]] +[[howto.build.build-an-executable-archive-with-ant-without-using-spring-boot-antlib]] === Build an Executable Archive from Ant without Using spring-boot-antlib To build with Ant, you need to grab dependencies, compile, and then create a jar or war archive. To make it executable, you can either use the `spring-boot-antlib` module or you can follow these instructions: @@ -2728,14 +2728,14 @@ The following example shows how to build an executable archive with Ant: -[[howto-traditional-deployment]] +[[howto.traditional-deployment]] == Traditional Deployment Spring Boot supports traditional deployment as well as more modern forms of deployment. This section answers common questions about traditional deployment. -[[howto-create-a-deployable-war-file]] +[[howto.howto.traditional-deployment.war]] === Create a Deployable War File WARNING: Because Spring WebFlux does not strictly depend on the Servlet API and applications are deployed by default on an embedded Reactor Netty server, War deployment is not supported for WebFlux applications. @@ -2813,7 +2813,7 @@ This means that, in addition to being deployable to a servlet container, you can -[[howto-convert-an-existing-application-to-spring-boot]] +[[howto.howto.traditional-deployment.convert-existing-application]] === Convert an Existing Application to Spring Boot To convert an existing non-web Spring application to a Spring Boot application, replace the code that creates your `ApplicationContext` and replace it with calls to `SpringApplication` or `SpringApplicationBuilder`. Spring MVC web applications are generally amenable to first creating a deployable war application and then migrating it later to an executable war or jar. @@ -2900,7 +2900,7 @@ Servlet 3.0+ applications might translate pretty easily if they already use the Normally, all the code from an existing `WebApplicationInitializer` can be moved into a `SpringBootServletInitializer`. If your existing application has more than one `ApplicationContext` (for example, if it uses `AbstractDispatcherServletInitializer`) then you might be able to combine all your context sources into a single `SpringApplication`. The main complication you might encounter is if combining does not work and you need to maintain the context hierarchy. -See the <> for examples. +See the <> for examples. An existing parent context that contains web-specific features usually needs to be broken up so that all the `ServletContextAware` components are in the child context. Applications that are not already Spring applications might be convertible to Spring Boot applications, and the previously mentioned guidance may help. @@ -2909,7 +2909,7 @@ In that case, we suggest https://stackoverflow.com/questions/tagged/spring-boot[ -[[howto-weblogic]] +[[howto.howto.traditional-deployment.weblogic]] === Deploying a WAR to WebLogic To deploy a Spring Boot application to WebLogic, you must ensure that your servlet initializer *directly* implements `WebApplicationInitializer` (even if you extend from a base class that already implements it). @@ -2950,7 +2950,7 @@ You can do so by adding a `WEB-INF/weblogic.xml` file with the following content -[[howto-use-jedis-instead-of-lettuce]] +[[howto.howto.traditional-deployment.jedis-instead-of-lettuce]] === Use Jedis Instead of Lettuce By default, the Spring Boot starter (`spring-boot-starter-data-redis`) uses https://github.com/lettuce-io/lettuce-core/[Lettuce]. You need to exclude that dependency and include the https://github.com/xetorthio/jedis/[Jedis] one instead. @@ -2991,7 +2991,7 @@ The following example shows how to do so in Gradle: -[[howto-testcontainers]] +[[howto.howto.traditional-deployment.testcontainers]] === Use Testcontainers for integration testing The https://www.testcontainers.org/[Testcontainers] library provides a way to manage services running inside Docker containers. It integrates with JUnit, allowing you to write a test class that can start up a container before any of the tests run. 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 b1d68bb692..234f8703a1 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 @@ -1,4 +1,4 @@ -[[spring-boot-reference-documentation]] +[[index]] = Spring Boot Reference Documentation include::authors.adoc[] :docinfo: shared @@ -10,11 +10,11 @@ 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. <> :: Maven Plugin, Gradle Plugin, Antlib, and more. 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/production-ready-features.adoc index 6a83924866..cd596bebc9 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/production-ready-features.adoc @@ -1,4 +1,4 @@ -[[production-ready]] +[[actuator]] = Spring Boot Actuator: Production-ready Features include::attributes.adoc[] @@ -8,7 +8,7 @@ Auditing, health, and metrics gathering can also be automatically applied to you -[[production-ready-enabling]] +[[actuator.enabling]] == Enabling Production-ready Features The {spring-boot-code}/spring-boot-project/spring-boot-actuator[`spring-boot-actuator`] module provides all of Spring Boot's production-ready features. The recommended way to enable the features is to add a dependency on the `spring-boot-starter-actuator` '`Starter`'. @@ -42,13 +42,13 @@ For Gradle, use the following declaration: -[[production-ready-endpoints]] +[[actuator.endpoints]] == Endpoints Actuator endpoints let you monitor and interact with your application. Spring Boot includes a number of built-in endpoints and lets you add your own. For example, the `health` endpoint provides basic application health information. -Each individual endpoint can be <> and <>. +Each individual endpoint can be <> and <>. An endpoint is considered to be available when it is both enabled and exposed. The built-in endpoints will only be auto-configured when they are available. Most applications choose exposure via HTTP, where the ID of the endpoint along with a prefix of `/actuator` is mapped to a URL. @@ -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` @@ -158,7 +158,7 @@ If your application is a web application (Spring MVC, Spring WebFlux, or Jersey) -[[production-ready-endpoints-enabling-endpoints]] +[[actuator.endpoints.enabling]] === Enabling Endpoints By default, all endpoints except for `shutdown` are enabled. To configure the enablement of an endpoint, use its `management.endpoint..enabled` property. @@ -186,11 +186,11 @@ The following example enables the `info` endpoint and disables all other endpoin ---- NOTE: Disabled endpoints are removed entirely from the application context. -If you want to change only the technologies over which an endpoint is exposed, use the <> instead. +If you want to change only the technologies over which an endpoint is exposed, use the <> instead. -[[production-ready-endpoints-exposing-endpoints]] +[[actuator.endpoints.exposing]] === Exposing Endpoints Since Endpoints may contain sensitive information, careful consideration should be given about when to expose them. The following table shows the default exposure for the built-in endpoints: @@ -350,13 +350,13 @@ For example, to expose everything over HTTP except the `env` and `beans` endpoin NOTE: `*` has a special meaning in YAML, so be sure to add quotes if you want to include (or exclude) all endpoints. -NOTE: If your application is exposed publicly, we strongly recommend that you also <>. +NOTE: If your application is exposed publicly, we strongly recommend that you also <>. TIP: If you want to implement your own strategy for when endpoints are exposed, you can register an `EndpointFilter` bean. -[[production-ready-endpoints-security]] +[[actuator.endpoints.security]] === Securing HTTP Endpoints You should take care to secure HTTP endpoints in the same way that you would any other sensitive URL. If Spring Security is present, endpoints are secured by default using Spring Security’s content-negotiation strategy. @@ -408,7 +408,7 @@ Since Spring Boot's security configuration backs off completely in the presence -[[production-ready-endpoints-caching]] +[[actuator.endpoints.caching]] === Configuring Endpoints Endpoints automatically cache responses to read operations that do not take any parameters. To configure the amount of time for which an endpoint will cache a response, use its `cache.time-to-live` property. @@ -427,7 +427,7 @@ NOTE: The prefix `management.endpoint.` is used to uniquely identify the e -[[production-ready-endpoints-hypermedia]] +[[actuator.endpoints.hypermedia]] === Hypermedia for Actuator Web Endpoints A "`discovery page`" is added with links to all the endpoints. The "`discovery page`" is available on `/actuator` by default. @@ -449,7 +449,7 @@ When the management context path is set to `/`, the discovery page is disabled t -[[production-ready-endpoints-cors]] +[[actuator.endpoints.cors]] === CORS Support https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a https://www.w3.org/TR/cors/[W3C specification] that lets you specify in a flexible way what kind of cross-domain requests are authorized. If you use Spring MVC or Spring WebFlux, Actuator's web endpoints can be configured to support such scenarios. @@ -471,7 +471,7 @@ TIP: See {spring-boot-actuator-autoconfigure-module-code}/endpoint/web/CorsEndpo -[[production-ready-endpoints-custom]] +[[actuator.endpoints.implementing-custom]] === Implementing Custom Endpoints If you add a `@Bean` annotated with `@Endpoint`, any methods annotated with `@ReadOperation`, `@WriteOperation`, or `@DeleteOperation` are automatically exposed over JMX and, in a web application, over HTTP as well. Endpoints can be exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux. @@ -495,7 +495,7 @@ Finally, if you need access to web-framework-specific functionality, you can imp -[[production-ready-endpoints-custom-input]] +[[actuator.endpoints.implementing-custom.input]] ==== Receiving Input Operations on an endpoint receive input via their parameters. When exposed via the web, the values for these parameters are taken from the URL's query parameters and from the JSON request body. @@ -529,27 +529,27 @@ This will happen automatically if you are using Spring Boot's Gradle plugin or i -[[production-ready-endpoints-custom-input-conversion]] +[[actuator.endpoints.implementing-custom.input.conversion]] ===== Input Type Conversion The parameters passed to endpoint operation methods are, if necessary, automatically converted to the required type. Before calling an operation method, the input received via JMX or an HTTP request is converted to the required types using an instance of `ApplicationConversionService` as well as any `Converter` or `GenericConverter` beans qualified with `@EndpointConverter`. -[[production-ready-endpoints-custom-web]] +[[actuator.endpoints.implementing-custom.web]] ==== Custom Web Endpoints Operations on an `@Endpoint`, `@WebEndpoint`, or `@EndpointWebExtension` are automatically exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux. If both Jersey and Spring MVC are available, Spring MVC will be used. -[[production-ready-endpoints-custom-web-predicate]] +[[actuator.endpoints.implementing-custom.web.request-predicates]] ===== Web Endpoint Request Predicates A request predicate is automatically generated for each operation on a web-exposed endpoint. -[[production-ready-endpoints-custom-web-predicate-path]] +[[actuator.endpoints.implementing-custom.web.path-predicates]] ===== Path The path of the predicate is determined by the ID of the endpoint and the base path of web-exposed endpoints. The default base path is `/actuator`. @@ -562,7 +562,7 @@ If you want to capture all remaining path elements, you can add `@Selector(Match -[[production-ready-endpoints-custom-web-predicate-http-method]] +[[actuator.endpoints.implementing-custom.web.method-predicates]] ===== HTTP method The HTTP method of the predicate is determined by the operation type, as shown in the following table: @@ -582,14 +582,14 @@ The HTTP method of the predicate is determined by the operation type, as shown i -[[production-ready-endpoints-custom-web-predicate-consumes]] +[[actuator.endpoints.implementing-custom.web.consumes-predicates]] ===== Consumes For a `@WriteOperation` (HTTP `POST`) that uses the request body, the consumes clause of the predicate is `application/vnd.spring-boot.actuator.v2+json, application/json`. For all other operations the consumes clause is empty. -[[production-ready-endpoints-custom-web-predicate-produces]] +[[actuator.endpoints.implementing-custom.web.produces-predicates]] ===== Produces The produces clause of the predicate can be determined by the `produces` attribute of the `@DeleteOperation`, `@ReadOperation`, and `@WriteOperation` annotations. The attribute is optional. @@ -601,7 +601,7 @@ For all other operations the produces clause is `application/vnd.spring-boot.act -[[production-ready-endpoints-custom-web-response-status]] +[[actuator.endpoints.implementing-custom.web.response-status]] ===== Web Endpoint Response Status The default response status for an endpoint operation depends on the operation type (read, write, or delete) and what, if anything, the operation returns. @@ -615,7 +615,7 @@ If an operation is invoked without a required parameter, or with a parameter tha -[[production-ready-endpoints-custom-web-range-requests]] +[[actuator.endpoints.implementing-custom.web.range-requests]] ===== Web Endpoint Range Requests An HTTP range request can be used to request part of an HTTP resource. When using Spring MVC or Spring Web Flux, operations that return a `org.springframework.core.io.Resource` automatically support range requests. @@ -624,7 +624,7 @@ NOTE: Range requests are not supported when using Jersey. -[[production-ready-endpoints-custom-web-security]] +[[actuator.endpoints.implementing-custom.web.security]] ===== Web Endpoint Security An operation on a web endpoint or a web-specific endpoint extension can receive the current `java.security.Principal` or `org.springframework.boot.actuate.endpoint.SecurityContext` as a method parameter. The former is typically used in conjunction with `@Nullable` to provide different behavior for authenticated and unauthenticated users. @@ -632,7 +632,7 @@ The latter is typically used to perform authorization checks using its `isUserIn -[[production-ready-endpoints-custom-servlet]] +[[actuator.endpoints.implementing-custom.servlet]] ==== Servlet Endpoints A `Servlet` can be exposed as an endpoint by implementing a class annotated with `@ServletEndpoint` that also implements `Supplier`. Servlet endpoints provide deeper integration with the Servlet container but at the expense of portability. @@ -641,7 +641,7 @@ For new endpoints, the `@Endpoint` and `@WebEndpoint` annotations should be pref -[[production-ready-endpoints-custom-controller]] +[[actuator.endpoints.implementing-custom.controller]] ==== Controller Endpoints `@ControllerEndpoint` and `@RestControllerEndpoint` can be used to implement an endpoint that is only exposed by Spring MVC or Spring WebFlux. Methods are mapped using the standard annotations for Spring MVC and Spring WebFlux such as `@RequestMapping` and `@GetMapping`, with the endpoint's ID being used as a prefix for the path. @@ -650,7 +650,7 @@ The `@Endpoint` and `@WebEndpoint` annotations should be preferred whenever poss -[[production-ready-health]] +[[actuator.endpoints.health]] === Health Information You can use health information to check the status of your running application. It is often used by monitoring software to alert someone when a production system goes down. @@ -694,7 +694,7 @@ TIP: The `HealthContributorRegistry` can be used to register and unregister heal -[[production-ready-health-indicators]] +[[actuator.endpoints.health.auto-configured-health-indicators]] ==== Auto-configured HealthIndicators The following `HealthIndicators` are auto-configured by Spring Boot when appropriate. You can also enable/disable selected indicators by configuring `management.health.key.enabled`, @@ -788,7 +788,7 @@ Additional `HealthIndicators` are available but not enabled by default: -[[production-ready-health-indicators-writing]] +[[actuator.endpoints.health.writing-custom-health-indicators]] ==== Writing Custom HealthIndicators To provide custom health information, you can register Spring beans that implement the {spring-boot-actuator-module-code}/health/HealthIndicator.java[`HealthIndicator`] interface. You need to provide an implementation of the `health()` method and return a `Health` response. @@ -877,7 +877,7 @@ The following table shows the default status mappings for the built-in statuses: -[[reactive-health-indicators]] +[[actuator.endpoints.health.reactive-health-indicators]] ==== Reactive Health Indicators For reactive applications, such as those using Spring WebFlux, `ReactiveHealthContributor` provides a non-blocking contract for getting application health. Similar to a traditional `HealthContributor`, health information is collected from the content of a {spring-boot-actuator-module-code}/health/ReactiveHealthContributorRegistry.java[`ReactiveHealthContributorRegistry`] (by default all {spring-boot-actuator-module-code}/health/HealthContributor.java[`HealthContributor`] and {spring-boot-actuator-module-code}/health/ReactiveHealthContributor.java[`ReactiveHealthContributor`] instances defined in your `ApplicationContext`). @@ -907,7 +907,7 @@ TIP: To handle the error automatically, consider extending from `AbstractReactiv -[[reactive-health-indicators-autoconfigured]] +[[actuator.endpoints.health.auto-configured-reactive-health-indicators]] ==== Auto-configured ReactiveHealthIndicators The following `ReactiveHealthIndicators` are auto-configured by Spring Boot when appropriate: @@ -939,7 +939,7 @@ Also, any `HealthIndicator` that is not handled explicitly is wrapped automatica -[[production-ready-health-groups]] +[[actuator.endpoints.health.groups]] ==== Health Groups It's sometimes useful to organize health indicators into groups that can be used for different purposes. @@ -993,7 +993,7 @@ TIP: You can use `@Qualifier("groupname")` if you need to register custom `Statu -[[production-ready-health-datasource]] +[[actuator.endpoints.health.datasource]] ==== DataSource Health The `DataSource` health indicator shows the health of both standard data source and routing data source beans. The health of a routing data source includes the health of each of its target data sources. @@ -1002,15 +1002,15 @@ If you prefer not to include routing data sources in the indicator's output, set -[[production-ready-kubernetes-probes]] +[[actuator.endpoints.kubernetes-probes]] === Kubernetes Probes 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. -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`. +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"`. +They will also be exposed as separate HTTP Probes using <>: `"/actuator/health/liveness"` and `"/actuator/health/readiness"`. You can then configure your Kubernetes infrastructure with the following endpoint information: @@ -1034,20 +1034,20 @@ readinessProbe: NOTE: `` should be set to the port that the actuator endpoints are available on. It could be the main web server port, or a separate management port if the `"management.server.port"` property has been set. -These health groups are only enabled automatically if the application is <>. +These health groups are only enabled automatically if the application is <>. You can enable them in any environment using the configprop:management.endpoint.health.probes.enabled[] configuration property. NOTE: If an application takes longer to start than the configured liveness period, Kubernetes mention the `"startupProbe"` as a possible solution. -The `"startupProbe"` is not necessarily needed here as the `"readinessProbe"` fails until all startup tasks are done, see <>. +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). -[[production-ready-kubernetes-probes-external-state]] +[[actuator.endpoints.kubernetes-probes.external-state]] ==== Checking External State with Kubernetes Probes -Actuator configures the "liveness" and "readiness" probes as Health Groups; this means that all the <> are available for them. +Actuator configures the "liveness" and "readiness" probes as Health Groups; this means that all the <> are available for them. You can, for example, configure additional Health Indicators: [source,yaml,indent=0,configprops,configblocks] @@ -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. @@ -1082,13 +1082,13 @@ Also, if an application is using Kubernetes https://kubernetes.io/docs/tasks/run -[[production-ready-kubernetes-probes-lifecycle]] +[[actuator.endpoints.kubernetes-probes.lifecycle]] ==== Application Lifecycle and Probe States An important aspect of the Kubernetes Probes support is its consistency with the application lifecycle. 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. @@ -1134,7 +1134,7 @@ When a Spring Boot application shuts down: |`CORRECT` |`REFUSING_TRAFFIC` |New requests are rejected -|If enabled, <>. +|If enabled, <>. |Shutdown complete |N/A @@ -1143,18 +1143,18 @@ When a Spring Boot application shuts down: |The application context is closed and the application is shut down. |=== -TIP: Check out the <> for more information about Kubernetes deployment. +TIP: Check out the <> for more information about Kubernetes deployment. -[[production-ready-application-info]] +[[actuator.endpoints.info]] === Application Information Application information exposes various information collected from all {spring-boot-actuator-module-code}/info/InfoContributor.java[`InfoContributor`] beans defined in your `ApplicationContext`. Spring Boot includes a number of auto-configured `InfoContributor` beans, and you can write your own. -[[production-ready-application-info-autoconfigure]] +[[actuator.endpoints.info.auto-configured-info-contributors]] ==== Auto-configured InfoContributors The following `InfoContributor` beans are auto-configured by Spring Boot, when appropriate: @@ -1176,7 +1176,7 @@ TIP: It is possible to disable them all by setting the configprop:management.inf -[[production-ready-application-info-env]] +[[actuator.endpoints.info.custom-application-information]] ==== Custom Application Information You can customize the data exposed by the `info` endpoint by setting `+info.*+` Spring properties. All `Environment` properties under the `info` key are automatically exposed. @@ -1194,7 +1194,7 @@ For example, you could add the following settings to your `application.propertie [TIP] ==== -Rather than hardcoding those values, you could also <>. +Rather than hardcoding those values, you could also <>. Assuming you use Maven, you could rewrite the preceding example as follows: @@ -1211,13 +1211,13 @@ Assuming you use Maven, you could rewrite the preceding example as follows: -[[production-ready-application-info-git]] +[[actuator.endpoints.info.git-commit-information]] ==== Git Commit Information Another useful feature of the `info` endpoint is its ability to publish information about the state of your `git` source code repository when the project was built. If a `GitProperties` bean is available, the `info` endpoint can be used to expose these properties. TIP: A `GitProperties` bean is auto-configured if a `git.properties` file is available at the root of the classpath. -See "<>" for more details. +See "<>" for more details. By default, the endpoint exposes `git.branch`, `git.commit.id`, and `git.commit.time` properties, if present. If you don't want any of these properties in the endpoint response, they need to be excluded from the `git.properties` file. @@ -1240,17 +1240,17 @@ To disable the git commit information from the `info` endpoint completely, set t -[[production-ready-application-info-build]] +[[actuator.endpoints.info.build-information]] ==== Build Information If a `BuildProperties` bean is available, the `info` endpoint can also publish information about your build. This happens if a `META-INF/build-info.properties` file is available in the classpath. TIP: The Maven and Gradle plugins can both generate that file. -See "<>" for more details. +See "<>" for more details. -[[production-ready-application-info-custom]] +[[actuator.endpoints.info.writing-custom-info-contributors]] ==== Writing Custom InfoContributors To provide custom application information, you can register Spring beans that implement the {spring-boot-actuator-module-code}/info/InfoContributor.java[`InfoContributor`] interface. @@ -1289,7 +1289,7 @@ If you reach the `info` endpoint, you should see a response that contains the fo -[[production-ready-monitoring]] +[[actuator.monitoring]] == Monitoring and Management over HTTP If you are developing a web application, Spring Boot Actuator auto-configures all enabled endpoints to be exposed over HTTP. The default convention is to use the `id` of the endpoint with a prefix of `/actuator` as the URL path. @@ -1302,7 +1302,7 @@ NOTE: Jackson is a required dependency in order to get the correct JSON response -[[production-ready-customizing-management-server-context-path]] +[[actuator.monitoring.customizing-management-server-context-path]] === Customizing the Management Endpoint Paths Sometimes, it is useful to customize the prefix for the management endpoints. For example, your application might already use `/actuator` for another purpose. @@ -1318,7 +1318,7 @@ You can use the configprop:management.endpoints.web.base-path[] property to chan The preceding `application.properties` example changes the endpoint from `/actuator/\{id}` to `/manage/\{id}` (for example, `/manage/info`). -NOTE: Unless the management port has been configured to <>, `management.endpoints.web.base-path` is relative to `server.servlet.context-path` (Servlet web applications) or `spring.webflux.base-path` (reactive web applications). +NOTE: Unless the management port has been configured to <>, `management.endpoints.web.base-path` is relative to `server.servlet.context-path` (Servlet web applications) or `spring.webflux.base-path` (reactive web applications). If `management.server.port` is configured, `management.endpoints.web.base-path` is relative to `management.server.base-path`. If you want to map endpoints to a different path, you can use the configprop:management.endpoints.web.path-mapping[] property. @@ -1337,7 +1337,7 @@ The following example remaps `/actuator/health` to `/healthcheck`: -[[production-ready-customizing-management-server-port]] +[[actuator.monitoring.customizing-management-server-port]] === Customizing the Management Server Port Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments. If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port. @@ -1356,7 +1356,7 @@ If you want to use a custom management port on Cloud Foundry, you will need to e -[[production-ready-management-specific-ssl]] +[[actuator.monitoring.management-specific-ssl]] === Configuring Management-specific SSL When configured to use a custom port, the management server can also be configured with its own SSL by using the various `management.server.ssl.*` properties. For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as shown in the following property settings: @@ -1397,7 +1397,7 @@ Alternatively, both the main server and the management server can use SSL but wi -[[production-ready-customizing-management-server-address]] +[[actuator.monitoring.customizing-management-server-address]] === Customizing the Management Server Address You can customize the address that the management endpoints are available on by setting the configprop:management.server.address[] property. Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections from `localhost`. @@ -1416,7 +1416,7 @@ The following example `application.properties` does not allow remote management -[[production-ready-disabling-http-endpoints]] +[[actuator.monitoring.disabling-http-endpoints]] === Disabling HTTP Endpoints If you do not want to expose endpoints over HTTP, you can set the management port to `-1`, as shown in the following example: @@ -1440,7 +1440,7 @@ This can be achieved using the configprop:management.endpoints.web.exposure.excl -[[production-ready-jmx]] +[[actuator.jmx]] == Monitoring and Management over JMX Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications. By default, this feature is not enabled and can be turned on by setting the configuration property configprop:spring.jmx.enabled[] to `true`. @@ -1449,7 +1449,7 @@ To Take full control over endpoints registration in the JMX domain, consider reg -[[production-ready-custom-mbean-names]] +[[actuator.jmx.custom-mbean-names]] === Customizing MBean Names The name of the MBean is usually generated from the `id` of the endpoint. For example, the `health` endpoint is exposed as `org.springframework.boot:type=Endpoint,name=Health`. @@ -1473,7 +1473,7 @@ The following settings show an example of doing so in `application.properties`: -[[production-ready-disable-jmx-endpoints]] +[[actuator.jmx.disable-jmx-endpoints]] === Disabling JMX Endpoints If you do not want to expose endpoints over JMX, you can set the configprop:management.endpoints.jmx.exposure.exclude[] property to `*`, as shown in the following example: @@ -1488,7 +1488,7 @@ If you do not want to expose endpoints over JMX, you can set the configprop:mana -[[production-ready-jolokia]] +[[actuator.jmx.jolokia]] === Using Jolokia for JMX over HTTP Jolokia is a JMX-HTTP bridge that provides an alternative method of accessing JMX beans. To use Jolokia, include a dependency to `org.jolokia:jolokia-core`. @@ -1511,7 +1511,7 @@ The endpoint will not be available in a WebFlux application. -[[production-ready-customizing-jolokia]] +[[actuator.jmx.jolokia.customizing]] ==== Customizing Jolokia Jolokia has a number of settings that you would traditionally configure by setting servlet parameters. With Spring Boot, you can use your `application.properties` file. @@ -1528,7 +1528,7 @@ To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as sh -[[production-ready-disabling-jolokia]] +[[actuator.jmx.jolokia.disabling]] ==== Disabling Jolokia If you use Jolokia but do not want Spring Boot to configure it, set the configprop:management.endpoint.jolokia.enabled[] property to `false`, as follows: @@ -1542,7 +1542,7 @@ If you use Jolokia but do not want Spring Boot to configure it, set the configpr -[[production-ready-loggers]] +[[actuator.loggers]] == Loggers Spring Boot Actuator includes the ability to view and configure the log levels of your application at runtime. You can view either the entire list or an individual logger's configuration, which is made up of both the explicitly configured logging level as well as the effective logging level given to it by the logging framework. @@ -1561,7 +1561,7 @@ These levels can be one of: -[[production-ready-logger-configuration]] +[[actuator.loggers.configure]] === Configure a Logger To configure a given logger, `POST` a partial entity to the resource's URI, as shown in the following example: @@ -1576,34 +1576,34 @@ TIP: To "`reset`" the specific level of the logger (and use the default configur -[[production-ready-metrics]] +[[actuator.metrics]] == Metrics Spring Boot Actuator provides dependency management and auto-configuration for https://micrometer.io[Micrometer], an application metrics facade that supports {micrometer-docs}[numerous monitoring systems], including: -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> -- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> TIP: To learn more about Micrometer's capabilities, please refer to its https://micrometer.io/docs[reference documentation], in particular the {micrometer-concepts-docs}[concepts section]. -[[production-ready-metrics-getting-started]] +[[actuator.metrics.getting-started]] === Getting started Spring Boot auto-configures a composite `MeterRegistry` and adds a registry to the composite for each of the supported implementations that it finds on the classpath. Having a dependency on `micrometer-registry-\{system}` in your runtime classpath is enough for Spring Boot to configure the registry. @@ -1661,16 +1661,16 @@ You can apply customizations to particular registry implementations by being mor } ---- -Spring Boot also <> that you can control via configuration or dedicated annotation markers. +Spring Boot also <> that you can control via configuration or dedicated annotation markers. -[[production-ready-metrics-export]] +[[actuator.metrics.export]] === Supported Monitoring Systems -[[production-ready-metrics-export-appoptics]] +[[actuator.metrics.export.appoptics]] ==== AppOptics By default, the AppOptics registry pushes metrics to `https://api.appoptics.com/v1/measurements` periodically. To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your API token must be provided: @@ -1686,7 +1686,7 @@ To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your -[[production-ready-metrics-export-atlas]] +[[actuator.metrics.export.atlas]] ==== Atlas By default, metrics are exported to {micrometer-registry-docs}/atlas[Atlas] running on your local machine. The location of the https://github.com/Netflix/atlas[Atlas server] to use can be provided using: @@ -1702,7 +1702,7 @@ The location of the https://github.com/Netflix/atlas[Atlas server] to use can be -[[production-ready-metrics-export-datadog]] +[[actuator.metrics.export.datadog]] ==== Datadog Datadog registry pushes metrics to https://www.datadoghq.com[datadoghq] periodically. To export metrics to {micrometer-registry-docs}/datadog[Datadog], your API key must be provided: @@ -1729,7 +1729,7 @@ You can also change the interval at which metrics are sent to Datadog: -[[production-ready-metrics-export-dynatrace]] +[[actuator.metrics.export.dynatrace]] ==== Dynatrace Dynatrace registry pushes metrics to the configured URI periodically. To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API token, device ID, and URI must be provided: @@ -1758,7 +1758,7 @@ You can also change the interval at which metrics are sent to Dynatrace: -[[production-ready-metrics-export-elastic]] +[[actuator.metrics.export.elastic]] ==== Elastic By default, metrics are exported to {micrometer-registry-docs}/elastic[Elastic] running on your local machine. The location of the Elastic server to use can be provided using the following property: @@ -1774,7 +1774,7 @@ The location of the Elastic server to use can be provided using the following pr -[[production-ready-metrics-export-ganglia]] +[[actuator.metrics.export.ganglia]] ==== Ganglia By default, metrics are exported to {micrometer-registry-docs}/ganglia[Ganglia] running on your local machine. The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be provided using: @@ -1791,7 +1791,7 @@ The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be p -[[production-ready-metrics-export-graphite]] +[[actuator.metrics.export.graphite]] ==== Graphite By default, metrics are exported to {micrometer-registry-docs}/graphite[Graphite] running on your local machine. The https://graphiteapp.org[Graphite server] host and port to use can be provided using: @@ -1821,7 +1821,7 @@ An auto-configured `GraphiteConfig` and `Clock` beans are provided unless you de -[[production-ready-metrics-export-humio]] +[[actuator.metrics.export.humio]] ==== Humio By default, the Humio registry pushes metrics to https://cloud.humio.com periodically. To export metrics to SaaS {micrometer-registry-docs}/humio[Humio], your API token must be provided: @@ -1850,7 +1850,7 @@ You should also configure one or more tags to identify the data source to which -[[production-ready-metrics-export-influx]] +[[actuator.metrics.export.influx]] ==== Influx By default, metrics are exported to an {micrometer-registry-docs}/influx[Influx] v1 instance running on your local machine with the default configuration. To export metrics to InfluxDB v2, configure the `org`, `bucket`, and authentication `token` for writing metrics. @@ -1867,7 +1867,7 @@ The location of the https://www.influxdata.com[Influx server] to use can be prov -[[production-ready-metrics-export-jmx]] +[[actuator.metrics.export.jmx]] ==== JMX Micrometer provides a hierarchical mapping to {micrometer-registry-docs}/jmx[JMX], primarily as a cheap and portable way to view metrics locally. By default, metrics are exported to the `metrics` JMX domain. @@ -1897,7 +1897,7 @@ An auto-configured `JmxConfig` and `Clock` beans are provided unless you define -[[production-ready-metrics-export-kairos]] +[[actuator.metrics.export.kairos]] ==== KairosDB By default, metrics are exported to {micrometer-registry-docs}/kairos[KairosDB] running on your local machine. The location of the https://kairosdb.github.io/[KairosDB server] to use can be provided using: @@ -1913,7 +1913,7 @@ The location of the https://kairosdb.github.io/[KairosDB server] to use can be p -[[production-ready-metrics-export-newrelic]] +[[actuator.metrics.export.newrelic]] ==== New Relic New Relic registry pushes metrics to {micrometer-registry-docs}/new-relic[New Relic] periodically. To export metrics to https://newrelic.com[New Relic], your API key and account id must be provided: @@ -1954,12 +1954,12 @@ Finally, you can take full control by defining your own `NewRelicClientProvider` -[[production-ready-metrics-export-prometheus]] +[[actuator.metrics.export.prometheus]] ==== Prometheus {micrometer-registry-docs}/prometheus[Prometheus] expects to scrape or poll individual app instances for metrics. Spring Boot provides an actuator endpoint available at `/actuator/prometheus` to present a https://prometheus.io[Prometheus scrape] with the appropriate format. -TIP: The endpoint is not available by default and must be exposed, see <> for more details. +TIP: The endpoint is not available by default and must be exposed, see <> for more details. Here is an example `scrape_config` to add to `prometheus.yml`: @@ -1991,7 +1991,7 @@ For advanced configuration, you can also provide your own `PrometheusPushGateway -[[production-ready-metrics-export-signalfx]] +[[actuator.metrics.export.signalfx]] ==== SignalFx SignalFx registry pushes metrics to {micrometer-registry-docs}/signalFx[SignalFx] periodically. To export metrics to https://www.signalfx.com[SignalFx], your access token must be provided: @@ -2018,10 +2018,10 @@ You can also change the interval at which metrics are sent to SignalFx: -[[production-ready-metrics-export-simple]] +[[actuator.metrics.export.simple]] ==== Simple Micrometer ships with a simple, in-memory backend that is automatically used as a fallback if no other registry is configured. -This allows you to see what metrics are collected in the <>. +This allows you to see what metrics are collected in the <>. The in-memory backend disables itself as soon as you're using any of the other available backend. You can also disable it explicitly: @@ -2037,7 +2037,7 @@ You can also disable it explicitly: -[[production-ready-metrics-export-stackdriver]] +[[actuator.metrics.export.stackdriver]] ==== Stackdriver Stackdriver registry pushes metrics to https://cloud.google.com/stackdriver/[Stackdriver] periodically. To export metrics to SaaS {micrometer-registry-docs}/stackdriver[Stackdriver], your Google Cloud project id must be provided: @@ -2064,7 +2064,7 @@ You can also change the interval at which metrics are sent to Stackdriver: -[[production-ready-metrics-export-statsd]] +[[actuator.metrics.export.statsd]] ==== StatsD The StatsD registry pushes metrics over UDP to a StatsD agent eagerly. By default, metrics are exported to a {micrometer-registry-docs}/statsD[StatsD] agent running on your local machine. @@ -2094,7 +2094,7 @@ You can also change the StatsD line protocol to use (default to Datadog): -[[production-ready-metrics-export-wavefront]] +[[actuator.metrics.export.wavefront]] ==== Wavefront Wavefront registry pushes metrics to {micrometer-registry-docs}/wavefront[Wavefront] periodically. If you are exporting metrics to https://www.wavefront.com/[Wavefront] directly, your API token must be provided: @@ -2134,14 +2134,14 @@ You can also change the interval at which metrics are sent to Wavefront: -[[production-ready-metrics-meter]] +[[actuator.metrics.supported]] === Supported Metrics and Meters Spring Boot provides automatic meter registration for a wide variety of technologies. In most situations, the out-of-the-box defaults will provide sensible metrics that can be published to any of the supported monioring systems. -[[production-ready-metrics-jvm]] +[[actuator.metrics.supported.jvm]] ==== JVM Metrics Auto-configuration will enable JVM Metrics using core Micrometer classes. JVM metrics are published under the `jvm.` meter name. @@ -2155,7 +2155,7 @@ The following JVM metrics are provided: -[[production-ready-metrics-system]] +[[actuator.metrics.supported.system]] ==== System Metrics Auto-configuration will enable system metrics using core Micrometer classes. System metrics are published under the `system.` and `process.` meter names. @@ -2168,20 +2168,20 @@ The following system metrics are provided: -[[production-ready-metrics-logger]] +[[actuator.metrics.supported.logger]] ==== Logger Metrics Auto-configuration enables the event metrics for both Logback and Log4J2. Details are published under the `log4j2.events.` or `logback.events.` meter names. -[[production-ready-metrics-spring-mvc]] +[[actuator.metrics.supported.spring-mvc]] ==== Spring MVC Metrics Auto-configuration enables the instrumentation of all requests handled by Spring MVC controllers and functional handlers. By default, metrics are generated with the name, `http.server.requests`. The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property. -`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <> for details). +`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <> for details). If you don't want to record metrics for all Spring MVC requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead. By default, Spring MVC related metrics are tagged with the following information: @@ -2210,17 +2210,17 @@ 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 <>. -[[production-ready-metrics-web-flux]] +[[actuator.metrics.supported.spring-webflux]] ==== Spring WebFlux Metrics Auto-configuration enables the instrumentation of all requests handled by Spring WebFlux controllers and functional handlers. By default, metrics are generated with the name, `http.server.requests`. The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property. -`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <> for details). +`@Timed` annotations are supported on `@Controller` classes and `@RequestMapping` methods (see <> for details). If you don't want to record metrics for all Spring WebFlux requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead. By default, WebFlux related metrics are tagged with the following information: @@ -2249,17 +2249,17 @@ 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 <>. -[[production-ready-metrics-jersey-server]] +[[actuator.metrics.supported.jersey]] ==== Jersey Server Metrics Auto-configuration enables the instrumentation of all requests handled by the Jersey JAX-RS implementation whenever Micrometer's `micrometer-jersey2` module is on the classpath. By default, metrics are generated with the name, `http.server.requests`. The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property. -`@Timed` annotations are supported on request-handling classes and methods (see <> for details). +`@Timed` annotations are supported on request-handling classes and methods (see <> for details). If you don't want to record metrics for all Jersey requests, you can set configprop:management.metrics.web.server.request.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead. By default, Jersey server metrics are tagged with the following information: @@ -2288,7 +2288,7 @@ To customize the tags, provide a `@Bean` that implements `JerseyTagsProvider`. -[[production-ready-metrics-http-clients]] +[[actuator.metrics.supported.http-clients]] ==== HTTP Client Metrics Spring Boot Actuator manages the instrumentation of both `RestTemplate` and `WebClient`. For that, you have to inject the auto-configured builder and use it to create instances: @@ -2328,7 +2328,7 @@ There are convenience static functions in `RestTemplateExchangeTags` and `WebCli -[[production-ready-metrics-tomcat]] +[[actuator.metrics.supported.tomcat]] ==== Tomcat Metrics Auto-configuration will enable the instrumentation of Tomcat only when an `MBeanRegistry` is enabled. By default, the `MBeanRegistry` is disabled, but you can enable it by setting configprop:server.tomcat.mbeanregistry.enabled[] to `true`. @@ -2337,7 +2337,7 @@ Tomcat metrics are published under the `tomcat.` meter name. -[[production-ready-metrics-cache]] +[[actuator.metrics.supported.cache]] ==== Cache Metrics Auto-configuration enables the instrumentation of all available ``Cache``s on startup with metrics prefixed with `cache`. Cache instrumentation is standardized for a basic set of metrics. @@ -2359,7 +2359,7 @@ A `CacheMetricsRegistrar` bean is made available to make that process easier. -[[production-ready-metrics-jdbc]] +[[actuator.metrics.supported.jdbc]] ==== DataSource Metrics Auto-configuration enables the instrumentation of all available `DataSource` objects with metrics prefixed with `jdbc.connections`. Data source instrumentation results in gauges representing the currently active, idle, maximum allowed, and minimum allowed connections in the pool. @@ -2374,7 +2374,7 @@ Each metric is tagged by the name of the Pool (can be controlled with `spring.da -[[production-ready-metrics-hibernate]] +[[actuator.metrics.supported.hibernate]] ==== Hibernate Metrics If `org.hibernate:hibernate-micrometer` is on the classpath, all available Hibernate `EntityManagerFactory` instances that have statistics enabled are instrumented with a metric named `hibernate`. @@ -2393,13 +2393,13 @@ You can enable that on the auto-configured `EntityManagerFactory` as shown in th -[[production-ready-metrics-data-repository]] +[[actuator.metrics.supported.spring-data-repository]] ==== Spring Data Repository Metrics Auto-configuration enables the instrumentation of all Spring Data `Repository` method invocations. By default, metrics are generated with the name, `spring.data.repository.invocations`. The name can be customized by setting the configprop:management.metrics.data.repository.metric-name[] property. -`@Timed` annotations are supported on `Repository` classes and methods (see <> for details). +`@Timed` annotations are supported on `Repository` classes and methods (see <> for details). If you don't want to record metrics for all `Repository` invocations, you can set configprop:management.metrics.data.repository.autotime.enabled[] to `false` and exclusively use `@Timed` annotations instead. By default, repository invocation related metrics are tagged with the following information: @@ -2424,20 +2424,20 @@ To replace the default tags, provide a `@Bean` that implements `RepositoryTagsPr -[[production-ready-metrics-rabbitmq]] +[[actuator.metrics.supported.rabbitmq]] ==== RabbitMQ Metrics Auto-configuration will enable the instrumentation of all available RabbitMQ connection factories with a metric named `rabbitmq`. -[[production-ready-metrics-integration]] +[[actuator.metrics.supported.spring-integration]] ==== Spring Integration Metrics Spring Integration provides {spring-integration-docs}system-management.html#micrometer-integration[Micrometer support] automatically whenever a `MeterRegistry` bean is available. Metrics are published under the `spring.integration.` meter name. -[[production-ready-metrics-kafka]] +[[actuator.metrics.supported.kafka]] ==== Kafka Metrics Auto-configuration will register a `MicrometerConsumerListener` and `MicrometerProducerListener` for the auto-configured consumer factory and producer factory respectively. It will also register a `KafkaStreamsMicrometerListener` for `StreamsBuilderFactoryBean`. @@ -2445,12 +2445,12 @@ For more details refer to {spring-kafka-docs}#micrometer-native[Micrometer Nativ -[[production-ready-metrics-mongodb]] +[[actuator.metrics.supported.mongodb]] ==== MongoDB Metrics -[[production-ready-metrics-mongodb-command]] +[[actuator.metrics.supported.mongodb.command]] ===== Command Metrics Auto-configuration will register a `MongoMetricsCommandListener` with the auto-configured `MongoClient`. @@ -2492,7 +2492,7 @@ To disable the auto-configured command metrics, set the following property: -[[production-ready-metrics-mongodb-connectionpool]] +[[actuator.metrics.supported.mongodb.connection-pool]] ===== Connection Pool Metrics Auto-configuration will register a `MongoMetricsConnectionPoolListener` with the auto-configured `MongoClient`. @@ -2533,7 +2533,7 @@ To disable the auto-configured connection pool metrics, set the following proper -[[production-ready-metrics-timed-annotation]] +[[actuator.metrics.supported.timed-annotation]] ==== @Timed Annotation Support The `@Timed` annotation from the `io.micrometer.core.annotation` package can be used with several of the supported technologies listed above. If supported, the annotation can be used either at the class-level or the method-level. @@ -2596,7 +2596,7 @@ Long task timers require a separate metric name, and can be stacked with a short -[[production-ready-metrics-custom]] +[[actuator.metrics.registering-custom]] === Registering Custom Metrics To register custom metrics, inject `MeterRegistry` into your component, as shown in the following example: @@ -2619,7 +2619,7 @@ NOTE: By default, metrics from all `MeterBinder` beans will be automatically bou -[[production-ready-metrics-customizing]] +[[actuator.metrics.customizing]] === Customizing Individual Metrics If you need to apply customizations to specific `Meter` instances you can use the `io.micrometer.core.instrument.config.MeterFilter` interface. @@ -2636,7 +2636,7 @@ These use the global registry that is not Spring-managed. -[[production-ready-metrics-common-tags]] +[[actuator.metrics.customizing.common-tags]] ==== Common Tags Common tags are generally used for dimensional drill-down on the operating environment like host, instance, region, stack, etc. Commons tags are applied to all meters and can be configured as shown in the following example: @@ -2657,7 +2657,7 @@ As the order of common tags cannot be guaranteed using this approach, Graphite u -[[production-ready-metrics-per-meter-properties]] +[[actuator.metrics.customizing.per-meter-properties]] ==== Per-meter Properties In addition to `MeterFilter` beans, it's also possible to apply a limited set of customization on a per-meter basis using properties. Per-meter customizations apply to any all meter IDs that start with the given name. @@ -2698,10 +2698,10 @@ For more details on concepts behind `percentiles-histogram`, `percentiles` and ` -[[production-ready-metrics-endpoint]] +[[actuator.metrics.endpoint]] === Metrics Endpoint Spring Boot provides a `metrics` endpoint that can be used diagnostically to examine the metrics collected by an application. -The endpoint is not available by default and must be exposed, see <> for more details. +The endpoint is not available by default and must be exposed, see <> for more details. Navigating to `/actuator/metrics` displays a list of available meter names. You can drill down to view information about a particular meter by providing its name as a selector, e.g. `/actuator/metrics/jvm.memory.max`. @@ -2723,7 +2723,7 @@ If you only wanted to see the maximum size for the "Metaspace", you could add an -[[production-ready-auditing]] +[[actuator.auditing]] == Auditing Once Spring Security is in play, Spring Boot Actuator has a flexible audit framework that publishes events (by default, "`authentication success`", "`failure`" and "`access denied`" exceptions). This feature can be very useful for reporting and for implementing a lock-out policy based on authentication failures. @@ -2735,7 +2735,7 @@ For production environments, consider creating your own alternative `AuditEventR -[[production-ready-auditing-custom]] +[[actuator.auditing.custom]] === Custom Auditing To customize published security events, you can provide your own implementations of `AbstractAuthenticationAuditListener` and `AbstractAuthorizationAuditListener`. @@ -2744,7 +2744,7 @@ To do so, either inject the `AuditEventRepository` bean into your own components -[[production-ready-http-tracing]] +[[actuator.tracing]] == HTTP Tracing HTTP Tracing can be enabled by providing a bean of type `HttpTraceRepository` in your application's configuration. For convenience, Spring Boot offers an `InMemoryHttpTraceRepository` that stores traces for the last 100 request-response exchanges, by default. @@ -2756,14 +2756,14 @@ The `httptrace` endpoint can be used to obtain information about the request-res -[[production-ready-http-tracing-custom]] +[[actuator.tracing.custom]] === Custom HTTP tracing To customize the items that are included in each trace, use the configprop:management.trace.http.include[] configuration property. For advanced customization, consider registering your own `HttpExchangeTracer` implementation. -[[production-ready-process-monitoring]] +[[actuator.process-monitoring]] == Process Monitoring In the `spring-boot` module, you can find two classes to create files that are often useful for process monitoring: @@ -2772,12 +2772,12 @@ In the `spring-boot` module, you can find two classes to create files that are o By default, these writers are not activated, but you can enable: -* <> -* <> +* <> +* <> -[[production-ready-process-monitoring-configuration]] +[[actuator.process-monitoring.configuration]] === Extending Configuration In the `META-INF/spring.factories` file, you can activate the listener(s) that writes a PID file, as shown in the following example: @@ -2790,14 +2790,14 @@ In the `META-INF/spring.factories` file, you can activate the listener(s) that w -[[production-ready-process-monitoring-programmatically]] +[[actuator.process-monitoring.programmatically]] === Programmatically You can also activate a listener by invoking the `SpringApplication.addListeners(...)` method and passing the appropriate `Writer` object. This method also lets you customize the file name and path in the `Writer` constructor. -[[production-ready-cloudfoundry]] +[[actuator.cloud-foundry]] == Cloud Foundry Support Spring Boot's actuator module includes additional support that is activated when you deploy to a compatible Cloud Foundry instance. The `/cloudfoundryapplication` path provides an alternative secured route to all `@Endpoint` beans. @@ -2810,7 +2810,7 @@ In order to use the endpoint, a valid UAA token must be passed with the request. -[[production-ready-cloudfoundry-disable]] +[[actuator.cloud-foundry.disable]] === Disabling Extended Cloud Foundry Actuator Support If you want to fully disable the `/cloudfoundryapplication` endpoints, you can add the following setting to your `application.properties` file: @@ -2825,7 +2825,7 @@ If you want to fully disable the `/cloudfoundryapplication` endpoints, you can a -[[production-ready-cloudfoundry-ssl]] +[[actuator.cloud-foundry.ssl]] === Cloud Foundry Self-signed Certificates By default, the security verification for `/cloudfoundryapplication` endpoints makes SSL calls to various Cloud Foundry services. If your Cloud Foundry UAA or Cloud Controller services use self-signed certificates, you need to set the following property: @@ -2840,7 +2840,7 @@ If your Cloud Foundry UAA or Cloud Controller services use self-signed certifica -[[production-ready-custom-context-path]] +[[actuator.cloud-foundry.custom-context-path]] === Custom Context Path If the server's context-path has been configured to anything other than `/`, the Cloud Foundry endpoints will not be available at the root of the application. For example, if `server.servlet.context-path=/app`, Cloud Foundry endpoints will be available at `/app/cloudfoundryapplication/*`. @@ -2856,7 +2856,7 @@ include::{include-productionreadyfeatures}/cloudfoundry/CloudFoundryCustomContex -[[production-ready-whats-next]] +[[actuator.whats-next]] == What to Read Next You might want to read about graphing tools such as https://graphiteapp.org[Graphite]. 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/spring-boot-cli.adoc index dfd82eda5e..25405ee0b8 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/spring-boot-cli.adoc @@ -8,14 +8,14 @@ You can also bootstrap a new project or write your own command for it. -[[cli-installation]] +[[cli.installation]] == Installing the CLI The Spring Boot CLI (Command-Line Interface) can be installed manually by using SDKMAN! (the SDK Manager) or by using Homebrew or MacPorts if you are an OSX user. -See _<>_ in the "`Getting started`" section for comprehensive installation instructions. +See _<>_ in the "`Getting started`" section for comprehensive installation instructions. -[[cli-using-the-cli]] +[[cli.using-the-cli]] == Using the CLI Once you have installed the CLI, you can run it by typing `spring` and pressing Enter at the command line. If you run `spring` without any arguments, a help screen is displayed, as follows: @@ -66,7 +66,7 @@ The `version` command provides a quick way to check which version of Spring Boot -[[cli-run]] +[[cli.using-the-cli.run]] === Running Applications with the CLI You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI is completely self-contained, so you do not need any external Groovy installation. @@ -113,7 +113,7 @@ Doing so ensures the values are properly passed to the process. -[[cli-deduced-grab-annotations]] +[[cli.using-the-cli.run.deduced-grab-annotations]] ==== Deduced "`grab`" Dependencies Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on third-party libraries. This useful technique lets Groovy download jars in the same way as Maven or Gradle would but without requiring you to use a build tool. @@ -164,7 +164,7 @@ TIP: See subclasses of {spring-boot-cli-module-code}/compiler/CompilerAutoConfig -[[cli-default-grab-deduced-coordinates]] +[[cli.using-the-cli.run.deduced-grab-coordinates]] ==== Deduced "`grab`" Coordinates Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency without a group or version (for example, `@Grab('freemarker')`). Doing so consults Spring Boot's default dependency metadata to deduce the artifact's group and version. @@ -175,7 +175,7 @@ A table showing the dependencies and their versions that are included in the def -[[cli-default-import-statements]] +[[cli.using-the-cli.run.default-import-statements]] ==== Default Import Statements To help reduce the size of your Groovy code, several `import` statements are automatically included. Notice how the preceding example refers to `@Component`, `@RestController`, and `@RequestMapping` without needing to use fully-qualified names or `import` statements. @@ -185,14 +185,14 @@ Try running your application to see what fails before adding imports. -[[cli-automatic-main-method]] +[[cli.using-the-cli.run.automatic-main-method]] ==== Automatic Main Method Unlike the equivalent Java application, you do not need to include a `public static void main(String[] args)` method with your `Groovy` scripts. A `SpringApplication` is automatically created, with your compiled code acting as the `source`. -[[cli-default-grab-deduced-coordinates-custom-dependency-management]] +[[cli.using-the-cli.run.custom-dependency-management]] ==== Custom Dependency Management By default, the CLI uses the dependency management declared in `spring-boot-dependencies` when resolving `@Grab` dependencies. Additional dependency management, which overrides the default dependency management, can be configured by using the `@DependencyManagementBom` annotation. @@ -222,7 +222,7 @@ However, to ensure consistent ordering of the dependency management, you can use -[[cli-multiple-source-files]] +[[cli.using-the-cli.multiple-source-files]] === Applications with Multiple Source Files You can use "`shell globbing`" with all commands that accept file input. Doing so lets you use multiple files from a single directory, as shown in the following example: @@ -234,7 +234,7 @@ Doing so lets you use multiple files from a single directory, as shown in the fo -[[cli-jar]] +[[cli.using-the-cli.packaging]] === Packaging Your Application You can use the `jar` command to package your application into a self-contained executable jar file, as shown in the following example: @@ -265,7 +265,7 @@ Type `spring help jar` on the command line for more information. -[[cli-init]] +[[cli.using-the-cli.initialize-new-project]] === Initialize a New Project The `init` command lets you create a new project by using https://start.spring.io without leaving the shell, as shown in the following example: @@ -317,7 +317,7 @@ For instance, the following command creates a Gradle project that uses Java 8 an -[[cli-shell]] +[[cli.using-the-cli.embedded-shell]] === Using the Embedded Shell Spring Boot includes command-line completion scripts for the BASH and zsh shells. If you do not use either of these shells (perhaps you are a Windows user), you can use the `shell` command to launch an integrated shell, as shown in the following example: @@ -343,7 +343,7 @@ To exit the embedded shell, press `ctrl-c`. -[[cli-install-uninstall]] +[[cli.using-the-cli.extensions]] === Adding Extensions to the CLI You can add extensions to the CLI by using the `install` command. The command takes one or more sets of artifact coordinates in the format `group:artifact:version`, as shown in the following example: @@ -374,7 +374,7 @@ To uninstall all additional dependencies, you can use the `--all` option, as sho -[[cli-groovy-beans-dsl]] +[[cli.groovy-beans-dsl]] == Developing Applications with the Groovy Beans DSL Spring Framework 4.0 has native support for a `beans{}` "`DSL`" (borrowed from https://grails.org/[Grails]), and you can embed bean definitions in your Groovy application scripts by using the same format. This is sometimes a good way to include external features like middleware declarations, as shown in the following example: @@ -407,7 +407,7 @@ You can mix class declarations with `beans{}` in the same file as long as they s -[[cli-maven-settings]] +[[cli.maven-setting]] == Configuring the CLI with settings.xml The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolve dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml` to configure Aether. @@ -426,7 +426,7 @@ See https://maven.apache.org/settings.html[Maven's settings documentation] for f -[[cli-whats-next]] +[[cli.whats-next]] == What to Read Next There are some {spring-boot-code}/spring-boot-project/spring-boot-cli/samples[sample groovy scripts] available from the GitHub repository that you can use to try out the Spring Boot CLI. There is also extensive Javadoc throughout the {spring-boot-cli-module-code}[source code]. 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/spring-boot-features.adoc index ad9debb9f1..6d6aeeb605 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/spring-boot-features.adoc @@ -1,14 +1,14 @@ -[[boot-features]] +[[features]] = Spring Boot Features 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. -[[boot-features-spring-application]] +[[features.spring-application]] == SpringApplication The `SpringApplication` class provides a convenient way to bootstrap a Spring application that is started from a `main()` method. In many situations, you can delegate to the static `SpringApplication.run` method, as shown in the following example: @@ -45,7 +45,7 @@ When your application starts, you should see something similar to the following By default, `INFO` logging messages are shown, including some relevant startup details, such as the user that launched the application. -If you need a log level other than `INFO`, you can set it, as described in <>. +If you need a log level other than `INFO`, you can set it, as described in <>. The application version is determined using the implementation version from the main application class's package. Startup information logging can be turned off by setting `spring.main.log-startup-info` to `false`. This will also turn off logging of the application's active profiles. @@ -54,7 +54,7 @@ TIP: To add additional logging during startup, you can override `logStartupInfo( -[[boot-features-startup-failure]] +[[features.spring-application.startup-failure]] === Startup Failure If your application fails to start, registered `FailureAnalyzers` get a chance to provide a dedicated error message and a concrete action to fix the problem. For instance, if you start a web application on port `8080` and that port is already in use, you should see something similar to the following message: @@ -74,10 +74,10 @@ For instance, if you start a web application on port `8080` and that port is alr Identify and stop the process that's listening on port 8080 or configure this application to listen on another port. ---- -NOTE: Spring Boot provides numerous `FailureAnalyzer` implementations, and you can <>. +NOTE: Spring Boot provides numerous `FailureAnalyzer` implementations, and you can <>. If no failure analyzers are able to handle the exception, you can still display the full conditions report to better understand what went wrong. -To do so, you need to <> or <> for `org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener`. +To do so, you need to <> or <> for `org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener`. For instance, if you are running your application by using `java -jar`, you can enable the `debug` property as follows: @@ -88,7 +88,7 @@ For instance, if you are running your application by using `java -jar`, you can -[[boot-features-lazy-initialization]] +[[features.spring-application.lazy-initialization]] === Lazy Initialization `SpringApplication` allows an application to be initialized lazily. When lazy initialization is enabled, beans are created as they are needed rather than during application startup. @@ -114,7 +114,7 @@ TIP: If you want to disable lazy initialization for certain beans while using la -[[boot-features-banner]] +[[features.spring-application.banner]] === Customizing the Banner The banner that is printed on start up can be changed by adding a `banner.txt` file to your classpath or by setting the configprop:spring.banner.location[] property to the location of such a file. If the file has an encoding other than UTF-8, you can set `spring.banner.charset`. @@ -170,7 +170,7 @@ This will initialize the `application.*` banner variables before building the cl -[[boot-features-customizing-spring-application]] +[[features.spring-application.customizing-spring-application]] === Customizing SpringApplication If the `SpringApplication` defaults are not to your taste, you can instead create a local instance and customize it. For example, to turn off the banner, you could write: @@ -184,13 +184,13 @@ NOTE: The constructor arguments passed to `SpringApplication` are configuration In most cases, these are references to `@Configuration` classes, but they could also be references to XML configuration or to packages that should be scanned. It is also possible to configure the `SpringApplication` by using an `application.properties` file. -See _<>_ for details. +See _<>_ for details. For a complete list of the configuration options, see the {spring-boot-module-api}/SpringApplication.html[`SpringApplication` Javadoc]. -[[boot-features-fluent-builder-api]] +[[features.spring-application.fluent-builder-api]] === Fluent Builder API If you need to build an `ApplicationContext` hierarchy (multiple contexts with a parent/child relationship) or if you prefer using a "`fluent`" builder API, you can use the `SpringApplicationBuilder`. @@ -207,7 +207,7 @@ See the {spring-boot-module-api}/builder/SpringApplicationBuilder.html[`SpringAp -[[boot-features-application-availability]] +[[features.spring-application.application-availability]] === Application Availability When deployed on platforms, applications can provide information about their availability to the platform using infrastructure such as https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[Kubernetes Probes]. Spring Boot includes out-of-the box support for the commonly used "`liveness`" and "`readiness`" availability states. @@ -217,33 +217,33 @@ In addition, you can also obtain availability states by injecting the `Applicati -[[boot-features-application-availability-liveness-state]] +[[features.spring-application.application-availability.liveness]] ==== Liveness State 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`. If the application context has started successfully, Spring Boot assumes that the application is in a valid state. -An application is considered live as soon as the context has been refreshed, see <>. +An application is considered live as soon as the context has been refreshed, see <>. -[[boot-features-application-availability-readiness-state]] +[[features.spring-application.application-availability.readiness]] ==== Readiness State The "`Readiness`" state of an application tells whether the application is ready to handle traffic. A failing "`Readiness`" state tells the platform that it should not route traffic to the application for now. This typically happens during startup, while `CommandLineRunner` and `ApplicationRunner` components are being processed, or at any time if the application decides that it's too busy for additional traffic. -An application is considered ready as soon as application and command-line runners have been called, see <>. +An application is considered ready as soon as application and command-line runners have been called, see <>. TIP: Tasks expected to run during startup should be executed by `CommandLineRunner` and `ApplicationRunner` components instead of using Spring component lifecycle callbacks such as `@PostConstruct`. -[[boot-features-application-availability-managing]] +[[features.spring-application.application-availability.managing]] ==== Managing the Application Availability State Application components can retrieve the current availability state at any time, by injecting the `ApplicationAvailability` interface and calling methods on it. More often, applications will want to listen to state updates or update the state of the application. @@ -262,12 +262,12 @@ We can also update the state of the application, when the application breaks and include::{include-springbootfeatures}/springapplication/availability/LocalCacheVerifier.java[] ---- -Spring Boot provides <>. -You can get more guidance about <>. +Spring Boot provides <>. +You can get more guidance about <>. -[[boot-features-application-events-and-listeners]] +[[features.spring-application.application-events-and-listeners]] === Application Events and Listeners In addition to the usual Spring Framework events, such as {spring-framework-api}/context/event/ContextRefreshedEvent.html[`ContextRefreshedEvent`], a `SpringApplication` sends some additional application events. @@ -293,7 +293,7 @@ Application events are sent in the following order, as your application runs: . An `ApplicationPreparedEvent` is sent just before the refresh is started but after bean definitions have been loaded. . An `ApplicationStartedEvent` is sent after the context has been refreshed but before any application and command-line runners have been called. . An `AvailabilityChangeEvent` is sent right after with `LivenessState.CORRECT` to indicate that the application is considered as live. -. An `ApplicationReadyEvent` is sent after any <> have been called. +. An `ApplicationReadyEvent` is sent after any <> have been called. . An `AvailabilityChangeEvent` is sent right after with `ReadinessState.ACCEPTING_TRAFFIC` to indicate that the application is ready to service requests. . An `ApplicationFailedEvent` is sent if there is an exception on startup. @@ -308,7 +308,7 @@ TIP: You often need not use application events, but it can be handy to know that Internally, Spring Boot uses events to handle a variety of tasks. NOTE: Event listeners should not run potentially lengthy tasks as they execute in the same thread by default. -Consider using <> instead. +Consider using <> instead. Application events are sent by using Spring Framework's event publishing mechanism. Part of this mechanism ensures that an event published to the listeners in a child context is also published to the listeners in any ancestor contexts. @@ -319,7 +319,7 @@ The context can be injected by implementing `ApplicationContextAware` or, if the -[[boot-features-web-environment]] +[[features.spring-application.web-environment]] === Web Environment A `SpringApplication` attempts to create the right type of `ApplicationContext` on your behalf. The algorithm used to determine a `WebApplicationType` is the following: @@ -337,7 +337,7 @@ TIP: It is often desirable to call `setWebApplicationType(WebApplicationType.NON -[[boot-features-application-arguments]] +[[features.spring-application.application-arguments]] === Accessing Application Arguments If you need to access the application arguments that were passed to `SpringApplication.run(...)`, you can inject a `org.springframework.boot.ApplicationArguments` bean. The `ApplicationArguments` interface provides access to both the raw `String[]` arguments as well as parsed `option` and `non-option` arguments, as shown in the following example: @@ -352,7 +352,7 @@ This lets you also inject single application arguments by using the `@Value` ann -[[boot-features-command-line-runner]] +[[features.spring-application.command-line-runner]] === Using the ApplicationRunner or CommandLineRunner If you need to run some specific code once the `SpringApplication` has started, you can implement the `ApplicationRunner` or `CommandLineRunner` interfaces. Both interfaces work in the same way and offer a single `run` method, which is called just before `SpringApplication.run(...)` completes. @@ -372,7 +372,7 @@ If several `CommandLineRunner` or `ApplicationRunner` beans are defined that mus -[[boot-features-application-exit]] +[[features.spring-application.application-exit]] === Application Exit Each `SpringApplication` registers a shutdown hook with the JVM to ensure that the `ApplicationContext` closes gracefully on exit. All the standard Spring lifecycle callbacks (such as the `DisposableBean` interface or the `@PreDestroy` annotation) can be used. @@ -390,7 +390,7 @@ When such an exception is encountered, Spring Boot returns the exit code provide -[[boot-features-application-admin]] +[[features.spring-application.admin]] === Admin Features It is possible to enable admin-related features for the application by specifying the configprop:spring.application.admin.enabled[] property. This exposes the {spring-boot-module-code}/admin/SpringApplicationAdminMXBean.java[`SpringApplicationAdminMXBean`] on the platform `MBeanServer`. @@ -401,7 +401,7 @@ TIP: If you want to know on which HTTP port the application is running, get the -[[boot-features-application-startup-tracking]] +[[features.spring-application.startup-tracking]] === Application Startup tracking During the application startup, the `SpringApplication` and the `ApplicationContext` perform many tasks related to the application lifecycle, the beans lifecycle or even processing application events. @@ -431,12 +431,12 @@ Additionally, Spring Boot Actuator will {spring-boot-actuator-restapi-docs}/#sta -[[boot-features-external-config]] +[[features.external-config]] == Externalized Configuration Spring Boot lets you externalize your configuration so that you can work with the same application code in different environments. You can use a variety of external configuration sources, include Java properties files, YAML files, environment variables, and command-line arguments. -Property values can be injected directly into your beans by using the `@Value` annotation, accessed through Spring's `Environment` abstraction, or be <> through `@ConfigurationProperties`. +Property values can be injected directly into your beans by using the `@Value` annotation, accessed through Spring's `Environment` abstraction, or be <> through `@ConfigurationProperties`. Spring Boot uses a very particular `PropertySource` order that is designed to allow sensible overriding of values. Properties are considered in the following order (with values from lower items overriding earlier ones): @@ -455,16 +455,16 @@ Properties are considered in the following order (with values from lower items o . Properties from `SPRING_APPLICATION_JSON` (inline JSON embedded in an environment variable or system property). . Command line arguments. . `properties` attribute on your tests. - Available on {spring-boot-test-module-api}/context/SpringBootTest.html[`@SpringBootTest`] and the <>. + 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: -. <> packaged inside your jar (`application.properties` and YAML variants). -. <> packaged inside your jar (`application-\{profile}.properties` and YAML variants). -. <> outside of your packaged jar (`application.properties` and YAML variants). -. <> outside of your packaged jar (`application-\{profile}.properties` and YAML variants). +. <> packaged inside your jar (`application.properties` and YAML variants). +. <> packaged inside your jar (`application-\{profile}.properties` and YAML variants). +. <> outside of your packaged jar (`application.properties` and YAML variants). +. <> outside of your packaged jar (`application-\{profile}.properties` and YAML variants). NOTE: It is recommended to stick with one format for your entire application. If you have configuration files with both `.properties` and `.yml` format in the same location, `.properties` takes precedence. @@ -482,11 +482,11 @@ 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. -[[boot-features-external-config-command-line-args]] +[[features.external-config.command-line-args]] === Accessing Command Line Properties By default, `SpringApplication` converts any command line option arguments (that is, arguments starting with `--`, such as `--server.port=9000`) to a `property` and adds them to the Spring `Environment`. As mentioned previously, command line properties always take precedence over file based property sources. @@ -495,7 +495,7 @@ If you do not want command line properties to be added to the `Environment`, you -[[boot-features-external-config-application-json]] +[[features.external-config.application-json]] === JSON Application Properties Environment variables and system properties often have restrictions that mean some property names cannot be used. To help with this, Spring Boot allows you to encode a block of properties into a single JSON structure. @@ -532,8 +532,8 @@ This means that the JSON cannot override properties from lower order property so -[[boot-features-external-config-files]] -=== External Application Properties [[boot-features-external-config-application-property-files]] +[[features.external-config.files]] +=== External Application Properties [[features.external-config.files]] Spring Boot will automatically find and load `application.properties` and `application.yaml` files from the following locations when your application starts: . The classpath root @@ -561,7 +561,7 @@ The following example shows how to specify two locations: $ java -jar myproject.jar --spring.config.location=optional:classpath:/default.properties,optional:classpath:/override.properties ---- -TIP: Use the prefix `optional:` if the <> and you don't mind if they don't exist. +TIP: Use the prefix `optional:` if the <> and you don't mind if they don't exist. WARNING: `spring.config.name`, `spring.config.location`, and `spring.config.additional-location` are used very early to determine which files have to be loaded. They must be defined as an environment property (typically an OS environment variable, a system property, or a command-line argument). @@ -598,18 +598,18 @@ You can provide default values for your application in `application.properties` These default values can then be overridden at runtime with a different file located in one of the custom locations. NOTE: If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, configprop:spring.config.name[format=envvar] instead of configprop:spring.config.name[]). -See <> for details. +See <> for details. NOTE: If your application runs in a servlet container or application server, then JNDI properties (in `java:comp/env`) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties. -[[boot-features-external-config-optional-prefix]] +[[features.external-config.files.optional-prefix]] ==== Optional Locations By default, when a specified config data location does not exist, Spring Boot will throw a `ConfigDataLocationNotFoundException` and your application will not start. If you want to specify a location, but you don't mind if it doesn't always exist, you can use the `optional:` prefix. -You can use this prefix with the `spring.config.location` and `spring.config.additional-location` properties, as well as with <> declarations. +You can use this prefix with the `spring.config.location` and `spring.config.additional-location` properties, as well as with <> declarations. For example, a `spring.config.import` value of `optional:file:./myconfig.properties` allows your application to start, even if the `myconfig.properties` file is missing. @@ -618,7 +618,7 @@ Set the value to `ignore` using `SpringApplication.setDefaultProperties(...)` or -[[boot-features-external-config-files-wildcards]] +[[features.external-config.files.wildcard-locations]] ==== Wildcard Locations If a config file location includes the `{asterisk}` character for the last path segment, it is considered a wildcard location. Wildcards are expanded when the config is loaded so that immediate subdirectories are also checked. @@ -641,7 +641,7 @@ You cannot use a wildcard in a `classpath:` location. -[[boot-features-external-config-files-profile-specific]] +[[features.external-config.files.profile-specific]] ==== Profile Specific Files As well as `application` property files, Spring Boot will also attempt to load profile-specific files using the naming convention `application-\{profile}`. For example, if your application activates a profile named `prod` and uses YAML files, then both `application.yml` and `application-prod.yml` will be considered. @@ -654,11 +654,11 @@ The `Environment` has a set of default profiles (by default, `[default]`) that a In other words, if no profiles are explicitly activated, then properties from `application-default` are considered. NOTE: Properties files are only ever loaded once. -If you've already directly <> a profile specific property files then it won't be imported a second time. +If you've already directly <> a profile specific property files then it won't be imported a second time. -[[boot-features-external-config-files-importing]] +[[features.external-config.files.importing]] ==== Importing Additional Data Application properties may import further config data from other locations using the `spring.config.import` property. Imports are processed as they are discovered, and are treated as additional documents inserted immediately below the one that declares the import. @@ -707,7 +707,7 @@ Locations will be processed in the order that they are defined, with later impor [TIP] ==== Spring Boot includes pluggable API that allows various different location addresses to be supported. -By default you can import Java Properties, YAML and "`<>`". +By default you can import Java Properties, YAML and "`<>`". Third-party jars can offer support for additional technologies (there's no requirement for files to be local). For example, you can imagine config data being from external stores such as Consul, Apache ZooKeeper or Netflix Archaius. @@ -717,7 +717,7 @@ If you want to support your own locations, see the `ConfigDataLocationResolver` -[[boot-features-external-config-files-importing-extensionless]] +[[features.external-config.file.importing-extensionless]] ==== Importing Extensionless Files Some cloud platforms cannot add a file extension to volume mounted files. To import these extensionless files, you need to give Spring Boot a hint so that it knows how to load them. @@ -735,7 +735,7 @@ You can import it from your `application.properties` using the following: -[[boot-features-external-config-files-configtree]] +[[features.external-config.files.configtree]] ==== Using Configuration Trees When running applications on a cloud platform (such as Kubernetes) you often need to read config values that the platform supplies. It's not uncommon to use environment variables for such purposes, but this can have drawbacks, especially if the value is supposed to be kept secret. @@ -748,7 +748,7 @@ There are two common volume mount patterns that can be use: . A single file contains a complete set of properties (usually written as YAML). . Multiple files are written to a directory tree, with the filename becoming the '`key`' and the contents becoming the '`value`'. -For the first case, you can import the YAML or Properties file directly using `spring.config.import` as described <>. +For the first case, you can import the YAML or Properties file directly using `spring.config.import` as described <>. For the second case, you need to use the `configtree:` prefix so that Spring Boot knows it needs to expose all the files as properties. As an example, let's imagine that Kubernetes has mounted the following volume: @@ -824,7 +824,7 @@ For example, if a secret named `db.password` is mounted at location `/run/secret -[[boot-features-external-config-placeholders-in-properties]] +[[features.external-config.files.property-placeholders]] ==== Property Placeholders The values in `application.properties` and `application.yml` are filtered through the existing `Environment` when they are used, so you can refer back to previously defined values (for example, from System properties). The standard `$\{name}` property-placeholder syntax can be used anywhere within a value. @@ -839,11 +839,11 @@ For example, the following file will set `app.description` to "`MyApp is a Sprin ---- TIP: You can also use this technique to create "`short`" variants of existing Spring Boot properties. -See the _<>_ how-to for details. +See the _<>_ how-to for details. -[[boot-features-external-config-files-multi-document]] +[[features.external-config.files.multi-document]] ==== Working with Multi-Document Files Spring Boot allows you to split a single physical file into multiple logical documents which are each added independently. Documents are processed in order, from top to bottom. @@ -876,13 +876,13 @@ NOTE: Property file separators must not have any leading whitespace and must hav The lines immediately before and after the separator must not be comments. TIP: Multi-document property files are often used in conjunction with activation properties such as `spring.config.activate.on-profile`. -See the <> for details. +See the <> for details. WARNING: Multi-document property files cannot be loaded by using the `@PropertySource` or `@TestPropertySource` annotations. -[[boot-features-external-config-file-activation-properties]] +[[features.external-config.files.activation-properties]] ==== Activation Properties It's sometimes useful to only activate a given get of properties when certain conditions are met. For example, you might have properties that are only relevant when a specific profile is active. @@ -920,17 +920,17 @@ For example, the following specifies that the second document is only active whe -[[boot-features-encrypting-properties]] +[[features.external-config.encrypting]] === Encrypting Properties Spring Boot does not provide any built in support for encrypting property values, however, it does provide the hook points necessary to modify values contained in the Spring `Environment`. The `EnvironmentPostProcessor` interface allows you to manipulate the `Environment` before the application starts. -See <> for details. +See <> for details. If you're looking for a secure way to store credentials and passwords, the https://cloud.spring.io/spring-cloud-vault/[Spring Cloud Vault] project provides support for storing externalized configuration in https://www.vaultproject.io/[HashiCorp Vault]. -[[boot-features-external-config-yaml]] +[[features.external-config.yaml]] === Working with YAML https://yaml.org[YAML] is a superset of JSON and, as such, is a convenient format for specifying hierarchical configuration data. The `SpringApplication` class automatically supports YAML as an alternative to properties whenever you have the https://bitbucket.org/asomov/snakeyaml[SnakeYAML] library on your classpath. @@ -939,7 +939,7 @@ NOTE: If you use "`Starters`", SnakeYAML is automatically provided by `spring-bo -[[boot-features-external-config-yaml-to-properties]] +[[features.external-config.yaml.mapping-to-properties]] ==== Mapping YAML to Properties YAML documents need to be converted from their hierarchical format to a flat structure that can be used with the Spring `Environment`. For example, consider the following YAML document: @@ -986,15 +986,15 @@ The preceding example would be transformed into these properties: ---- TIP: Properties that use the `[index]` notation can be bound to Java `List` or `Set` objects using Spring Boot's `Binder` class. -For more details see the "`<>`" section below. +For more details see the "`<>`" section below. WARNING: YAML files cannot be loaded by using the `@PropertySource` or `@TestPropertySource` annotations. So, in the case that you need to load values that way, you need to use a properties file. -[[boot-features-external-config-loading-yaml]] -[[boot-features-external-config-exposing-yaml-to-spring]] +[[features.external-config.yaml.directly-loading]] +[[features.external-config.yaml.directly-loading]] ==== Directly Loading YAML Spring Framework provides two convenient classes that can be used to load YAML documents. The `YamlPropertiesFactoryBean` loads YAML as `Properties` and the `YamlMapFactoryBean` loads YAML as a `Map`. @@ -1003,7 +1003,7 @@ You can also use the `YamlPropertySourceLoader` class if you want to load YAML a -[[boot-features-external-config-random-values]] +[[features.external-config.random-values]] === Configuring Random Values The `RandomValuePropertySource` is useful for injecting random values (for example, into secrets or test cases). It can produce integers, longs, uuids, or strings, as shown in the following example: @@ -1024,7 +1024,7 @@ If `max` is provided, then `value` is the minimum value and `max` is the maximum -[[boot-features-external-config-system-environment]] +[[features.external-config.system-environment]] === Configuring System Environment Properties Spring Boot supports setting a prefix for environment properties. This is useful if the system environment is shared by multiple Spring Boot applications with different configuration requirements. @@ -1034,16 +1034,16 @@ For example, if you set the prefix to `input`, a property such as `remote.timeou -[[boot-features-external-config-typesafe-configuration-properties]] +[[features.external-config.typesafe-configuration-properties]] === Type-safe Configuration Properties Using the `@Value("$\{property}")` annotation to inject configuration properties can sometimes be cumbersome, especially if you are working with multiple properties or your data is hierarchical in nature. Spring Boot provides an alternative method of working with properties that lets strongly typed beans govern and validate the configuration of your application. -TIP: See also the <>. +TIP: See also the <>. -[[boot-features-external-config-java-bean-binding]] +[[features.external-config.typesafe-configuration-properties.java-bean-binding]] ==== JavaBean properties binding It is possible to bind a bean declaring standard JavaBean properties as shown in the following example: @@ -1084,7 +1084,7 @@ Finally, only standard Java Bean properties are considered and binding on static -[[boot-features-external-config-constructor-binding]] +[[features.external-config.typesafe-configuration-properties.constructor-binding]] ==== Constructor binding The example in the previous section can be rewritten in an immutable fashion as shown in the following example: @@ -1119,7 +1119,7 @@ For consistency with properties of other types, if you do declare an `Optional` -[[boot-features-external-config-enabling]] +[[features.external-config.typesafe-configuration-properties.enabling-annotated-types]] ==== Enabling @ConfigurationProperties-annotated types Spring Boot provides infrastructure to bind `@ConfigurationProperties` types and register them as beans. You can either enable configuration properties on a class-by-class basis or enable configuration property scanning that works in a similar manner to component scanning. @@ -1157,7 +1157,7 @@ If you still want to inject other beans using the constructor, the configuration -[[boot-features-external-config-using]] +[[features.external-config.typesafe-configuration-properties.using-annotated-types]] ==== Using @ConfigurationProperties-annotated types This style of configuration works particularly well with the `SpringApplication` external YAML configuration, as shown in the following example: @@ -1184,7 +1184,7 @@ See the <> -[[boot-features-external-config-3rd-party-configuration]] +[[features.external-config.typesafe-configuration-properties.3rd-party-configuration]] ==== Third-party Configuration As well as using `@ConfigurationProperties` to annotate a class, you can also use it on public `@Bean` methods. Doing so can be particularly useful when you want to bind properties to third-party components that are outside of your control. @@ -1200,7 +1200,7 @@ Any JavaBean property defined with the `another` prefix is mapped onto that `Ano -[[boot-features-external-config-relaxed-binding]] +[[features.external-config.typesafe-configuration-properties.relaxed-binding]] ==== Relaxed Binding Spring Boot uses some relaxed rules for binding `Environment` properties to `@ConfigurationProperties` beans, so there does not need to be an exact match between the `Environment` property name and the bean property name. Common examples where this is useful include dash-separated environment properties (for example, `context-path` binds to `contextPath`), and capitalized environment properties (for example, `PORT` binds to `port`). @@ -1248,8 +1248,8 @@ NOTE: The `prefix` value for the annotation _must_ be in kebab case (lowercase a | Standard YAML list syntax or comma-separated values | Environment Variables -| Upper case format with underscore as the delimiter (see <>). -| Numeric values surrounded by underscores (see <>) +| Upper case format with underscore as the delimiter (see <>). +| Numeric values surrounded by underscores (see <>) | System properties | Camel case, kebab case, or underscore notation @@ -1260,7 +1260,7 @@ TIP: We recommend that, when possible, properties are stored in lower-case kebab -[[boot-features-external-config-relaxed-binding-maps]] +[[features.external-config.typesafe-configuration-properties.relaxed-binding.maps]] ===== Binding Maps When binding to `Map` properties you may need to use a special bracket notation so that the original `key` value is preserved. If the key is not surrounded by `[]`, any characters that are not alpha-numeric, `-` or `.` are removed. @@ -1296,7 +1296,7 @@ For example, binding `a.b=c` to `Map` will return a Map with the -[[boot-features-external-config-relaxed-binding-from-environment-variables]] +[[features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables]] ===== Binding from Environment Variables Most operating systems impose strict rules around the names that can be used for environment variables. For example, Linux shell variables can contain only letters (`a` to `z` or `A` to `Z`), numbers (`0` to `9`) or the underscore character (`_`). @@ -1319,7 +1319,7 @@ For example, the configuration property `my.acme[0].other` would use an environm -[[boot-features-external-config-complex-type-merge]] +[[features.external-config.typesafe-configuration-properties.merging-complex-types]] ==== Merging Complex Types When lists are configured in more than one place, overriding works by replacing the entire list. @@ -1416,7 +1416,7 @@ NOTE: The preceding merging rules apply to properties from all property sources, -[[boot-features-external-config-conversion]] +[[features.external-config.typesafe-configuration-properties.conversion]] ==== Properties Conversion Spring Boot attempts to coerce the external application properties to the right type when it binds to the `@ConfigurationProperties` beans. If you need custom type conversion, you can provide a `ConversionService` bean (with a bean named `conversionService`) or custom property editors (through a `CustomEditorConfigurer` bean) or custom `Converters` (with bean definitions annotated as `@ConfigurationPropertiesBinding`). @@ -1427,7 +1427,7 @@ You may want to rename your custom `ConversionService` if it is not required for -[[boot-features-external-config-conversion-duration]] +[[features.external-config.typesafe-configuration-properties.conversion.durations]] ===== Converting Durations Spring Boot has dedicated support for expressing durations. If you expose a `java.time.Duration` property, the following formats in application properties are available: @@ -1472,7 +1472,7 @@ Doing so gives a transparent upgrade path while supporting a much richer format. -[[boot-features-external-config-conversion-period]] +[[features.external-config.typesafe-configuration-properties.conversion.periods]] ===== Converting periods In addition to durations, Spring Boot can also work with `java.time.Period` type. The following formats can be used in application properties: @@ -1492,7 +1492,7 @@ NOTE: The `java.time.Period` type never actually stores the number of weeks, it -[[boot-features-external-config-conversion-datasize]] +[[features.external-config.typesafe-configuration-properties.conversion.data-sizes]] ===== Converting Data Sizes Spring Framework has a `DataSize` value type that expresses a size in bytes. If you expose a `DataSize` property, the following formats in application properties are available: @@ -1533,7 +1533,7 @@ Doing so gives a transparent upgrade path while supporting a much richer format. -[[boot-features-external-config-validation]] +[[features.external-config.typesafe-configuration-properties.validation]] ==== @ConfigurationProperties Validation Spring Boot attempts to validate `@ConfigurationProperties` classes whenever they are annotated with Spring's `@Validated` annotation. You can use JSR-303 `javax.validation` constraint annotations directly on your configuration class. @@ -1561,11 +1561,11 @@ 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. -[[boot-features-external-config-vs-value]] +[[features.external-config.typesafe-configuration-properties.vs-value-annotation]] ==== @ConfigurationProperties vs. @Value The `@Value` annotation is a core container feature, and it does not provide the same features as type-safe configuration properties. The following table summarizes the features that are supported by `@ConfigurationProperties` and `@Value`: @@ -1574,7 +1574,7 @@ The following table summarizes the features that are supported by `@Configuratio |=== | Feature |`@ConfigurationProperties` |`@Value` -| <> +| <> | Yes | Limited (see <>) @@ -1595,13 +1595,13 @@ If you used `@Value("{demo.itemPrice}")` instead, `demo.item-price` and `DEMO_IT If you define a set of configuration keys for your own components, we recommend you group them in a POJO annotated with `@ConfigurationProperties`. Doing so will provide you with structured, type-safe object that you can inject into your own beans. -`SpEL` expressions from <> are not processed at time of parsing these files and populating the environment. +`SpEL` expressions from <> are not processed at time of parsing these files and populating the environment. However, it is possible to write a `SpEL` expression in `@Value`. If the value of a property from an application property file is a `SpEL` expression, it will be evaluated when consumed via `@Value`. -[[boot-features-profiles]] +[[features.profiles]] == Profiles Spring Profiles provide a way to segregate parts of your application configuration and make it be available only in certain environments. Any `@Component`, `@Configuration` or `@ConfigurationProperties` can be marked with `@Profile` to limit when it is loaded, as shown in the following example: @@ -1629,7 +1629,7 @@ You could also specify it on the command line by using the following switch: `-- -[[boot-features-adding-active-profiles]] +[[features.profiles.adding-active-profiles]] === Adding Active Profiles The configprop:spring.profiles.active[] property follows the same ordering rules as other properties: The highest `PropertySource` wins. This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch. @@ -1637,11 +1637,11 @@ This means that you can specify active profiles in `application.properties` and Sometimes, it is useful to have properties that *add* to the active profiles rather than replace them. The `SpringApplication` entry point has a Java API for setting additional profiles (that is, on top of those activated by the configprop:spring.profiles.active[] property). See the `setAdditionalProfiles()` method in {spring-boot-module-api}/SpringApplication.html[SpringApplication]. -Profile groups, which are described in the <> can also be used to add active profiles if a given profile is active. +Profile groups, which are described in the <> can also be used to add active profiles if a given profile is active. -[[boot-features-profiles-groups]] +[[features.profiles.groups]] === Profile Groups Occasionally the profiles that you define and use in your application are too fine-grained and become cumbersome to use. For example, you might have `proddb` and `prodmq` profiles that you use to enable database and messaging features independently. @@ -1665,21 +1665,21 @@ Our application can now be started using `--spring.profiles.active=production` t -[[boot-features-programmatically-setting-profiles]] +[[features.profiles.programmatically-setting-profiles]] === Programmatically Setting Profiles You can programmatically set active profiles by calling `SpringApplication.setAdditionalProfiles(...)` before your application runs. It is also possible to activate profiles by using Spring's `ConfigurableEnvironment` interface. -[[boot-features-profile-specific-configuration]] +[[features.profiles.profile-specific-configuration-files]] === Profile-specific Configuration Files Profile-specific variants of both `application.properties` (or `application.yml`) and files referenced through `@ConfigurationProperties` are considered as files and loaded. -See "<>" for details. +See "<>" for details. -[[boot-features-logging]] +[[features.logging]] == Logging Spring Boot uses https://commons.apache.org/logging[Commons Logging] for all internal logging but leaves the underlying log implementation open. Default configurations are provided for {java-api}/java/util/logging/package-summary.html[Java Util Logging], https://logging.apache.org/log4j/2.x/[Log4J2], and https://logback.qos.ch/[Logback]. @@ -1697,7 +1697,7 @@ This prevents logging performed by the container or other applications that have -[[boot-features-logging-format]] +[[features.logging.log-format]] === Log Format The default log output from Spring Boot resembles the following example: @@ -1725,7 +1725,7 @@ It is mapped to `ERROR`. -[[boot-features-logging-console-output]] +[[features.logging.console-output]] === Console Output The default log configuration echoes messages to the console as they are written. By default, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged. @@ -1746,7 +1746,7 @@ Doing so enables trace logging for a selection of core loggers (embedded contain -[[boot-features-logging-color-coded-output]] +[[features.logging.console-output.color-coded]] ==== Color-coded Output If your terminal supports ANSI, color output is used to aid readability. You can set `spring.output.ansi.enabled` to a {spring-boot-module-api}/ansi/AnsiOutput.Enabled.html[supported value] to override the auto-detection. @@ -1803,7 +1803,7 @@ The following colors and styles are supported: -[[boot-features-logging-file-output]] +[[features.logging.file-output]] === File Output By default, Spring Boot logs only to the console and does not write log files. If you want to write log files in addition to the console output, you need to set a configprop:logging.file.name[] or configprop:logging.file.path[] property (for example, in your `application.properties`). @@ -1840,7 +1840,7 @@ As a result, specific configuration keys (such as `logback.configurationFile` fo -[[boot-features-logging-file-rotation]] +[[features.logging.file-rotation]] === File Rotation If you are using the Logback, it's possible to fine-tune log rotation settings using your `application.properties` or `application.yaml` file. For all other logging system, you'll need to configure rotation settings directly yourself (for example, if you use Log4J2 then you could add a `log4j.xml` file). @@ -1868,7 +1868,7 @@ The following rotation policy properties are supported: -[[boot-features-custom-log-levels]] +[[features.logging.log-levels]] === Log Levels All the supported logging systems can have the logger levels set in the Spring `Environment` (for example, in `application.properties`) by using `+logging.level.=+` where `level` is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL, or OFF. The `root` logger can be configured by using `logging.level.root`. @@ -1898,11 +1898,11 @@ For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springf NOTE: The above approach will only work for package level logging. Since relaxed binding always converts environment variables to lowercase, it's not possible to configure logging for an individual class in this way. -If you need to configure logging for a class, you can use <> variable. +If you need to configure logging for a class, you can use <> variable. -[[boot-features-custom-log-groups]] +[[features.logging.log-groups]] === Log Groups It's often useful to be able to group related loggers together so that they can all be configured at the same time. For example, you might commonly change the logging levels for _all_ Tomcat related loggers, but you can't easily remember top level packages. @@ -1941,7 +1941,7 @@ Spring Boot includes the following pre-defined logging groups that can be used o -[[boot-features-log-shutdown-hook]] +[[features.logging.shutdown-hook]] === Using a Log Shutdown Hook In order to release logging resources when your application terminates, a shutdown hook that will trigger log system cleanup when the JVM exits is provided. This shutdown hook is registered automatically unless your application is deployed as a war file. @@ -1960,7 +1960,7 @@ You can set the property in your `application.properties` or `application.yaml` -[[boot-features-custom-log-configuration]] +[[features.logging.custom-log-configuration]] === Custom Log Configuration The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring `Environment` property: configprop:logging.config[]. @@ -2074,7 +2074,7 @@ See the default configurations in `spring-boot.jar` for examples: [TIP] ==== -If you want to use a placeholder in a logging property, you should use <> and not the syntax of the underlying framework. +If you want to use a placeholder in a logging property, you should use <> and not the syntax of the underlying framework. Notably, if you use Logback, you should use `:` as the delimiter between a property name and its default value and not use `:-`. ==== @@ -2092,7 +2092,7 @@ For example, if you use `logging.pattern.level=user:%X\{user} %5p`, then the def -[[boot-features-logback-extensions]] +[[features.logging.logback-extensions]] === Logback Extensions Spring Boot includes a number of extensions to Logback that can help with advanced configuration. You can use these extensions in your `logback-spring.xml` configuration file. @@ -2111,7 +2111,7 @@ If you attempt to do so, making changes to the configuration file results in an -[[boot-features-logback-extensions-profile-specific]] +[[features.logging.logback-extensions.profile-specific]] ==== Profile-specific Configuration The `` tag lets you optionally include or exclude sections of configuration based on the active Spring profiles. Profile sections are supported anywhere within the `` element. @@ -2138,7 +2138,7 @@ The following listing shows three sample profiles: -[[boot-features-logback-environment-properties]] +[[features.logging.logback-extensions.environment-properties]] ==== Environment Properties The `` tag lets you expose properties from the Spring `Environment` for use within Logback. Doing so can be useful if you want to access values from your `application.properties` file in your Logback configuration. @@ -2163,7 +2163,7 @@ However, properties can be added to the `Environment` by using the relaxed rules -[[boot-features-internationalization]] +[[features.internationalization]] == Internationalization Spring Boot supports localized messages so that your application can cater to users of different language preferences. By default, Spring Boot looks for the presence of a `messages` resource bundle at the root of the classpath. @@ -2188,7 +2188,7 @@ See {spring-boot-autoconfigure-module-code}/context/MessageSourceProperties.java -[[boot-features-json]] +[[features.json]] == JSON Spring Boot provides integration with three JSON mapping libraries: @@ -2200,15 +2200,15 @@ Jackson is the preferred and default library. -[[boot-features-json-jackson]] +[[features.json.jackson]] === Jackson Auto-configuration for Jackson is provided and Jackson is part of `spring-boot-starter-json`. When Jackson is on the classpath an `ObjectMapper` bean is automatically configured. -Several configuration properties are provided for <>. +Several configuration properties are provided for <>. -[[boot-features-json-gson]] +[[features.json.gson]] === Gson Auto-configuration for Gson is provided. When Gson is on the classpath a `Gson` bean is automatically configured. @@ -2217,7 +2217,7 @@ To take more control, one or more `GsonBuilderCustomizer` beans can be used. -[[boot-features-json-json-b]] +[[features.json.json-b]] === JSON-B Auto-configuration for JSON-B is provided. When the JSON-B API and an implementation are on the classpath a `Jsonb` bean will be automatically configured. @@ -2225,18 +2225,18 @@ The preferred JSON-B implementation is Apache Johnzon for which dependency manag -[[boot-features-developing-web-applications]] +[[features.developing-web-applications]] == Developing Web Applications Spring Boot is well suited for web application development. You can create a self-contained HTTP server by using embedded Tomcat, Jetty, Undertow, or Netty. Most web applications use the `spring-boot-starter-web` module to get up and running quickly. You can also choose to build reactive web applications by using the `spring-boot-starter-webflux` module. -If you have not yet developed a Spring Boot web application, you can follow the "Hello World!" example in the _<>_ section. +If you have not yet developed a Spring Boot web application, you can follow the "Hello World!" example in the _<>_ section. -[[boot-features-spring-mvc]] +[[features.developing-web-applications.spring-mvc]] === The "`Spring Web MVC Framework`" The {spring-framework-docs}/web.html#mvc[Spring Web MVC framework] (often referred to as "`Spring MVC`") is a rich "`model view controller`" web framework. Spring MVC lets you create special `@Controller` or `@RestController` beans to handle incoming HTTP requests. @@ -2254,19 +2254,19 @@ There are also several guides that cover Spring MVC available at https://spring. -[[boot-features-spring-mvc-auto-configuration]] +[[features.developing-web-applications.spring-mvc.auto-configuration]] ==== Spring MVC Auto-configuration Spring Boot provides auto-configuration for Spring MVC that works well with most applications. The auto-configuration adds the following features on top of Spring's defaults: * Inclusion of `ContentNegotiatingViewResolver` and `BeanNameViewResolver` beans. -* Support for serving static resources, including support for WebJars (covered <>)). +* Support for serving static resources, including support for WebJars (covered <>)). * Automatic registration of `Converter`, `GenericConverter`, and `Formatter` beans. -* Support for `HttpMessageConverters` (covered <>). -* Automatic registration of `MessageCodesResolver` (covered <>). +* Support for `HttpMessageConverters` (covered <>). +* Automatic registration of `MessageCodesResolver` (covered <>). * Static `index.html` support. -* Automatic use of a `ConfigurableWebBindingInitializer` bean (covered <>). +* Automatic use of a `ConfigurableWebBindingInitializer` bean (covered <>). If you want to keep those Spring Boot MVC customizations and make more {spring-framework-docs}/web.html#mvc[MVC customizations] (interceptors, formatters, view controllers, and other features), you can add your own `@Configuration` class of type `WebMvcConfigurer` but *without* `@EnableWebMvc`. @@ -2285,7 +2285,7 @@ From this method you can register any converter that you like, or you can delega -[[boot-features-spring-mvc-message-converters]] +[[features.developing-web-applications.spring-mvc.message-converters]] ==== HttpMessageConverters Spring MVC uses the `HttpMessageConverter` interface to convert HTTP requests and responses. Sensible defaults are included out of the box. @@ -2304,7 +2304,7 @@ You can also override default converters in the same way. -[[boot-features-json-components]] +[[features.developing-web-applications.spring-mvc.json]] ==== Custom JSON Serializers and Deserializers If you use Jackson to serialize and deserialize JSON data, you might want to write your own `JsonSerializer` and `JsonDeserializer` classes. Custom serializers are usually https://github.com/FasterXML/jackson-docs/wiki/JacksonHowToCustomSerializers[registered with Jackson through a module], but Spring Boot provides an alternative `@JsonComponent` annotation that makes it easier to directly register Spring Beans. @@ -2332,14 +2332,14 @@ include::{include-springbootfeatures}/webapplications/json/object/MyJsonComponen -[[boot-features-spring-message-codes]] +[[features.developing-web-applications.spring-mvc.message-codes]] ==== MessageCodesResolver Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: `MessageCodesResolver`. If you set the configprop:spring.mvc.message-codes-resolver-format[] property `PREFIX_ERROR_CODE` or `POSTFIX_ERROR_CODE`, Spring Boot creates one for you (see the enumeration in {spring-framework-api}/validation/DefaultMessageCodesResolver.Format.html[`DefaultMessageCodesResolver.Format`]). -[[boot-features-spring-mvc-static-content]] +[[features.developing-web-applications.spring-mvc.static-content]] ==== Static Content By default, Spring Boot serves static content from a directory called `/static` (or `/public` or `/resources` or `/META-INF/resources`) in the classpath or from the root of the `ServletContext`. It uses the `ResourceHttpRequestHandler` from Spring MVC so that you can modify that behavior by adding your own `WebMvcConfigurer` and overriding the `addResourceHandlers` method. @@ -2424,7 +2424,7 @@ This feature has been thoroughly described in a dedicated https://spring.io/blog -[[boot-features-spring-mvc-welcome-page]] +[[features.developing-web-applications.spring-mvc.welcome-page]] ==== Welcome Page Spring Boot supports both static and templated welcome pages. It first looks for an `index.html` file in the configured static content locations. @@ -2433,7 +2433,7 @@ If either is found, it is automatically used as the welcome page of the applicat -[[boot-features-spring-mvc-pathmatch]] +[[features.developing-web-applications.spring-mvc.content-negotiation]] ==== Path Matching and Content Negotiation Spring MVC can map incoming HTTP requests to handlers by looking at the request path and matching it to the mappings defined in your application (for example, `@GetMapping` annotations on Controller methods). @@ -2525,14 +2525,14 @@ with a Servlet prefix (configprop:spring.mvc.servlet.path[]). -[[boot-features-spring-mvc-web-binding-initializer]] +[[features.developing-web-applications.spring-mvc.binding-initializer]] ==== ConfigurableWebBindingInitializer Spring MVC uses a `WebBindingInitializer` to initialize a `WebDataBinder` for a particular request. If you create your own `ConfigurableWebBindingInitializer` `@Bean`, Spring Boot automatically configures Spring MVC to use it. -[[boot-features-spring-mvc-template-engines]] +[[features.developing-web-applications.spring-mvc.template-engines]] ==== Template Engines As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. Spring MVC supports a variety of templating technologies, including Thymeleaf, FreeMarker, and JSPs. @@ -2546,7 +2546,7 @@ Spring Boot includes auto-configuration support for the following templating eng * https://mustache.github.io/[Mustache] TIP: If possible, JSPs should be avoided. -There are several <> when using them with embedded servlet containers. +There are several <> when using them with embedded servlet containers. When you use one of these templating engines with the default configuration, your templates are picked up automatically from `src/main/resources/templates`. @@ -2557,14 +2557,14 @@ If you have this problem, you can reorder the classpath in the IDE to place the -[[boot-features-error-handling]] +[[features.developing-web-applications.spring-mvc.error-handling]] ==== Error Handling By default, Spring Boot provides an `/error` mapping that handles all errors in a sensible way, and it is registered as a "`global`" error page in the servlet container. For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message. 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"] @@ -2591,7 +2591,7 @@ include::{include-springbootfeatures}/webapplications/servlet/MyController.java[ -[[boot-features-error-handling-custom-error-pages]] +[[features.developing-web-applications.spring-mvc.error-handling.error-pages]] ===== Custom Error Pages If you want to display a custom HTML error page for a given status code, you can add a file to an `/error` directory. Error pages can either be static HTML (that is, added under any of the static resource directories) or be built by using templates. @@ -2639,7 +2639,7 @@ The `ErrorController` then picks up any unhandled exceptions. -[[boot-features-error-handling-mapping-error-pages-without-mvc]] +[[features.developing-web-applications.spring-mvc.error-handling.error-pages-without-spring-mvc]] ===== Mapping Error Pages outside of Spring MVC For applications that do not use Spring MVC, you can use the `ErrorPageRegistrar` interface to directly register `ErrorPages`. This abstraction works directly with the underlying embedded servlet container and works even if you do not have a Spring MVC `DispatcherServlet`. @@ -2660,7 +2660,7 @@ Note that the default `FilterRegistrationBean` does not include the `ERROR` disp -[[boot-features-error-handling-war-deployment]] +[[features.developing-web-applications.spring-mvc.error-handling.in-a-war-deployment]] ===== Error handling in a war deployment When deployed to a servlet container, Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page. This is necessary as the Servlet specification does not provide an API for registering error pages. @@ -2675,7 +2675,7 @@ To do so, set the `spring.security.filter.dispatcher-types` property to `async, -[[boot-features-spring-hateoas]] +[[features.developing-web-applications.spring-mvc.spring-hateoas]] ==== Spring HATEOAS If you develop a RESTful API that makes use of hypermedia, Spring Boot provides auto-configuration for Spring HATEOAS that works well with most applications. The auto-configuration replaces the need to use `@EnableHypermediaSupport` and registers a number of beans to ease building hypermedia-based applications, including a `LinkDiscoverers` (for client side support) and an `ObjectMapper` configured to correctly marshal responses into the desired representation. @@ -2686,7 +2686,7 @@ Note that doing so disables the `ObjectMapper` customization described earlier. -[[boot-features-cors]] +[[features.developing-web-applications.spring-mvc.cors]] ==== CORS Support https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a https://www.w3.org/TR/cors/[W3C specification] implemented by https://caniuse.com/#feat=cors[most browsers] that lets you specify in a flexible way what kind of cross-domain requests are authorized., instead of using some less secure and less powerful approaches such as IFRAME or JSONP. @@ -2701,7 +2701,7 @@ include::{include-springbootfeatures}/webapplications/servlet/CorsConfiguration. -[[boot-features-webflux]] +[[features.developing-web-applications.spring-webflux]] === The "`Spring WebFlux Framework`" Spring WebFlux is the new reactive web framework introduced in Spring Framework 5.0. Unlike Spring MVC, it does not require the Servlet API, is fully asynchronous and non-blocking, and implements the https://www.reactive-streams.org/[Reactive Streams] specification through https://projectreactor.io/[the Reactor project]. @@ -2739,14 +2739,14 @@ You can still enforce your choice by setting the chosen application type to `Spr -[[boot-features-webflux-auto-configuration]] +[[features.developing-web-applications.spring-webflux.auto-configuration]] ==== Spring WebFlux Auto-configuration Spring Boot provides auto-configuration for Spring WebFlux that works well with most applications. The auto-configuration adds the following features on top of Spring's defaults: -* Configuring codecs for `HttpMessageReader` and `HttpMessageWriter` instances (described <>). -* Support for serving static resources, including support for WebJars (described <>). +* Configuring codecs for `HttpMessageReader` and `HttpMessageWriter` instances (described <>). +* Support for serving static resources, including support for WebJars (described <>). If you want to keep Spring Boot WebFlux features and you want to add additional {spring-framework-docs}/web-reactive.html#webflux-config[WebFlux configuration], you can add your own `@Configuration` class of type `WebFluxConfigurer` but *without* `@EnableWebFlux`. @@ -2754,7 +2754,7 @@ If you want to take complete control of Spring WebFlux, you can add your own `@C -[[boot-features-webflux-httpcodecs]] +[[features.developing-web-applications.spring-webflux.httpcodecs]] ==== HTTP Codecs with HttpMessageReaders and HttpMessageWriters Spring WebFlux uses the `HttpMessageReader` and `HttpMessageWriter` interfaces to convert HTTP requests and responses. They are configured with `CodecConfigurer` to have sensible defaults by looking at the libraries available in your classpath. @@ -2770,11 +2770,11 @@ If you need to add or customize codecs, you can create a custom `CodecCustomizer include::{include-springbootfeatures}/webapplications/webflux/CodecConfiguration.java[] ---- -You can also leverage <>. +You can also leverage <>. -[[boot-features-webflux-static-content]] +[[features.developing-web-applications.spring-webflux.static-content]] ==== Static Content By default, Spring Boot serves static content from a directory called `/static` (or `/public` or `/resources` or `/META-INF/resources`) in the classpath. It uses the `ResourceWebHandler` from Spring WebFlux so that you can modify that behavior by adding your own `WebFluxConfigurer` and overriding the `addResourceHandlers` method. @@ -2801,7 +2801,7 @@ TIP: Spring WebFlux applications do not strictly depend on the Servlet API, so t -[[boot-features-webflux-welcome-page]] +[[features.developing-web-applications.spring-webflux.welcome-page]] ==== Welcome Page Spring Boot supports both static and templated welcome pages. It first looks for an `index.html` file in the configured static content locations. @@ -2810,7 +2810,7 @@ If either is found, it is automatically used as the welcome page of the applicat -[[boot-features-webflux-template-engines]] +[[features.developing-web-applications.spring-webflux.template-engines]] ==== Template Engines As well as REST web services, you can also use Spring WebFlux to serve dynamic HTML content. Spring WebFlux supports a variety of templating technologies, including Thymeleaf, FreeMarker, and Mustache. @@ -2825,13 +2825,13 @@ When you use one of these templating engines with the default configuration, you -[[boot-features-webflux-error-handling]] +[[features.developing-web-applications.spring-webflux.error-handling]] ==== Error Handling Spring Boot provides a `WebExceptionHandler` that handles all errors in a sensible way. Its position in the processing order is immediately before the handlers provided by WebFlux, which are considered last. For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message. For browser clients, there is a "`whitelabel`" error handler that renders the same data in HTML format. -You can also provide your own HTML templates to display errors (see the <>). +You can also provide your own HTML templates to display errors (see the <>). The first step to customizing this feature often involves using the existing mechanism but replacing or augmenting the error contents. For that, you can add a bean of type `ErrorAttributes`. @@ -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"] @@ -2856,7 +2856,7 @@ include::{include-springbootfeatures}/webapplications/webflux/ExceptionHandlingC -[[boot-features-webflux-error-handling-custom-error-pages]] +[[features.developing-web-applications.spring-webflux.error-handling.error-pages]] ===== Custom Error Pages If you want to display a custom HTML error page for a given status code, you can add a file to an `/error` directory. Error pages can either be static HTML (that is, added under any of the static resource directories) or built with templates. @@ -2894,7 +2894,7 @@ To map all `5xx` errors by using a Mustache template, your directory structure w -[[boot-features-webflux-web-filters]] +[[features.developing-web-applications.spring-webflux.web-filters]] ==== Web Filters Spring WebFlux provides a `WebFilter` interface that can be implemented to filter HTTP request-response exchanges. `WebFilter` beans found in the application context will be automatically used to filter each exchange. @@ -2918,7 +2918,7 @@ When it does so, the orders shown in the following table will be used: -[[boot-features-jersey]] +[[features.developing-web-applications.jersey]] === JAX-RS and Jersey If you prefer the JAX-RS programming model for REST endpoints, you can use one of the available implementations instead of Spring MVC. https://jersey.github.io/[Jersey] and https://cxf.apache.org/[Apache CXF] work quite well out of the box. @@ -2933,7 +2933,7 @@ include::{include-springbootfeatures}/webapplications/jersey/JerseyConfig.java[] ---- WARNING: Jersey's support for scanning executable archives is rather limited. -For example, it cannot scan for endpoints in a package found in a <> or in `WEB-INF/classes` when running an executable war file. +For example, it cannot scan for endpoints in a package found in a <> or in `WEB-INF/classes` when running an executable war file. To avoid this limitation, the `packages` method should not be used, and endpoints should be registered individually by using the `register` method, as shown in the preceding example. For more advanced customizations, you can also register an arbitrary number of beans that implement `ResourceConfigCustomizer`. @@ -2958,7 +2958,7 @@ Both the servlet and the filter registrations can be given init parameters by us -[[boot-features-embedded-container]] +[[features.developing-web-applications.embedded-container]] === Embedded Servlet Container Support Spring Boot includes support for embedded https://tomcat.apache.org/[Tomcat], https://www.eclipse.org/jetty/[Jetty], and https://github.com/undertow-io/undertow[Undertow] servers. Most developers use the appropriate "`Starter`" to obtain a fully configured instance. @@ -2966,13 +2966,13 @@ By default, the embedded server listens for HTTP requests on port `8080`. -[[boot-features-embedded-container-servlets-filters-listeners]] +[[features.developing-web-applications.embedded-container.servlets-filters-listeners]] ==== Servlets, Filters, and listeners When using an embedded servlet container, you can register servlets, filters, and all the listeners (such as `HttpSessionListener`) from the Servlet spec, either by using Spring beans or by scanning for Servlet components. -[[boot-features-embedded-container-servlets-filters-listeners-beans]] +[[features.developing-web-applications.embedded-container.servlets-filters-listeners.beans]] ===== Registering Servlets, Filters, and Listeners as Spring Beans Any `Servlet`, `Filter`, or servlet `*Listener` instance that is a Spring bean is registered with the embedded container. This can be particularly convenient if you want to refer to a value from your `application.properties` during configuration. @@ -2990,7 +2990,7 @@ If you cannot change the `Filter` class to add `@Order` or implement `Ordered`, Avoid configuring a Filter that reads the request body at `Ordered.HIGHEST_PRECEDENCE`, since it might go against the character encoding configuration of your application. If a Servlet filter wraps the request, it should be configured with an order that is less than or equal to `OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER`. -TIP: To see the order of every `Filter` in your application, enable debug level logging for the `web` <> (`logging.level.web=debug`). +TIP: To see the order of every `Filter` in your application, enable debug level logging for the `web` <> (`logging.level.web=debug`). Details of the registered filters, including their order and URL patterns, will then be logged at startup. WARNING: Take care when registering `Filter` beans since they are initialized very early in the application lifecycle. @@ -2998,7 +2998,7 @@ If you need to register a `Filter` that interacts with other beans, consider usi -[[boot-features-embedded-container-context-initializer]] +[[features.developing-web-applications.embedded-container.context-initializer]] ==== Servlet Context Initialization Embedded servlet containers do not directly execute the Servlet 3.0+ `javax.servlet.ServletContainerInitializer` interface or Spring's `org.springframework.web.WebApplicationInitializer` interface. This is an intentional design decision intended to reduce the risk that third party libraries designed to run inside a war may break Spring Boot applications. @@ -3008,7 +3008,7 @@ The single `onStartup` method provides access to the `ServletContext` and, if ne -[[boot-features-embedded-container-servlets-filters-listeners-scanning]] +[[features.developing-web-applications.embedded-container.context-initializer.scanning]] ===== Scanning for Servlets, Filters, and listeners When using an embedded container, automatic registration of classes annotated with `@WebServlet`, `@WebFilter`, and `@WebListener` can be enabled by using `@ServletComponentScan`. @@ -3016,7 +3016,7 @@ TIP: `@ServletComponentScan` has no effect in a standalone container, where the -[[boot-features-embedded-container-application-context]] +[[features.developing-web-applications.embedded-container.application-context]] ==== The ServletWebServerApplicationContext Under the hood, Spring Boot uses a different type of `ApplicationContext` for embedded servlet container support. The `ServletWebServerApplicationContext` is a special type of `WebApplicationContext` that bootstraps itself by searching for a single `ServletWebServerFactory` bean. @@ -3027,7 +3027,7 @@ Most applications are auto-configured, and the appropriate `ApplicationContext` -[[boot-features-customizing-embedded-containers]] +[[features.developing-web-applications.embedded-container.customizing]] ==== Customizing Embedded Servlet Containers Common servlet container settings can be configured by using Spring `Environment` properties. Usually, you would define the properties in your `application.properties` or `application.yaml` file. @@ -3037,18 +3037,18 @@ Common server settings include: * Network settings: Listen port for incoming HTTP requests (`server.port`), interface address to bind to `server.address`, and so on. * Session settings: Whether the session is persistent (`server.servlet.session.persistent`), session timeout (`server.servlet.session.timeout`), location of session data (`server.servlet.session.store-dir`), and session-cookie configuration (`server.servlet.session.cookie.*`). * Error management: Location of the error page (`server.error.path`) and so on. -* <> -* <> +* <> +* <> Spring Boot tries as much as possible to expose common settings, but this is not always possible. For those cases, dedicated namespaces offer server-specific customizations (see `server.tomcat` and `server.undertow`). -For instance, <> can be configured with specific features of the embedded servlet container. +For instance, <> can be configured with specific features of the embedded servlet container. TIP: See the {spring-boot-autoconfigure-module-code}/web/ServerProperties.java[`ServerProperties`] class for a complete list. -[[boot-features-programmatic-embedded-container-customization]] +[[features.developing-web-applications.embedded-container.customizing.programmatic]] ===== Programmatic Customization If you need to programmatically configure your embedded servlet container, you can register a Spring bean that implements the `WebServerFactoryCustomizer` interface. `WebServerFactoryCustomizer` provides access to the `ConfigurableServletWebServerFactory`, which includes numerous customization setter methods. @@ -3069,7 +3069,7 @@ include::{include-springbootfeatures}/webapplications/embeddedservletcontainer/T -[[boot-features-customizing-configurableservletwebserverfactory-directly]] +[[features.developing-web-applications.embedded-container.customizing.direct]] ===== Customizing ConfigurableServletWebServerFactory Directly For more advanced use cases that require you to extend from `ServletWebServerFactory`, you can expose a bean of such type yourself. @@ -3081,7 +3081,7 @@ NOTE: Auto-configured customizers are still applied on your custom factory, so u -[[boot-features-jsp-limitations]] +[[features.developing-web-applications.embedded-container.jsp-limitations]] ==== JSP Limitations When running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support. @@ -3091,12 +3091,12 @@ When running a Spring Boot application that uses an embedded servlet container ( * Undertow does not support JSPs. -* Creating a custom `error.jsp` page does not override the default view for <>. - <> should be used instead. +* Creating a custom `error.jsp` page does not override the default view for <>. + <> should be used instead. -[[boot-features-reactive-server]] +[[features.developing-web-applications.reactive-server]] === Embedded Reactive Server Support Spring Boot includes support for the following embedded reactive web servers: Reactor Netty, Tomcat, Jetty, and Undertow. Most developers use the appropriate “Starter” to obtain a fully configured instance. @@ -3104,7 +3104,7 @@ By default, the embedded server listens for HTTP requests on port 8080. -[[boot-features-reactive-server-resources]] +[[features.developing-web-applications.reactive-server-resources-configuration]] === Reactive Server Resources Configuration When auto-configuring a Reactor Netty or Jetty server, Spring Boot will create specific beans that will provide HTTP resources to the server instance: `ReactorResourceFactory` or `JettyResourceFactory`. @@ -3115,11 +3115,11 @@ By default, those resources will be also shared with the Reactor Netty and Jetty Developers can override the resource configuration for Jetty and Reactor Netty by providing a custom `ReactorResourceFactory` or `JettyResourceFactory` bean - this will be applied to both clients and servers. -You can learn more about the resource configuration on the client side in the <>. +You can learn more about the resource configuration on the client side in the <>. -[[boot-features-graceful-shutdown]] +[[features.graceful-shutdown]] == Graceful shutdown Graceful shutdown is supported with all four embedded web servers (Jetty, Reactor Netty, Tomcat, and Undertow) and with both reactive and Servlet-based web applications. It occurs as part of closing the application context and is performed in the earliest phase of stopping `SmartLifecycle` beans. @@ -3152,7 +3152,7 @@ Refer to the documentation of your IDE for more details. -[[boot-features-rsocket]] +[[features.rsocket]] == RSocket https://rsocket.io[RSocket] is a binary protocol for use on byte stream transports. It enables symmetric interaction models via async message passing over a single connection. @@ -3163,7 +3163,7 @@ See the {spring-framework-docs}/web-reactive.html#rsocket-spring[RSocket section -[[boot-features-rsocket-strategies-auto-configuration]] +[[features.rsocket.strategies-auto-configuration]] === RSocket Strategies Auto-configuration Spring Boot auto-configures an `RSocketStrategies` bean that provides all the required infrastructure for encoding and decoding RSocket payloads. By default, the auto-configuration will try to configure the following (in order): @@ -3172,14 +3172,14 @@ By default, the auto-configuration will try to configure the following (in order . JSON codecs with Jackson The `spring-boot-starter-rsocket` starter provides both dependencies. -Check out the <> to know more about customization possibilities. +Check out the <> to know more about customization possibilities. Developers can customize the `RSocketStrategies` component by creating beans that implement the `RSocketStrategiesCustomizer` interface. Note that their `@Order` is important, as it determines the order of codecs. -[[boot-features-rsocket-server-auto-configuration]] +[[features.rsocket.server-auto-configuration]] === RSocket server Auto-configuration Spring Boot provides RSocket server auto-configuration. The required dependencies are provided by the `spring-boot-starter-rsocket`. @@ -3213,7 +3213,7 @@ Besides the dependency requirements, the only required configuration is to defin -[[boot-features-rsocket-messaging]] +[[features.rsocket.messaging]] === Spring Messaging RSocket support Spring Boot will auto-configure the Spring Messaging infrastructure for RSocket. @@ -3221,7 +3221,7 @@ This means that Spring Boot will create a `RSocketMessageHandler` bean that will -[[boot-features-rsocket-requester]] +[[features.rsocket.requester]] === Calling RSocket Services with RSocketRequester Once the `RSocket` channel is established between server and client, any party can send or receive requests to the other. @@ -3241,7 +3241,7 @@ include::{include-springbootfeatures}/rsocket/MyService.java[] -[[boot-features-security]] +[[features.security]] == Security If {spring-security}[Spring Security] is on the classpath, then web applications are secured by default. Spring Boot relies on Spring Security’s content-negotiation strategy to determine whether to use `httpBasic` or `formLogin`. @@ -3271,7 +3271,7 @@ You can provide a different `AuthenticationEventPublisher` by adding a bean for -[[boot-features-security-mvc]] +[[features.security.spring-mvc]] === MVC Security The default security configuration is implemented in `SecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`. `SecurityAutoConfiguration` imports `SpringBootWebSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications. @@ -3286,7 +3286,7 @@ Spring Boot provides convenience methods that can be used to override access rul -[[boot-features-security-webflux]] +[[features.security.spring-webflux]] === WebFlux Security Similar to Spring MVC applications, you can secure your WebFlux applications by adding the `spring-boot-starter-security` dependency. The default security configuration is implemented in `ReactiveSecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`. @@ -3310,13 +3310,13 @@ include::{include-springbootfeatures}/security/CustomWebFluxSecurityConfiguratio -[[boot-features-security-oauth2]] +[[features.security.oauth2]] === OAuth2 https://oauth.net/2/[OAuth2] is a widely used authorization framework that is supported by Spring. -[[boot-features-security-oauth2-client]] +[[features.security.oauth2.client]] ==== Client If you have `spring-security-oauth2-client` on your classpath, you can take advantage of some auto-configuration to set up an OAuth2/Open ID Connect clients. This configuration makes use of the properties under `OAuth2ClientProperties`. @@ -3393,7 +3393,7 @@ For production environments, consider using a `JdbcOAuth2AuthorizedClientService -[[boot-features-security-oauth2-common-providers]] +[[features.security.oauth2.client.common-providers]] ===== OAuth2 client registration for common providers For common OAuth2 and OpenID providers, including Google, Github, Facebook, and Okta, we provide a set of provider defaults (`google`, `github`, `facebook`, and `okta`, respectively). @@ -3420,7 +3420,7 @@ In other words, the two configurations in the following example use the Google p -[[boot-features-security-oauth2-server]] +[[features.security.oauth2.server]] ==== Resource Server If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server. For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples: @@ -3472,7 +3472,7 @@ Alternatively, you can define your own `OpaqueTokenIntrospector` bean for servle -[[boot-features-security-authorization-server]] +[[features.security.oauth2.authorization-server]] ==== Authorization Server Currently, Spring Security does not provide support for implementing an OAuth 2.0 Authorization Server. However, this functionality is available from the {spring-security-oauth2}[Spring Security OAuth] project, which will eventually be superseded by Spring Security completely. @@ -3480,12 +3480,12 @@ Until then, you can use the `spring-security-oauth2-autoconfigure` module to eas -[[boot-features-security-saml]] +[[features.security.saml2]] === SAML 2.0 -[[boot-features-security-saml2-relying-party]] +[[features.security.saml2.relying-party]] ==== Relying Party If you have `spring-security-saml2-service-provider` on your classpath, you can take advantage of some auto-configuration to set up a SAML 2.0 Relying Party. This configuration makes use of the properties under `Saml2RelyingPartyProperties`. @@ -3534,7 +3534,7 @@ You can register multiple relying parties under the `spring.security.saml2.relyi -[[boot-features-security-actuator]] +[[features.security.actuator]] === Actuator Security For security purposes, all actuators other than `/health` are disabled by default. The configprop:management.endpoints.web.exposure.include[] property can be used to enable the actuators. @@ -3546,7 +3546,7 @@ NOTE: Before setting the `management.endpoints.web.exposure.include`, ensure tha -[[boot-features-security-csrf]] +[[features.security.actuator.csrf]] ==== Cross Site Request Forgery Protection Since Spring Boot relies on Spring Security's defaults, CSRF protection is turned on by default. This means that the actuator endpoints that require a `POST` (shutdown and loggers endpoints), `PUT` or `DELETE` will get a 403 forbidden error when the default security configuration is in use. @@ -3557,29 +3557,29 @@ Additional information about CSRF protection can be found in the {spring-securit -[[boot-features-sql]] +[[features.sql]] == Working with SQL Databases The {spring-framework}[Spring Framework] provides extensive support for working with SQL databases, from direct JDBC access using `JdbcTemplate` to complete "`object relational mapping`" technologies such as Hibernate. {spring-data}[Spring Data] provides an additional level of functionality: creating `Repository` implementations directly from interfaces and using conventions to generate queries from your method names. -[[boot-features-configure-datasource]] +[[features.sql.datasource]] === Configure a DataSource Java's `javax.sql.DataSource` interface provides a standard method of working with database connections. Traditionally, a 'DataSource' uses a `URL` along with some credentials to establish a database connection. -TIP: See <> for more advanced examples, typically to take full control over the configuration of the DataSource. +TIP: See <> for more advanced examples, typically to take full control over the configuration of the DataSource. -[[boot-features-embedded-database-support]] +[[features.sql.datasource.embedded]] ==== Embedded Database Support It is often convenient to develop applications by using an in-memory embedded database. Obviously, in-memory databases do not provide persistent storage. You need to populate your database when your application starts and be prepared to throw away data when your application ends. -TIP: The "`How-to`" section includes a <>. +TIP: The "`How-to`" section includes a <>. Spring Boot can auto-configure embedded https://www.h2database.com[H2], http://hsqldb.org/[HSQL], and https://db.apache.org/derby/[Derby] databases. You need not provide any connection URLs. @@ -3618,13 +3618,13 @@ Disabling the database's automatic shutdown lets Spring Boot control when the da -[[boot-features-connect-to-production-database]] +[[features.sql.datasource.production]] ==== Connection to a Production Database Production database connections can also be auto-configured by using a pooling `DataSource`. -[[boot-features-connect-to-production-database-configuration]] +[[features.sql.datasource.configuration]] ==== DataSource Configuration DataSource configuration is controlled by external configuration properties in `+spring.datasource.*+`. For example, you might declare the following section in `application.properties`: @@ -3648,7 +3648,7 @@ NOTE: For a pooling `DataSource` to be created, we need to be able to verify tha In other words, if you set `spring.datasource.driver-class-name=com.mysql.jdbc.Driver`, then that class has to be loadable. See {spring-boot-autoconfigure-module-code}/jdbc/DataSourceProperties.java[`DataSourceProperties`] for more of the supported options. -These are the standard options that work regardless of <>. +These are the standard options that work regardless of <>. It is also possible to fine-tune implementation-specific settings by using their respective prefix (`+spring.datasource.hikari.*+`, `+spring.datasource.tomcat.*+`, `+spring.datasource.dbcp2.*+`, and `+spring.datasource.oracleucp.*+`). Refer to the documentation of the connection pool implementation you are using for more details. @@ -3668,7 +3668,7 @@ This will set the pool to wait 10000 ms before throwing an exception if no conne -[[boot-features-connect-to-production-database-connection-pool]] +[[features.sql.datasource.connection-pool]] ==== Supported Connection Pools Spring Boot uses the following algorithm for choosing a specific implementation: @@ -3697,7 +3697,7 @@ The following connection pools are supported by `DataSourceBuilder`: -[[boot-features-connecting-to-a-jndi-datasource]] +[[features.sql.configure-datasource.jndi]] ==== Connection to a JNDI DataSource If you deploy your Spring Boot application to an Application Server, you might want to configure and manage your DataSource by using your Application Server's built-in features and access it by using JNDI. @@ -3713,7 +3713,7 @@ For example, the following section in `application.properties` shows how you can -[[boot-features-using-jdbc-template]] +[[features.sql.jdbc-template]] === Using JdbcTemplate Spring's `JdbcTemplate` and `NamedParameterJdbcTemplate` classes are auto-configured, and you can `@Autowire` them directly into your own beans, as shown in the following example: @@ -3737,7 +3737,7 @@ If more than one `JdbcTemplate` is defined and no primary candidate exists, the -[[boot-features-jpa-and-spring-data]] +[[features.sql.jpa-and-spring-data]] === JPA and Spring Data JPA The Java Persistence API is a standard technology that lets you "`map`" objects to relational databases. The `spring-boot-starter-data-jpa` POM provides a quick way to get started. @@ -3752,7 +3752,7 @@ You can follow the https://spring.io/guides/gs/accessing-data-jpa/["`Accessing D -[[boot-features-entity-classes]] +[[features.sql.jpa-and-spring-data.entity-classes]] ==== Entity Classes Traditionally, JPA "`Entity`" classes are specified in a `persistence.xml` file. With Spring Boot, this file is not necessary and "`Entity Scanning`" is used instead. @@ -3767,11 +3767,11 @@ include::{include-springbootfeatures}/sql/jpa/City.java[] ---- TIP: You can customize entity scanning locations by using the `@EntityScan` annotation. -See the "`<>`" how-to. +See the "`<>`" how-to. -[[boot-features-spring-data-jpa-repositories]] +[[features.sql.jpa-and-spring-data.repositories]] ==== Spring Data JPA Repositories {spring-data-jpa}[Spring Data JPA] repositories are interfaces that you can define to access data. JPA queries are created automatically from your method names. @@ -3806,7 +3806,7 @@ For complete details, see the {spring-data-jdbc-docs}[Spring Data JPA reference -[[boot-features-creating-and-dropping-jpa-databases]] +[[features.sql.jpa-and-spring-data.creating-and-dropping]] ==== Creating and Dropping JPA Databases By default, JPA databases are automatically created *only* if you use an embedded database (H2, HSQL, or Derby). You can explicitly configure JPA settings by using `+spring.jpa.*+` properties. @@ -3833,14 +3833,14 @@ There is also a `spring.jpa.generate-ddl` flag, but it is not used if Hibernate -[[boot-features-jpa-in-web-environment]] +[[features.sql.jpa-and-spring-data.open-entity-manager-in-view]] ==== Open EntityManager in View If you are running a web application, Spring Boot by default registers {spring-framework-api}/orm/jpa/support/OpenEntityManagerInViewInterceptor.html[`OpenEntityManagerInViewInterceptor`] to apply the "`Open EntityManager in View`" pattern, to allow for lazy loading in web views. If you do not want this behavior, you should set `spring.jpa.open-in-view` to `false` in your `application.properties`. -[[boot-features-data-jdbc]] +[[features.sql.jdbc]] === Spring Data JDBC Spring Data includes repository support for JDBC and will automatically generate SQL for the methods on `CrudRepository`. For more advanced queries, a `@Query` annotation is provided. @@ -3853,14 +3853,14 @@ TIP: For complete details of Spring Data JDBC, please refer to the {spring-data- -[[boot-features-sql-h2-console]] +[[features.sql.h2-web-console]] === Using H2's Web Console The https://www.h2database.com[H2 database] provides a https://www.h2database.com/html/quickstart.html#h2_console[browser-based console] that Spring Boot can auto-configure for you. 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`. @@ -3868,21 +3868,21 @@ NOTE: The H2 console is only intended for use during development, so you should -[[boot-features-sql-h2-console-custom-path]] +[[features.sql.h2-web-console.custom-path]] ==== Changing the H2 Console's Path By default, the console is available at `/h2-console`. You can customize the console's path by using the configprop:spring.h2.console.path[] property. -[[boot-features-jooq]] +[[features.sql.jooq]] === Using jOOQ jOOQ Object Oriented Querying (https://www.jooq.org/[jOOQ]) is a popular product from https://www.datageekery.com/[Data Geekery] which generates Java code from your database and lets you build type-safe SQL queries through its fluent API. Both the commercial and open source editions can be used with Spring Boot. -[[boot-features-jooq-codegen]] +[[features.sql.jooq.codegen]] ==== Code Generation In order to use jOOQ type-safe queries, you need to generate Java classes from your database schema. You can follow the instructions in the {jooq-docs}/#jooq-in-7-steps-step3[jOOQ user manual]. @@ -3919,7 +3919,7 @@ The following listing shows an example: -[[boot-features-jooq-dslcontext]] +[[features.sql.jooq.dslcontext]] ==== Using DSLContext The fluent API offered by jOOQ is initiated through the `org.jooq.DSLContext` interface. Spring Boot auto-configures a `DSLContext` as a Spring Bean and connects it to your application `DataSource`. @@ -3941,7 +3941,7 @@ include::{include-springbootfeatures}/sql/jooq/JooqExample.java[tag=method] -[[boot-features-jooq-sqldialect]] +[[features.sql.jooq.sqldialect]] ==== jOOQ SQL Dialect Unless the configprop:spring.jooq.sql-dialect[] property has been configured, Spring Boot determines the SQL dialect to use for your datasource. If Spring Boot could not detect the dialect, it uses `DEFAULT`. @@ -3950,7 +3950,7 @@ NOTE: Spring Boot can only auto-configure dialects supported by the open source -[[boot-features-jooq-customizing]] +[[features.sql.jooq.customizing]] ==== Customizing jOOQ More advanced customizations can be achieved by defining your own `DefaultConfigurationCustomizer` bean that will be invoked prior to creating the `org.jooq.Configuration` `@Bean`. This takes precedence to anything that is applied by the auto-configuration. @@ -3959,7 +3959,7 @@ You can also create your own `org.jooq.Configuration` `@Bean` if you want to tak -[[boot-features-r2dbc]] +[[features.sql.r2dbc]] === Using R2DBC The Reactive Relational Database Connectivity (https://r2dbc.io[R2DBC]) project brings reactive programming APIs to relational databases. R2DBC's `io.r2dbc.spi.Connection` provides a standard method of working with non-blocking database connections. @@ -3982,7 +3982,7 @@ TIP: You do not need to specify a driver class name, since Spring Boot obtains t NOTE: At least the url should be provided. Information specified in the URL takes precedence over individual properties, i.e. `name`, `username`, `password` and pooling options. -TIP: The "`How-to`" section includes a <>. +TIP: The "`How-to`" section includes a <>. To customize the connections created by a `ConnectionFactory`, i.e., set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a `ConnectionFactoryOptionsBuilderCustomizer` `@Bean`. The following example shows how to manually override the database port while the rest of the options is taken from the application configuration: @@ -4004,9 +4004,9 @@ If you want to retain the JDBC `DataSource` auto-configuration, and are comforta -[[boot-features-r2dbc-embedded-database]] +[[features.sql.r2dbc.embedded]] ==== Embedded Database Support -Similarly to <>, Spring Boot can automatically configure an embedded database for reactive usage. +Similarly to <>, Spring Boot can automatically configure an embedded database for reactive usage. You need not provide any connection URLs. You need only include a build dependency to the embedded database that you want to use, as shown in the following example: @@ -4027,7 +4027,7 @@ If you want to make sure that each context has a separate embedded database, you -[[boot-features-r2dbc-using-database-client]] +[[features.sql.r2dbc.using-database-client]] ==== Using DatabaseClient A `DatabaseClient` bean is auto-configured, and you can `@Autowire` it directly into your own beans, as shown in the following example: @@ -4038,7 +4038,7 @@ include::{include-springbootfeatures}/sql/r2dbc/databaseclient/MyBean.java[tag=* -[[boot-features-spring-data-r2dbc-repositories]] +[[features.sql.r2dbc.repositories]] ==== Spring Data R2DBC Repositories https://spring.io/projects/spring-data-r2dbc[Spring Data R2DBC] repositories are interfaces that you can define to access data. Queries are created automatically from your method names. @@ -4060,7 +4060,7 @@ TIP: We have barely scratched the surface of Spring Data R2DBC. For complete det -[[boot-features-nosql]] +[[features.nosql]] == Working with NoSQL Technologies Spring Data provides additional projects that help you access a variety of NoSQL technologies, including: @@ -4079,7 +4079,7 @@ Refer to the appropriate reference documentation at {spring-data}. -[[boot-features-redis]] +[[features.nosql.redis]] === Redis https://redis.io/[Redis] is a cache, message broker, and richly-featured key-value store. Spring Boot offers basic auto-configuration for the https://github.com/lettuce-io/lettuce-core/[Lettuce] and https://github.com/xetorthio/jedis/[Jedis] client libraries and the abstractions on top of them provided by https://github.com/spring-projects/spring-data-redis[Spring Data Redis]. @@ -4092,7 +4092,7 @@ TIP: We also provide a `spring-boot-starter-data-redis-reactive` "`Starter`" for -[[boot-features-connecting-to-redis]] +[[features.nosql.redis.connecting]] ==== Connecting to Redis You can inject an auto-configured `RedisConnectionFactory`, `StringRedisTemplate`, or vanilla `RedisTemplate` instance as you would any other Spring Bean. By default, the instance tries to connect to a Redis server at `localhost:6379`. @@ -4111,14 +4111,14 @@ By default, if `commons-pool2` is on the classpath, you get a pooled connection -[[boot-features-mongodb]] +[[features.nosql.mongodb]] === MongoDB https://www.mongodb.com/[MongoDB] is an open-source NoSQL document database that uses a JSON-like schema instead of traditional table-based relational data. Spring Boot offers several conveniences for working with MongoDB, including the `spring-boot-starter-data-mongodb` and `spring-boot-starter-data-mongodb-reactive` "`Starters`". -[[boot-features-connecting-to-mongodb]] +[[features.nosql.mongodb.connecting]] ==== Connecting to a MongoDB Database To access MongoDB databases, you can inject an auto-configured `org.springframework.data.mongodb.MongoDatabaseFactory`. By default, the instance tries to connect to a MongoDB server at `mongodb://localhost/test`. @@ -4170,7 +4170,7 @@ The auto-configuration configures this factory automatically if Netty is availab -[[boot-features-mongo-template]] +[[features.nosql.mongodb.template]] ==== MongoTemplate {spring-data-mongodb}[Spring Data MongoDB] provides a {spring-data-mongodb-api}/core/MongoTemplate.html[`MongoTemplate`] class that is very similar in its design to Spring's `JdbcTemplate`. As with `JdbcTemplate`, Spring Boot auto-configures a bean for you to inject the template, as follows: @@ -4184,8 +4184,8 @@ See the {spring-data-mongodb-api}/core/MongoOperations.html[`MongoOperations` Ja -[[boot-features-spring-data-mongo-repositories]] -[[boot-features-spring-data-mongodb-repositories]] +[[features.nosql.mongodb.repositories]] +[[features.nosql.mongodb.repositories]] ==== Spring Data MongoDB Repositories Spring Data includes repository support for MongoDB. As with the JPA repositories discussed earlier, the basic principle is that queries are constructed automatically, based on method names. @@ -4204,7 +4204,7 @@ TIP: For complete details of Spring Data MongoDB, including its rich object mapp -[[boot-features-mongo-embedded]] +[[features.nosql.mongodb.embedded]] ==== Embedded Mongo Spring Boot offers auto-configuration for https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Embedded Mongo]. To use it in your Spring Boot application, add a dependency on `de.flapdoodle.embed:de.flapdoodle.embed.mongo`. @@ -4222,14 +4222,14 @@ The download configuration can be customized by declaring a `DownloadConfigBuild -[[boot-features-neo4j]] +[[features.nosql.neo4j]] === Neo4j https://neo4j.com/[Neo4j] is an open-source NoSQL graph database that uses a rich data model of nodes connected by first class relationships, which is better suited for connected big data than traditional RDBMS approaches. Spring Boot offers several conveniences for working with Neo4j, including the `spring-boot-starter-data-neo4j` "`Starter`". -[[boot-features-connecting-to-neo4j]] +[[features.nosql.neo4j.connecting]] ==== Connecting to a Neo4j Database To access a Neo4j server, you can inject an auto-configured `org.neo4j.driver.Driver`. By default, the instance tries to connect to a Neo4j server at `localhost:7687` using the Bolt protocol. @@ -4259,7 +4259,7 @@ Each will be called in order with the `ConfigBuilder` that is used to build the -[[boot-features-spring-data-neo4j-repositories]] +[[features.nosql.neo4j.repositories]] ==== Spring Data Neo4j Repositories Spring Data includes repository support for Neo4j. For complete details of Spring Data Neo4j, refer to the {spring-data-neo4j-docs}[reference documentation]. @@ -4291,14 +4291,14 @@ include::{include-springbootfeatures}/nosql/Neo4jReactiveTransactionManagerConfi -[[boot-features-solr]] +[[features.nosql.solr]] === Solr https://lucene.apache.org/solr/[Apache Solr] is a search engine. Spring Boot offers basic auto-configuration for the Solr 5 client library. -[[boot-features-connecting-to-solr]] +[[features.nosql.solr.connecting]] ==== Connecting to Solr You can inject an auto-configured `SolrClient` instance as you would any other Spring bean. By default, the instance tries to connect to a server at `http://localhost:8983/solr`. @@ -4313,7 +4313,7 @@ If you add your own `@Bean` of type `SolrClient`, it replaces the default. -[[boot-features-elasticsearch]] +[[features.nosql.elasticsearch]] === Elasticsearch https://www.elastic.co/products/elasticsearch[Elasticsearch] is an open source, distributed, RESTful search and analytics engine. Spring Boot offers basic auto-configuration for Elasticsearch. @@ -4327,7 +4327,7 @@ Spring Boot provides a dedicated "`Starter`", `spring-boot-starter-data-elastics -[[boot-features-connecting-to-elasticsearch-rest]] +[[features.nosql.elasticsearch.connecting-using-rest]] ==== Connecting to Elasticsearch using REST clients Elasticsearch ships https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html[two different REST clients] that you can use to query a cluster: the "Low Level" client and the "High Level" client. Spring Boot provides support for the "High Level" client, which ships with `org.elasticsearch.client:elasticsearch-rest-high-level-client`. @@ -4366,7 +4366,7 @@ You can further tune how `Sniffer` is configured, as shown in the following exam -[[boot-features-connecting-to-elasticsearch-reactive-rest]] +[[features.nosql.elasticsearch.connecting-using-reactive-rest]] ==== Connecting to Elasticsearch using Reactive REST clients {spring-data-elasticsearch}[Spring Data Elasticsearch] ships `ReactiveElasticsearchClient` for querying Elasticsearch instances in a reactive fashion. It is built on top of WebFlux's `WebClient`, so both `spring-boot-starter-elasticsearch` and `spring-boot-starter-webflux` dependencies are useful to enable this support. @@ -4394,7 +4394,7 @@ configuration, you can register a custom `ClientConfiguration` bean. -[[boot-features-connecting-to-elasticsearch-spring-data]] +[[features.nosql.elasticsearch.connecting-using-spring-data]] ==== Connecting to Elasticsearch by Using Spring Data To connect to Elasticsearch, a `RestHighLevelClient` bean must be defined, auto-configured by Spring Boot or manually provided by the application (see previous sections). @@ -4407,12 +4407,12 @@ as shown in the following example: include::{include-springbootfeatures}/nosql/elasticsearch/template/MyBean.java[] ---- -In the presence of `spring-data-elasticsearch` and the required dependencies for using a `WebClient` (typically `spring-boot-starter-webflux`), Spring Boot can also auto-configure a <> and a `ReactiveElasticsearchTemplate` as beans. +In the presence of `spring-data-elasticsearch` and the required dependencies for using a `WebClient` (typically `spring-boot-starter-webflux`), Spring Boot can also auto-configure a <> and a `ReactiveElasticsearchTemplate` as beans. They are the reactive equivalent of the other REST clients. -[[boot-features-spring-data-elasticsearch-repositories]] +[[features.nosql.elasticsearch.repositories]] ==== Spring Data Elasticsearch Repositories Spring Data includes repository support for Elasticsearch. As with the JPA repositories discussed earlier, the basic principle is that queries are constructed for you automatically based on method names. @@ -4441,7 +4441,7 @@ You can choose to disable the repositories support with the following property: -[[boot-features-cassandra]] +[[features.nosql.cassandra]] === Cassandra https://cassandra.apache.org/[Cassandra] is an open source, distributed database management system designed to handle large amounts of data across many commodity servers. Spring Boot offers auto-configuration for Cassandra and the abstractions on top of it provided by https://github.com/spring-projects/spring-data-cassandra[Spring Data Cassandra]. @@ -4449,7 +4449,7 @@ There is a `spring-boot-starter-data-cassandra` "`Starter`" for collecting the d -[[boot-features-connecting-to-cassandra]] +[[features.nosql.cassandra.connecting]] ==== Connecting to Cassandra You can inject an auto-configured `CassandraTemplate` or a Cassandra `CqlSession` instance as you would with any other Spring Bean. The `spring.data.cassandra.*` properties can be used to customize the connection. @@ -4504,7 +4504,7 @@ If you add your own `@Bean` of type `CassandraTemplate`, it replaces the default -[[boot-features-spring-data-cassandra-repositories]] +[[features.nosql.cassandra.repositories]] ==== Spring Data Cassandra Repositories Spring Data includes basic repository support for Cassandra. Currently, this is more limited than the JPA repositories discussed earlier and needs to annotate finder methods with `@Query`. @@ -4513,7 +4513,7 @@ TIP: For complete details of Spring Data Cassandra, refer to the https://docs.sp -[[boot-features-couchbase]] +[[features.nosql.couchbase]] === Couchbase https://www.couchbase.com/[Couchbase] is an open-source, distributed, multi-model NoSQL document-oriented database that is optimized for interactive applications. Spring Boot offers auto-configuration for Couchbase and the abstractions on top of it provided by https://github.com/spring-projects/spring-data-couchbase[Spring Data Couchbase]. @@ -4521,7 +4521,7 @@ There are `spring-boot-starter-data-couchbase` and `spring-boot-starter-data-cou -[[boot-features-connecting-to-couchbase]] +[[features.nosql.couchbase.connecting]] ==== Connecting to Couchbase You can get a `Cluster` by adding the Couchbase SDK and some configuration. The `spring.couchbase.*` properties can be used to customize the connection. @@ -4556,7 +4556,7 @@ To take more control, one or more `ClusterEnvironmentBuilderCustomizer` beans ca -[[boot-features-spring-data-couchbase-repositories]] +[[features.nosql.couchbase.repositories]] ==== Spring Data Couchbase Repositories Spring Data includes repository support for Couchbase. For complete details of Spring Data Couchbase, refer to the {spring-data-couchbase-docs}[reference documentation]. @@ -4595,7 +4595,7 @@ include::{include-springbootfeatures}/nosql/couchbase/CouchbaseConversionsConfig -[[boot-features-ldap]] +[[features.nosql.ldap]] === LDAP https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol[LDAP] (Lightweight Directory Access Protocol) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an IP network. Spring Boot offers auto-configuration for any compliant LDAP server as well as support for the embedded in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID]. @@ -4605,7 +4605,7 @@ There is a `spring-boot-starter-data-ldap` "`Starter`" for collecting the depend -[[boot-features-ldap-connecting]] +[[features.nosql.ldap.connecting]] ==== Connecting to an LDAP Server To connect to an LDAP server, make sure you declare a dependency on the `spring-boot-starter-data-ldap` "`Starter`" or `spring-ldap-core` and then declare the URLs of your server in your application.properties, as shown in the following example: @@ -4627,7 +4627,7 @@ Make sure to flag your customized `ContextSource` as `@Primary` so that the auto -[[boot-features-ldap-spring-data-repositories]] +[[features.nosql.ldap.repositories]] ==== Spring Data LDAP Repositories Spring Data includes repository support for LDAP. For complete details of Spring Data LDAP, refer to the https://docs.spring.io/spring-data/ldap/docs/1.0.x/reference/html/[reference documentation]. @@ -4642,7 +4642,7 @@ include::{include-springbootfeatures}/nosql/ldap/template/MyBean.java[] -[[boot-features-ldap-embedded]] +[[features.nosql.ldap.embedded]] ==== Embedded In-memory LDAP Server For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID]. To configure the server, add a dependency to `com.unboundid:unboundid-ldapsdk` and declare a configprop:spring.ldap.embedded.base-dn[] property, as follows: @@ -4681,13 +4681,13 @@ If you have custom attributes, you can use configprop:spring.ldap.embedded.valid -[[boot-features-influxdb]] +[[features.nosql.influxdb]] === InfluxDB https://www.influxdata.com/[InfluxDB] is an open-source time series database optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet-of-Things sensor data, and real-time analytics. -[[boot-features-connecting-to-influxdb]] +[[features.nosql.influxdb.connecting]] ==== Connecting to InfluxDB Spring Boot auto-configures an `InfluxDB` instance, provided the `influxdb-java` client is on the classpath and the URL of the database is set, as shown in the following example: @@ -4707,7 +4707,7 @@ If you need more control over the configuration, consider registering an `Influx -[[boot-features-caching]] +[[features.caching]] == Caching The Spring Framework provides support for transparently adding caching to an application. At its core, the abstraction applies caching to methods, thus reducing the number of executions based on the information available in the cache. @@ -4731,7 +4731,7 @@ Otherwise, the method is invoked, and the cache is updated before returning the CAUTION: You can also use the standard JSR-107 (JCache) annotations (such as `@CacheResult`) transparently. However, we strongly advise you to not mix and match the Spring Cache and JCache annotations. -If you do not add any specific cache library, Spring Boot auto-configures a <> that uses concurrent maps in memory. +If you do not add any specific cache library, Spring Boot auto-configures a <> that uses concurrent maps in memory. When a cache is required (such as `piDecimals` in the preceding example), this provider creates it for you. The simple provider is not really recommended for production usage, but it is great for getting started and making sure that you understand the features. When you have made up your mind about the cache provider to use, please make sure to read its documentation to figure out how to configure the caches that your application uses. @@ -4742,24 +4742,24 @@ TIP: It is also possible to transparently {spring-framework-docs}/integration.ht -[[boot-features-caching-provider]] +[[features.caching.provider]] === Supported Cache Providers The cache abstraction does not provide an actual store and relies on abstraction materialized by the `org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces. If you have not defined a bean of type `CacheManager` or a `CacheResolver` named `cacheResolver` (see {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`]), Spring Boot tries to detect the following providers (in the indicated order): -. <> -. <> (EhCache 3, Hazelcast, Infinispan, and others) -. <> -. <> -. <> -. <> -. <> -. <> -. <> +. <> +. <> (EhCache 3, Hazelcast, Infinispan, and others) +. <> +. <> +. <> +. <> +. <> +. <> +. <> TIP: It is also possible to _force_ a particular cache provider by setting the configprop:spring.cache.type[] property. -Use this property if you need to <> in certain environment (such as tests). +Use this property if you need to <> in certain environment (such as tests). TIP: Use the `spring-boot-starter-cache` "`Starter`" to quickly add basic caching dependencies. The starter brings in `spring-context-support`. @@ -4779,14 +4779,14 @@ You can have as many customizers as you want, and you can also order them by usi -[[boot-features-caching-provider-generic]] +[[features.caching.provider.generic]] ==== Generic Generic caching is used if the context defines _at least_ one `org.springframework.cache.Cache` bean. A `CacheManager` wrapping all beans of that type is created. -[[boot-features-caching-provider-jcache]] +[[features.caching.provider.jcache]] ==== JCache (JSR-107) https://jcp.org/en/jsr/detail?id=107[JCache] is bootstrapped through the presence of a `javax.cache.spi.CachingProvider` on the classpath (that is, a JSR-107 compliant caching library exists on the classpath), and the `JCacheCacheManager` is provided by the `spring-boot-starter-cache` "`Starter`". Various compliant libraries are available, and Spring Boot provides dependency management for Ehcache 3, Hazelcast, and Infinispan. @@ -4807,7 +4807,7 @@ Even if the JSR-107 standard does not enforce a standardized way to define the l NOTE: When a cache library offers both a native implementation and JSR-107 support, Spring Boot prefers the JSR-107 support, so that the same features are available if you switch to a different JSR-107 implementation. -TIP: Spring Boot has <>. +TIP: Spring Boot has <>. If a single `HazelcastInstance` is available, it is automatically reused for the `CacheManager` as well, unless the configprop:spring.cache.jcache.config[] property is specified. There are two ways to customize the underlying `javax.cache.cacheManager`: @@ -4821,7 +4821,7 @@ No further customization is applied to it. -[[boot-features-caching-provider-ehcache2]] +[[features.caching.provider.ehcache2]] ==== EhCache 2.x https://www.ehcache.org/[EhCache] 2.x is used if a file named `ehcache.xml` can be found at the root of the classpath. If EhCache 2.x is found, the `EhCacheCacheManager` provided by the `spring-boot-starter-cache` "`Starter`" is used to bootstrap the cache manager. @@ -4837,14 +4837,14 @@ An alternate configuration file can be provided as well, as shown in the followi -[[boot-features-caching-provider-hazelcast]] +[[features.caching.provider.hazelcast]] ==== Hazelcast -Spring Boot has <>. +Spring Boot has <>. If a `HazelcastInstance` has been auto-configured, it is automatically wrapped in a `CacheManager`. -[[boot-features-caching-provider-infinispan]] +[[features.caching.provider.infinispan]] ==== Infinispan https://infinispan.org/[Infinispan] has no default configuration file location, so it must be specified explicitly. Otherwise, the default bootstrap is used. @@ -4866,9 +4866,9 @@ See https://github.com/infinispan/infinispan-spring-boot[Infinispan's documentat -[[boot-features-caching-provider-couchbase]] +[[features.caching.provider.couchbase]] ==== Couchbase -If Spring Data Couchbase is available and Couchbase is <>, a `CouchbaseCacheManager` is auto-configured. +If Spring Data Couchbase is available and Couchbase is <>, a `CouchbaseCacheManager` is auto-configured. It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.couchbase.*` properties. For instance, the following configuration creates `cache1` and `cache2` caches with an entry _expiration_ of 10 minutes: @@ -4891,7 +4891,7 @@ include::{include-springbootfeatures}/nosql/CouchbaseCacheManagerConfiguration.j -[[boot-features-caching-provider-redis]] +[[features.caching.provider.redis]] ==== Redis If https://redis.io/[Redis] is available and configured, a `RedisCacheManager` is auto-configured. It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.redis.*` properties. @@ -4922,7 +4922,7 @@ include::{include-springbootfeatures}/nosql/RedisCacheManagerConfiguration.java[ -[[boot-features-caching-provider-caffeine]] +[[features.caching.provider.caffeine]] ==== Caffeine https://github.com/ben-manes/caffeine[Caffeine] is a Java 8 rewrite of Guava's cache that supersedes support for Guava. If Caffeine is present, a `CaffeineCacheManager` (provided by the `spring-boot-starter-cache` "`Starter`") is auto-configured. @@ -4949,7 +4949,7 @@ The auto-configuration ignores any other generic type. -[[boot-features-caching-provider-simple]] +[[features.caching.provider.simple]] ==== Simple If none of the other providers can be found, a simple implementation using a `ConcurrentHashMap` as the cache store is configured. This is the default if no caching library is present in your application. @@ -4968,7 +4968,7 @@ This is similar to the way the "real" cache providers behave if you use an undec -[[boot-features-caching-provider-none]] +[[features.caching.provider.none]] ==== None When `@EnableCaching` is present in your configuration, a suitable cache configuration is expected as well. If you need to disable caching altogether in certain environments, force the cache type to `none` to use a no-op implementation, as shown in the following example: @@ -4982,7 +4982,7 @@ If you need to disable caching altogether in certain environments, force the cac -[[boot-features-messaging]] +[[features.messaging]] == Messaging The Spring Framework provides extensive support for integrating with messaging systems, from simplified use of the JMS API using `JmsTemplate` to a complete infrastructure to receive messages asynchronously. Spring AMQP provides a similar feature set for the Advanced Message Queuing Protocol. @@ -4992,7 +4992,7 @@ Spring Boot also has support for Apache Kafka. -[[boot-features-jms]] +[[features.messaging.jms]] === JMS The `javax.jms.ConnectionFactory` interface provides a standard method of creating a `javax.jms.Connection` for interacting with a JMS broker. Although Spring needs a `ConnectionFactory` to work with JMS, you generally need not use it directly yourself and can instead rely on higher level messaging abstractions. @@ -5001,7 +5001,7 @@ Spring Boot also auto-configures the necessary infrastructure to send and receiv -[[boot-features-activemq]] +[[features.messaging.jms.activemq]] ==== ActiveMQ Support When https://activemq.apache.org/[ActiveMQ] is available on the classpath, Spring Boot can also configure a `ConnectionFactory`. If the broker is present, an embedded broker is automatically started and configured (provided no broker URL is specified through configuration). @@ -5048,7 +5048,7 @@ By default, ActiveMQ creates a destination if it does not yet exist so that dest -[[boot-features-artemis]] +[[features.messaging.jms.artemis]] ==== ActiveMQ Artemis Support Spring Boot can auto-configure a `ConnectionFactory` when it detects that https://activemq.apache.org/components/artemis/[ActiveMQ Artemis] is available on the classpath. If the broker is present, an embedded broker is automatically started and configured (unless the mode property has been explicitly set). @@ -5101,7 +5101,7 @@ No JNDI lookup is involved, and destinations are resolved against their names, u -[[boot-features-jms-jndi]] +[[features.messaging.jms.jndi]] ==== Using a JNDI ConnectionFactory If you are running your application in an application server, Spring Boot tries to locate a JMS `ConnectionFactory` by using JNDI. By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked. @@ -5116,7 +5116,7 @@ You can use the configprop:spring.jms.jndi-name[] property if you need to specif -[[boot-features-using-jms-sending]] +[[features.messaging.jms.sending]] ==== Sending a Message Spring's `JmsTemplate` is auto-configured, and you can autowire it directly into your own beans, as shown in the following example: @@ -5130,7 +5130,7 @@ If a `DestinationResolver` or a `MessageConverter` bean is defined, it is associ -[[boot-features-using-jms-receiving]] +[[features.messaging.jms.receiving]] ==== Receiving a Message When the JMS infrastructure is present, any bean can be annotated with `@JmsListener` to create a listener endpoint. If no `JmsListenerContainerFactory` has been defined, a default one is configured automatically. @@ -5170,7 +5170,7 @@ include::{include-springbootfeatures}/messaging/jms/receiving/custom/MyBean.java -[[boot-features-amqp]] +[[features.messaging.amqp]] === AMQP The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol for message-oriented middleware. The Spring AMQP project applies core Spring concepts to the development of AMQP-based messaging solutions. @@ -5178,7 +5178,7 @@ Spring Boot offers several conveniences for working with AMQP through RabbitMQ, -[[boot-features-rabbitmq]] +[[features.messaging.amqp.rabbitmq]] ==== RabbitMQ support https://www.rabbitmq.com/[RabbitMQ] is a lightweight, reliable, scalable, and portable message broker based on the AMQP protocol. Spring uses `RabbitMQ` to communicate through the AMQP protocol. @@ -5217,7 +5217,7 @@ TIP: See https://spring.io/blog/2010/06/14/understanding-amqp-the-protocol-used- -[[boot-features-using-amqp-sending]] +[[features.messaging.amqp.sending]] ==== Sending a Message Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured, and you can autowire them directly into your own beans, as shown in the following example: @@ -5250,7 +5250,7 @@ If you need to create more `RabbitTemplate` instances or if you want to override -[[boot-features-using-amqp-receiving]] +[[features.messaging.amqp.receiving]] ==== Receiving a Message When the Rabbit infrastructure is present, any bean can be annotated with `@RabbitListener` to create a listener endpoint. If no `RabbitListenerContainerFactory` has been defined, a default `SimpleRabbitListenerContainerFactory` is automatically configured and you can switch to a direct container using the configprop:spring.rabbitmq.listener.type[] property. @@ -5296,7 +5296,7 @@ The latter is the mechanism used when retries are enabled and the maximum number -[[boot-features-kafka]] +[[features.messaging.kafka]] === Apache Kafka Support https://kafka.apache.org/[Apache Kafka] is supported by providing auto-configuration of the `spring-kafka` project. @@ -5319,7 +5319,7 @@ See {spring-boot-autoconfigure-module-code}/kafka/KafkaProperties.java[`KafkaPro -[[boot-features-kafka-sending-a-message]] +[[features.messaging.kafka.sending]] ==== Sending a Message Spring's `KafkaTemplate` is auto-configured, and you can autowire it directly in your own beans, as shown in the following example: @@ -5333,7 +5333,7 @@ Also, if a `RecordMessageConverter` bean is defined, it is automatically associa -[[boot-features-kafka-receiving-a-message]] +[[features.messaging.kafka.receiving]] ==== Receiving a Message When the Apache Kafka infrastructure is present, any bean can be annotated with `@KafkaListener` to create a listener endpoint. If no `KafkaListenerContainerFactory` has been defined, a default one is automatically configured with keys defined in `spring.kafka.listener.*`. @@ -5355,7 +5355,7 @@ TIP: A custom `ChainedKafkaTransactionManager` must be marked `@Primary` as it u -[[boot-features-kafka-streams]] +[[features.messaging.kafka.streams]] ==== Kafka Streams Spring for Apache Kafka provides a factory bean to create a `StreamsBuilder` object and manage the lifecycle of its streams. Spring Boot auto-configures the required `KafkaStreamsConfiguration` bean as long as `kafka-streams` is on the classpath and Kafka Streams is enabled via the `@EnableKafkaStreams` annotation. @@ -5365,7 +5365,7 @@ The former can be configured using `spring.kafka.streams.application-id`, defaul The latter can be set globally or specifically overridden only for streams. Several additional properties are available using dedicated properties; other arbitrary Kafka properties can be set using the `spring.kafka.streams.properties` namespace. -See also <> for more information. +See also <> for more information. To use the factory bean, wire `StreamsBuilder` into your `@Bean` as shown in the following example: @@ -5379,7 +5379,7 @@ You can customize this behaviour using the configprop:spring.kafka.streams.auto- -[[boot-features-kafka-extra-props]] +[[features.messaging.kafka.additional-properties]] ==== Additional Kafka Properties 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. @@ -5443,7 +5443,7 @@ IMPORTANT: Properties set in this way override any configuration item that Sprin -[[boot-features-embedded-kafka]] +[[features.messaging.kafka.embedded]] ==== Testing with Embedded Kafka Spring for Apache Kafka provides a convenient way to test projects with an embedded Apache Kafka broker. To use this feature, annotate a test class with `@EmbeddedKafka` from the `spring-kafka-test` module. @@ -5477,7 +5477,7 @@ include::{include-springbootfeatures}/messaging/kafka/test/annotation/MyTest.jav -[[boot-features-resttemplate]] +[[features.resttemplate]] == Calling REST Services with RestTemplate If you need to call remote REST services from your application, you can use the Spring Framework's {spring-framework-api}/web/client/RestTemplate.html[`RestTemplate`] class. Since `RestTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `RestTemplate` bean. @@ -5496,7 +5496,7 @@ For example, to add BASIC auth support, you can use `builder.basicAuthentication -[[boot-features-resttemplate-customization]] +[[features.resttemplate.customization]] === RestTemplate Customization There are three main approaches to `RestTemplate` customization, depending on how broadly you want the customizations to apply. @@ -5527,14 +5527,14 @@ Doing so switches off the auto-configuration of a `RestTemplateBuilder` and prev -[[boot-features-webclient]] +[[features.webclient]] == Calling REST Services with WebClient If you have Spring WebFlux on your classpath, you can also choose to use `WebClient` to call remote REST services. Compared to `RestTemplate`, this client has a more functional feel and is fully reactive. You can learn more about the `WebClient` in the dedicated {spring-framework-docs}/web-reactive.html#webflux-client[section in the Spring Framework docs]. Spring Boot creates and pre-configures a `WebClient.Builder` for you; it is strongly advised to inject it in your components and use it to create `WebClient` instances. -Spring Boot is configuring that builder to share HTTP resources, reflect codecs setup in the same fashion as the server ones (see <>), and more. +Spring Boot is configuring that builder to share HTTP resources, reflect codecs setup in the same fashion as the server ones (see <>), and more. The following code shows a typical example: @@ -5545,7 +5545,7 @@ include::{include-springbootfeatures}/webclient/MyService.java[] -[[boot-features-webclient-runtime]] +[[features.webclient.runtime]] === WebClient Runtime Spring Boot will auto-detect which `ClientHttpConnector` to use to drive `WebClient`, depending on the libraries available on the application classpath. For now, Reactor Netty and Jetty RS client are supported. @@ -5562,7 +5562,7 @@ You can learn more about the {spring-framework-docs}/web-reactive.html#webflux-c -[[boot-features-webclient-customization]] +[[features.webclient.customization]] === WebClient Customization There are three main approaches to `WebClient` customization, depending on how broadly you want the customizations to apply. @@ -5577,7 +5577,7 @@ In that case, no auto-configuration or `WebClientCustomizer` is applied. -[[boot-features-validation]] +[[features.validation]] == Validation The method validation feature supported by Bean Validation 1.1 is automatically enabled as long as a JSR-303 implementation (such as Hibernate validator) is on the classpath. This lets bean methods be annotated with `javax.validation` constraints on their parameters and/or on their return value. @@ -5592,7 +5592,7 @@ include::{include-springbootfeatures}/validation/MyBean.java[] -[[boot-features-email]] +[[features.email]] == Sending Email The Spring Framework provides an abstraction for sending email by using the `JavaMailSender` interface, and Spring Boot provides auto-configuration for it as well as a starter module. @@ -5627,7 +5627,7 @@ When a `jndi-name` is set, it takes precedence over all other Session-related se -[[boot-features-jta]] +[[features.jta]] == Distributed Transactions with JTA Spring Boot supports distributed JTA transactions across multiple XA resources by using an https://www.atomikos.com/[Atomikos] embedded transaction manager. JTA transactions are also supported when deploying to a suitable Java EE Application Server. @@ -5639,7 +5639,7 @@ If you are within a JTA environment and still want to use local transactions, yo -[[boot-features-jta-atomikos]] +[[features.jta.atomikos]] === Using an Atomikos Transaction Manager https://www.atomikos.com/[Atomikos] is a popular open source transaction manager which can be embedded into your Spring Boot application. You can use the `spring-boot-starter-jta-atomikos` starter to pull in the appropriate Atomikos libraries. @@ -5656,16 +5656,16 @@ To ensure uniqueness in production, you should configure the configprop:spring.j -[[boot-features-jta-javaee]] +[[features.jta.javaee]] === Using a Java EE Managed Transaction Manager If you package your Spring Boot application as a `war` or `ear` file and deploy it to a Java EE application server, you can use your application server's built-in transaction manager. Spring Boot tries to auto-configure a transaction manager by looking at common JNDI locations (`java:comp/UserTransaction`, `java:comp/TransactionManager`, and so on). If you use a transaction service provided by your application server, you generally also want to ensure that all resources are managed by the server and exposed over JNDI. -Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the <> to configure your `DataSource`. +Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the <> to configure your `DataSource`. -[[boot-features-jta-mixed-jms]] +[[features.jta.mixing-xa-and-non-xa-connections]] === Mixing XA and Non-XA JMS Connections When using JTA, the primary JMS `ConnectionFactory` bean is XA-aware and participates in distributed transactions. You can inject into your bean without needing to use any `@Qualifier`: @@ -5694,7 +5694,7 @@ include::{include-springbootfeatures}/jta/xa/MyBean.java[tag=*] -[[boot-features-jta-supporting-alternative-embedded]] +[[features.jta.supporting-alternative-embedded-transaction-manager]] === Supporting an Alternative Embedded Transaction Manager The {spring-boot-module-code}/jms/XAConnectionFactoryWrapper.java[`XAConnectionFactoryWrapper`] and {spring-boot-module-code}/jdbc/XADataSourceWrapper.java[`XADataSourceWrapper`] interfaces can be used to support alternative embedded transaction managers. The interfaces are responsible for wrapping `XAConnectionFactory` and `XADataSource` beans and exposing them as regular `ConnectionFactory` and `DataSource` beans, which transparently enroll in the distributed transaction. @@ -5704,7 +5704,7 @@ The {spring-boot-module-code}/jta/atomikos/AtomikosXAConnectionFactoryWrapper.ja -[[boot-features-hazelcast]] +[[features.hazelcast]] == Hazelcast If https://hazelcast.com/[Hazelcast] is on the classpath and a suitable configuration is found, Spring Boot auto-configures a `HazelcastInstance` that you can inject in your application. @@ -5736,12 +5736,12 @@ Otherwise, Spring Boot tries to find the Hazelcast configuration from the defaul We also check if the `hazelcast.config` system property is set. See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast documentation] for more details. -NOTE: Spring Boot also has <>. +NOTE: Spring Boot also has <>. If caching is enabled, the `HazelcastInstance` is automatically wrapped in a `CacheManager` implementation. -[[boot-features-quartz]] +[[features.quartz]] == Quartz Scheduler Spring Boot offers several conveniences for working with the https://www.quartz-scheduler.org/[Quartz scheduler], including the `spring-boot-starter-quartz` "`Starter`". If Quartz is available, a `Scheduler` is auto-configured (through the `SchedulerFactoryBean` abstraction). @@ -5800,7 +5800,7 @@ include::{include-springbootfeatures}/quartz/SampleJob.java[] -[[boot-features-task-execution-scheduling]] +[[features.task-execution-and-scheduling]] == Task Execution and Scheduling In the absence of an `Executor` bean in the context, Spring Boot auto-configures a `ThreadPoolTaskExecutor` with sensible defaults that can be automatically associated to asynchronous task execution (`@EnableAsync`) and Spring MVC asynchronous request processing. @@ -5846,13 +5846,13 @@ Both a `TaskExecutorBuilder` bean and a `TaskSchedulerBuilder` bean are made ava -[[boot-features-integration]] +[[features.spring-integration]] == Spring Integration Spring Boot offers several conveniences for working with {spring-integration}[Spring Integration], including the `spring-boot-starter-integration` "`Starter`". Spring Integration provides abstractions over messaging and also other transports such as HTTP, TCP, and others. If Spring Integration is available on your classpath, it is initialized through the `@EnableIntegration` annotation. -Spring Integration polling logic relies <>. +Spring Integration polling logic relies <>. Spring Boot also configures some features that are triggered by the presence of additional Spring Integration modules. If `spring-integration-jmx` is also on the classpath, message processing statistics are published over JMX. @@ -5899,7 +5899,7 @@ If you wish to use legacy Spring Integration metrics, add a `DefaultMetricsFacto -[[boot-features-session]] +[[features.spring-session]] == Spring Session Spring Boot provides {spring-session}[Spring Session] auto-configuration for a wide range of data stores. When building a Servlet web application, the following stores can be auto-configured: @@ -5952,7 +5952,7 @@ Spring Session can then be configured using the annotation's attributes rather t -[[boot-features-jmx]] +[[features.jmx]] == Monitoring and Management over JMX Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications. Spring Boot exposes the most suitable `MBeanServer` as a bean with an ID of `mbeanServer`. @@ -5965,7 +5965,7 @@ See the {spring-boot-autoconfigure-module-code}/jmx/JmxAutoConfiguration.java[`J -[[boot-features-testing]] +[[features.testing]] == Testing Spring Boot provides a number of utilities and annotations to help when testing your application. Test support is provided by two modules: `spring-boot-test` contains core items, and `spring-boot-test-autoconfigure` supports auto-configuration for tests. @@ -5997,7 +5997,7 @@ To use the vintage engine, add a dependency on `junit-vintage-engine`, as shown -[[boot-features-test-scope-dependencies]] +[[features.testing.test-scope-dependencies]] === Test Scope Dependencies The `spring-boot-starter-test` "`Starter`" (in the `test` `scope`) contains the following provided libraries: @@ -6014,7 +6014,7 @@ If these libraries do not suit your needs, you can add additional test dependenc -[[boot-features-testing-spring-applications]] +[[features.testing.spring-applications]] === Testing Spring Applications One of the major advantages of dependency injection is that it should make your code easier to unit test. You can instantiate objects by using the `new` operator without even involving Spring. @@ -6030,15 +6030,15 @@ If you have not used the `spring-test` module before, you should start by readin -[[boot-features-testing-spring-boot-applications]] +[[features.testing.spring-boot-applications]] === Testing Spring Boot Applications A Spring Boot application is a Spring `ApplicationContext`, so nothing very special has to be done to test it beyond what you would normally do with a vanilla Spring context. NOTE: External properties, logging, and other features of Spring Boot are installed in the context by default only if you use `SpringApplication` to create it. Spring Boot provides a `@SpringBootTest` annotation, which can be used as an alternative to the standard `spring-test` `@ContextConfiguration` annotation when you need Spring Boot features. -The annotation works by <>. -In addition to `@SpringBootTest` a number of other annotations are also provided for <> of an application. +The annotation works by <>. +In addition to `@SpringBootTest` a number of other annotations are also provided for <> of an application. TIP: If you are using JUnit 4, don't forget to also add `@RunWith(SpringRunner.class)` to your test, otherwise the annotations will be ignored. If you are using JUnit 5, there's no need to add the equivalent `@ExtendWith(SpringExtension.class)` as `@SpringBootTest` and the other `@…Test` annotations are already annotated with it. @@ -6049,7 +6049,7 @@ You can use the `webEnvironment` attribute of `@SpringBootTest` to further refin * `MOCK`(Default) : Loads a web `ApplicationContext` and provides a mock web environment. Embedded servers are not started when using this annotation. If a web environment is not available on your classpath, this mode transparently falls back to creating a regular non-web `ApplicationContext`. - It can be used in conjunction with <> for mock-based testing of your web application. + It can be used in conjunction with <> for mock-based testing of your web application. * `RANDOM_PORT`: Loads a `WebServerApplicationContext` and provides a real web environment. Embedded servers are started and listen on a random port. * `DEFINED_PORT`: Loads a `WebServerApplicationContext` and provides a real web environment. @@ -6064,7 +6064,7 @@ NOTE: `@SpringBootTest` with `webEnvironment = WebEnvironment.RANDOM_PORT` will -[[boot-features-testing-spring-boot-applications-detecting-web-app-type]] +[[features.testing.spring-boot-applications.detecting-web-app-type]] ==== Detecting Web Application Type If Spring MVC is available, a regular MVC-based application context is configured. If you have only Spring WebFlux, we'll detect that and configure a WebFlux-based application context instead. @@ -6079,7 +6079,7 @@ include::{include-springbootfeatures}/testing/applications/detection/MyWebFluxTe -[[boot-features-testing-spring-boot-applications-detecting-config]] +[[features.testing.spring-boot-applications.detecting-configuration]] ==== Detecting Test Configuration If you are familiar with the Spring Test Framework, you may be used to using `@ContextConfiguration(classes=...)` in order to specify which Spring `@Configuration` to load. Alternatively, you might have often used nested `@Configuration` classes within your test. @@ -6088,11 +6088,11 @@ 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] ==== -If you use a <>, you should avoid adding configuration settings that are specific to a particular area on the <>. +If you use a <>, you should avoid adding configuration settings that are specific to a particular area on the <>. The underlying component scan configuration of `@SpringBootApplication` defines exclude filters that are used to make sure slicing works as expected. If you are using an explicit `@ComponentScan` directive on your `@SpringBootApplication`-annotated class, be aware that those filters will be disabled. @@ -6107,11 +6107,11 @@ Therefore, as long as your tests share the same configuration (no matter how it -[[boot-features-testing-spring-boot-applications-excluding-config]] +[[features.testing.spring-boot-applications.excluding-configuration]] ==== Excluding Test Configuration If your application uses component scanning (for example, if you use `@SpringBootApplication` or `@ComponentScan`), you may find top-level configuration classes that you created only for specific tests accidentally get picked up everywhere. -As we <>, `@TestConfiguration` can be used on an inner class of a test to customize the primary configuration. +As we <>, `@TestConfiguration` can be used on an inner class of a test to customize the primary configuration. When placed on a top-level class, `@TestConfiguration` indicates that classes in `src/test/java` should not be picked up by scanning. You can then import that class explicitly where it is required, as shown in the following example: @@ -6125,9 +6125,9 @@ See {spring-boot-module-api}/context/TypeExcludeFilter.html[the Javadoc] for det -[[boot-features-testing-spring-boot-application-arguments]] +[[features.testing.spring-boot-applications.using-application-arguments]] ==== Using Application Arguments -If your application expects <>, you can +If your application expects <>, you can have `@SpringBootTest` inject them using the `args` attribute. [source,java,indent=0] @@ -6137,7 +6137,7 @@ include::{include-springbootfeatures}/testing/ApplicationArgumentTests.java[] -[[boot-features-testing-spring-boot-applications-testing-with-mock-environment]] +[[features.testing.spring-boot-applications.with-mock-environment]] ==== Testing with a mock environment By default, `@SpringBootTest` does not start the server. If you have web endpoints that you want to test against this mock environment, you can additionally configure {spring-framework-docs}/testing.html#spring-mvc-test-framework[`MockMvc`] as shown in the following example: @@ -6147,7 +6147,7 @@ If you have web endpoints that you want to test against this mock environment, y include::{include-springbootfeatures}/testing/MockMvcTests.java[] ---- -TIP: If you want to focus only on the web layer and not start a complete `ApplicationContext`, consider <>. +TIP: If you want to focus only on the web layer and not start a complete `ApplicationContext`, consider <>. Alternatively, you can configure a {spring-framework-docs}/testing.html#webtestclient-tests[`WebTestClient`] as shown in the following example: @@ -6162,18 +6162,18 @@ Testing within a mocked environment is usually faster than running with a full S However, since mocking occurs at the Spring MVC layer, code that relies on lower-level Servlet container behavior cannot be directly tested with MockMvc. For example, Spring Boot's error handling is based on the "`error page`" support provided by the Servlet container. -This means that, whilst you can test your MVC layer throws and handles exceptions as expected, you cannot directly test that a specific <> is rendered. +This means that, whilst you can test your MVC layer throws and handles exceptions as expected, you cannot directly test that a specific <> is rendered. If you need to test these lower-level concerns, you can start a fully running server as described in the next section. ==== -[[boot-features-testing-spring-boot-applications-testing-with-running-server]] +[[features.testing.spring-boot-applications.with-running-server]] ==== Testing with a running server If you need to start a full running server, we recommend that you use random ports. If you use `@SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT)`, an available port is picked at random each time your test runs. -The `@LocalServerPort` annotation can be used to <> into your test. +The `@LocalServerPort` annotation can be used to <> into your test. For convenience, tests that need to make REST calls to the started server can additionally `@Autowire` a {spring-framework-docs}/testing.html#webtestclient-tests[`WebTestClient`], which resolves relative links to the running server and comes with a dedicated API for verifying responses, as shown in the following example: [source,java,indent=0] @@ -6191,14 +6191,14 @@ include::{include-springbootfeatures}/testing/RandomPortTestRestTemplateTests.ja -[[boot-features-testing-spring-boot-applications-customizing-web-test-client]] +[[features.testing.spring-boot-applications.customizing-web-test-client]] ==== Customizing WebTestClient To customize the `WebTestClient` bean, configure a `WebTestClientBuilderCustomizer` bean. Any such beans are called with the `WebTestClient.Builder` that is used to create the `WebTestClient`. -[[boot-features-testing-spring-boot-applications-jmx]] +[[features.testing.spring-boot-applications.jmx]] ==== Using JMX As the test context framework caches context, JMX is disabled by default to prevent identical components to register on the same domain. If such test needs access to an `MBeanServer`, consider marking it dirty as well: @@ -6210,7 +6210,7 @@ include::{include-springbootfeatures}/testing/jmx/SampleJmxTests.java[] -[[boot-features-testing-spring-boot-applications-metrics]] +[[features.testing.spring-boot-applications.metrics]] ==== Using Metrics Regardless of your classpath, meter registries, except the in-memory backed, are not auto-configured when using `@SpringBootTest`. @@ -6218,7 +6218,7 @@ If you need to export metrics to a different backend as part of an integration t -[[boot-features-testing-spring-boot-applications-mocking-beans]] +[[features.testing.spring-boot-applications.mocking-beans]] ==== Mocking and Spying Beans When running tests, it is sometimes necessary to mock certain components within your application context. For example, you may have a facade over some remote service that is unavailable during development. @@ -6271,7 +6271,7 @@ Use `AopTestUtils.getTargetObject(yourProxiedSpy)` to do so. -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-tests]] +[[features.testing.spring-boot-applications.autoconfigured-tests]] ==== Auto-configured Tests Spring Boot's auto-configuration system works well for applications but can sometimes be a little too much for tests. It often helps to load only the parts of the configuration that are required to test a "`slice`" of your application. @@ -6292,7 +6292,7 @@ You can use this combination if you are not interested in "`slicing`" your appli -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-json-tests]] +[[features.testing.spring-boot-applications.json-tests]] ==== Auto-configured JSON Tests To test that object JSON serialization and deserialization is working as expected, you can use the `@JsonTest` annotation. `@JsonTest` auto-configures the available supported JSON mapper, which can be one of the following libraries: @@ -6329,7 +6329,7 @@ include::{include-springbootfeatures}/testing/applications/json/AssertJ.java[tag -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests]] +[[features.testing.spring-boot-applications.spring-mvc-tests]] ==== Auto-configured Spring MVC Tests To test whether Spring MVC controllers are working as expected, use the `@WebMvcTest` annotation. `@WebMvcTest` auto-configures the Spring MVC infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `Converter`, `GenericConverter`, `Filter`, `HandlerInterceptor`, `WebMvcConfigurer`, and `HandlerMethodArgumentResolver`. @@ -6371,13 +6371,13 @@ If you define your own `webDriver` scope you may find it stops working when you If you have Spring Security on the classpath, `@WebMvcTest` will also scan `WebSecurityConfigurer` beans. Instead of disabling security completely for such tests, you can use Spring Security's test support. -More details on how to use Spring Security's `MockMvc` support can be found in this _<>_ how-to section. +More details on how to use Spring Security's `MockMvc` support can be found in this _<>_ how-to section. -TIP: Sometimes writing Spring MVC tests is not enough; Spring Boot can help you run <>. +TIP: Sometimes writing Spring MVC tests is not enough; Spring Boot can help you run <>. -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-webflux-tests]] +[[features.testing.spring-boot-applications.spring-webflux-tests]] ==== Auto-configured Spring WebFlux Tests To test that {spring-framework-docs}/web-reactive.html[Spring WebFlux] controllers are working as expected, you can use the `@WebFluxTest` annotation. `@WebFluxTest` auto-configures the Spring WebFlux infrastructure and limits scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `Converter`, `GenericConverter`, `WebFilter`, and `WebFluxConfigurer`. @@ -6408,17 +6408,17 @@ For testing `RouterFunction` beans in the context, consider importing your `Rout NOTE: `@WebFluxTest` cannot detect custom security configuration registered via a `@Bean` of type `SecurityWebFilterChain`. To include that in your test, you will need to import the configuration that registers the bean via `@Import` or use `@SpringBootTest`. -TIP: Sometimes writing Spring WebFlux tests is not enough; Spring Boot can help you run <>. +TIP: Sometimes writing Spring WebFlux tests is not enough; Spring Boot can help you run <>. -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-cassandra-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-cassandra]] ==== Auto-configured Data Cassandra Tests You can use `@DataCassandraTest` to test Cassandra applications. By default, it configures a `CassandraTemplate`, scans for `@Table` classes, and configures Spring Data Cassandra repositories. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataCassandraTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -(For more about using Cassandra with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6431,7 +6431,7 @@ include::{include-springbootfeatures}/testing/applications/data/cassandra/MyData -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-jpa]] ==== Auto-configured Data JPA Tests You can use the `@DataJpaTest` annotation to test JPA applications. By default, it scans for `@Entity` classes and configures Spring Data JPA repositories. @@ -6473,7 +6473,7 @@ include::{include-springbootfeatures}/testing/applications/data/jpa/db/MyReposit -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jdbc-test]] +[[features.testing.spring-boot-applications.autoconfigured-jdbc]] ==== Auto-configured JDBC Tests `@JdbcTest` is similar to `@DataJpaTest` but is for tests that only require a `DataSource` and do not use Spring Data JDBC. By default, it configures an in-memory embedded database and a `JdbcTemplate`. @@ -6492,11 +6492,11 @@ include::{include-springbootfeatures}/testing/applications/data/jdbc/MyTransacti ---- If you prefer your test to run against a real database, you can use the `@AutoConfigureTestDatabase` annotation in the same way as for `DataJpaTest`. -(See "<>".) +(See "<>".) -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-data-jdbc-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-jdbc]] ==== Auto-configured Data JDBC Tests `@DataJdbcTest` is similar to `@JdbcTest` but is for tests that use Spring Data JDBC repositories. By default, it configures an in-memory embedded database, a `JdbcTemplate`, and Spring Data JDBC repositories. @@ -6507,19 +6507,19 @@ TIP: A list of the auto-configurations that are enabled by `@DataJdbcTest` can b 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. -If that is not what you want, you can disable transaction management for a test or for the whole test class as <>. +If that is not what you want, you can disable transaction management for a test or for the whole test class as <>. If you prefer your test to run against a real database, you can use the `@AutoConfigureTestDatabase` annotation in the same way as for `DataJpaTest`. -(See "<>".) +(See "<>".) -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jooq-test]] +[[features.testing.spring-boot-applications.autoconfigured-jooq]] ==== Auto-configured jOOQ Tests You can use `@JooqTest` in a similar fashion as `@JdbcTest` but for jOOQ-related tests. As jOOQ relies heavily on a Java-based schema that corresponds with the database schema, the existing `DataSource` is used. If you want to replace it with an in-memory database, you can use `@AutoConfigureTestDatabase` to override those settings. -(For more about using jOOQ with Spring Boot, see "<>", earlier in this chapter.) +(For more about using jOOQ with Spring Boot, see "<>", earlier in this chapter.) Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@JooqTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. @@ -6534,17 +6534,17 @@ include::{include-springbootfeatures}/testing/applications/jooq/MyJooqTests.java ---- JOOQ tests are transactional and roll back at the end of each test by default. -If that is not what you want, you can disable transaction management for a test or for the whole test class as <>. +If that is not what you want, you can disable transaction management for a test or for the whole test class as <>. -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-mongo-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-mongodb]] ==== Auto-configured Data MongoDB Tests You can use `@DataMongoTest` to test MongoDB applications. By default, it configures an in-memory embedded MongoDB (if available), configures a `MongoTemplate`, scans for `@Document` classes, and configures Spring Data MongoDB repositories. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataMongoTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -(For more about using MongoDB with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6565,13 +6565,13 @@ include::{include-springbootfeatures}/testing/applications/data/mongodb/db/MyDat -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-neo4j-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-neo4j]] ==== Auto-configured Data Neo4j Tests You can use `@DataNeo4jTest` to test Neo4j applications. By default, it scans for `@Node` classes, and configures Spring Data Neo4j repositories. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataNeo4jTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -(For more about using Neo4J with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6596,13 +6596,13 @@ If you are using this style, you must configure `@DataNeo4jTest` tests as descri -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-redis-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-redis]] ==== Auto-configured Data Redis Tests You can use `@DataRedisTest` to test Redis applications. By default, it scans for `@RedisHash` classes and configures Spring Data Redis repositories. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataRedisTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -(For more about using Redis with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6615,13 +6615,13 @@ include::{include-springbootfeatures}/testing/applications/data/redis/MyDataRedi -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-ldap-test]] +[[features.testing.spring-boot-applications.autoconfigured-spring-data-ldap]] ==== Auto-configured Data LDAP Tests You can use `@DataLdapTest` to test LDAP applications. By default, it configures an in-memory embedded LDAP (if available), configures an `LdapTemplate`, scans for `@Entry` classes, and configures Spring Data LDAP repositories. Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataLdapTest` annotation is used. `@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans. -(For more about using LDAP with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6642,7 +6642,7 @@ include::{include-springbootfeatures}/testing/applications/data/ldap/server/MyDa -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-client]] +[[features.testing.spring-boot-applications.autoconfigured-rest-client]] ==== Auto-configured REST Clients You can use the `@RestClientTest` annotation to test REST clients. By default, it auto-configures Jackson, GSON, and Jsonb support, configures a `RestTemplateBuilder`, and adds support for `MockRestServiceServer`. @@ -6660,7 +6660,7 @@ include::{include-springbootfeatures}/testing/applications/restclient/MyRestClie -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]] +[[features.testing.spring-boot-applications.autoconfigured-spring-restdocs]] ==== Auto-configured Spring REST Docs Tests You can use the `@AutoConfigureRestDocs` annotation to use {spring-restdocs}[Spring REST Docs] in your tests with Mock MVC, REST Assured, or WebTestClient. It removes the need for the JUnit extension in Spring REST Docs. @@ -6670,7 +6670,7 @@ It can also be used to configure the host, scheme, and port that appears in any -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-mock-mvc]] +[[features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-mock-mvc]] ===== Auto-configured Spring REST Docs Tests with Mock MVC `@AutoConfigureRestDocs` customizes the `MockMvc` bean to use Spring REST Docs when testing Servlet-based web applications. You can inject it by using `@Autowired` and use it in your tests as you normally would when using Mock MVC and Spring REST Docs, as shown in the following example: @@ -6698,7 +6698,7 @@ include::{include-springbootfeatures}/testing/applications/restdocs/mvc/ResultHa -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-web-test-client]] +[[features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-web-test-client]] ===== Auto-configured Spring REST Docs Tests with WebTestClient `@AutoConfigureRestDocs` can also be used with `WebTestClient` when testing reactive web applications. You can inject it by using `@Autowired` and use it in your tests as you normally would when using `@WebFluxTest` and Spring REST Docs, as shown in the following example: @@ -6717,7 +6717,7 @@ include::{include-springbootfeatures}/testing/restdocs/webclient/AdvancedRestDoc -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-rest-assured]] +[[features.testing.spring-boot-applications.autoconfigured-spring-restdocs.with-rest-assured]] ===== Auto-configured Spring REST Docs Tests with REST Assured `@AutoConfigureRestDocs` makes a `RequestSpecification` bean, preconfigured to use Spring REST Docs, available to your tests. You can inject it by using `@Autowired` and use it in your tests as you normally would when using REST Assured and Spring REST Docs, as shown in the following example: @@ -6736,11 +6736,11 @@ include::{include-springbootfeatures}/testing/restdocs/restassured/AdvancedRestD -[[boot-features-testing-spring-boot-applications-testing-autoconfigured-webservices]] +[[features.testing.spring-boot-applications.autoconfigured-webservices]] ==== Auto-configured Spring Web Services Tests You can use `@WebServiceClientTest` to test applications that use call web services using the Spring Web Services project. By default, it configures a mock `WebServiceServer` bean and automatically customizes your `WebServiceTemplateBuilder`. -(For more about using Web Services with Spring Boot, see "<>", earlier in this chapter.) +(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 <>. @@ -6754,7 +6754,7 @@ include::{include-springbootfeatures}/testing/applications/webservices/MyWebServ -[[boot-features-testing-spring-boot-applications-testing-auto-configured-additional-auto-config]] +[[features.testing.spring-boot-applications.additional-autoconfiguration-and-slicing]] ==== Additional Auto-configuration and Slicing Each slice provides one or more `@AutoConfigure...` annotations that namely defines the auto-configurations that should be included as part of a slice. Additional auto-configurations can be added on a test-by-test basis by creating a custom `@AutoConfigure...` annotation or by adding `@ImportAutoConfiguration` to the test as shown in the following example: @@ -6777,9 +6777,9 @@ TIP: A slice or `@AutoConfigure...` annotation can be customized this way as lon -[[boot-features-testing-spring-boot-applications-testing-user-configuration]] +[[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. @@ -6835,7 +6835,7 @@ Alternatively, you can specify a source for your test, which disables the behavi -[[boot-features-testing-spring-boot-applications-with-spock]] +[[features.testing.spring-boot-applications.spock]] ==== Using Spock to Test Spring Boot Applications If you wish to use Spock to test a Spring Boot application, you should add a dependency on Spock's `spock-spring` module to your application's build. `spock-spring` integrates Spring's test framework into Spock. @@ -6846,13 +6846,13 @@ Either use the latest Spock 2.0 milestone or release that is compatible with Gro -[[boot-features-test-utilities]] +[[features.testing.utilities]] === Test Utilities A few test utility classes that are generally useful when testing your application are packaged as part of `spring-boot`. -[[boot-features-configfileapplicationcontextinitializer-test-utility]] +[[features.testing.utilities.config-data-application-context-initializer]] ==== ConfigDataApplicationContextInitializer `ConfigDataApplicationContextInitializer` is an `ApplicationContextInitializer` that you can apply to your tests to load Spring Boot `application.properties` files. You can use it when you do not need the full set of features provided by `@SpringBootTest`, as shown in the following example: @@ -6868,7 +6868,7 @@ For `@Value` support, you need to either additionally configure a `PropertySourc -[[boot-features-test-property-values]] +[[features.testing.utilities.test-property-values]] ==== TestPropertyValues `TestPropertyValues` lets you quickly add properties to a `ConfigurableEnvironment` or `ConfigurableApplicationContext`. You can call it with `key=value` strings, as follows: @@ -6880,7 +6880,7 @@ include::{include-springbootfeatures}/testing/utils/MyEnvironmentTests.java[tag= -[[boot-features-output-capture-test-utility]] +[[features.testing.utilities.output-capture]] ==== OutputCapture `OutputCapture` is a JUnit `Extension` that you can use to capture `System.out` and `System.err` output. To use add `@ExtendWith(OutputCaptureExtension.class)` and inject `CapturedOutput` as an argument to your test class constructor or test method as follows: @@ -6892,13 +6892,13 @@ include::{include-springbootfeatures}/testing/OutputCaptureTests.java[] -[[boot-features-rest-templates-test-utility]] +[[features.testing.utilities.test-rest-template]] ==== TestRestTemplate `TestRestTemplate` is a convenience alternative to Spring's `RestTemplate` that is useful in integration tests. You can get a vanilla template or one that sends Basic HTTP authentication (with a username and password). In either case, the template behaves in a test-friendly way by not throwing exceptions on server-side errors. -TIP: Spring Framework 5.0 provides a new `WebTestClient` that works for <> and both <>. +TIP: Spring Framework 5.0 provides a new `WebTestClient` that works for <> and both <>. It provides a fluent API for assertions, unlike `TestRestTemplate`. It is recommended, but not mandatory, to use the Apache HTTP Client (version 4.3.2 or better). @@ -6926,7 +6926,7 @@ include::{include-springbootfeatures}/testing/webclient/SampleWebClientTests.jav -[[boot-features-websockets]] +[[features.websockets]] == WebSockets Spring Boot provides WebSockets auto-configuration for embedded Tomcat, Jetty, and Undertow. If you deploy a war file to a standalone container, Spring Boot assumes that the container is responsible for the configuration of its WebSocket support. @@ -6945,7 +6945,7 @@ WebSocket support is also available for {spring-framework-docs}/web-reactive.htm -[[boot-features-webservices]] +[[features.webservices]] == Web Services Spring Boot provides Web Services auto-configuration so that all you must do is define your `Endpoints`. @@ -6964,7 +6964,7 @@ To do so, configure their location, as shown in the following example: -[[boot-features-webservices-template]] +[[features.webservices.template]] === Calling Web Services with WebServiceTemplate If you need to call remote Web services from your application, you can use the {spring-webservices-docs}#client-web-service-template[`WebServiceTemplate`] class. Since `WebServiceTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `WebServiceTemplate` bean. @@ -6987,19 +6987,19 @@ include::{include-springbootfeatures}/webservices/MyWebServiceTemplateConfigurat -[[boot-features-developing-auto-configuration]] +[[features.developing-auto-configuration]] == Creating Your Own Auto-configuration If you work in a company that develops shared libraries, or if you work on an open-source or commercial library, you might want to develop your own auto-configuration. Auto-configuration classes can be bundled in external jars and still be picked-up by Spring Boot. Auto-configuration can be associated to a "`starter`" that provides the auto-configuration code as well as the typical libraries that you would use with it. -We first cover what you need to know to build your own auto-configuration and then we move on to the <>. +We first cover what you need to know to build your own auto-configuration and then we move on to the <>. TIP: A https://github.com/snicoll-demos/spring-boot-master-auto-configuration[demo project] is available to showcase how you can create a starter step-by-step. -[[boot-features-understanding-auto-configured-beans]] +[[features.developing-auto-configuration.understanding-auto-configured-beans]] === Understanding Auto-configured Beans Under the hood, auto-configuration is implemented with standard `@Configuration` classes. Additional `@Conditional` annotations are used to constrain when the auto-configuration should apply. @@ -7010,7 +7010,7 @@ You can browse the source code of {spring-boot-autoconfigure-module-code}[`sprin -[[boot-features-locating-auto-configuration-candidates]] +[[features.developing-auto-configuration.locating-auto-configuration-candidates]] === Locating Auto-configuration Candidates Spring Boot checks for the presence of a `META-INF/spring.factories` file within your published jar. The file should list your configuration classes under the `EnableAutoConfiguration` key, as shown in the following example: @@ -7038,7 +7038,7 @@ The order in which those beans are subsequently created is unaffected and is det -[[boot-features-condition-annotations]] +[[features.developing-auto-configuration.condition-annotations]] === Condition Annotations You almost always want to include one or more `@Conditional` annotations on your auto-configuration class. The `@ConditionalOnMissingBean` annotation is one common example that is used to allow developers to override auto-configuration if they are not happy with your defaults. @@ -7046,16 +7046,16 @@ The `@ConditionalOnMissingBean` annotation is one common example that is used to Spring Boot includes a number of `@Conditional` annotations that you can reuse in your own code by annotating `@Configuration` classes or individual `@Bean` methods. These annotations include: -* <> -* <> -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> +* <> +* <> -[[boot-features-class-conditions]] +[[features.developing-auto-configuration.condition-annotations.class-conditions]] ==== Class Conditions The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations let `@Configuration` classes be included based on the presence or absence of specific classes. Due to the fact that annotation metadata is parsed by using https://asm.ow2.io/[ASM], you can use the `value` attribute to refer to the real class, even though that class might not actually appear on the running application classpath. @@ -7074,7 +7074,7 @@ TIP: If you use `@ConditionalOnClass` or `@ConditionalOnMissingClass` as a part -[[boot-features-bean-conditions]] +[[features.developing-auto-configuration.condition-annotations.bean-conditions]] ==== Bean Conditions The `@ConditionalOnBean` and `@ConditionalOnMissingBean` annotations let a bean be included based on the presence or absence of specific beans. You can use the `value` attribute to specify beans by type or `name` to specify beans by name. @@ -7101,7 +7101,7 @@ Providing as much type information as possible in `@Bean` methods is particularl -[[boot-features-property-conditions]] +[[features.developing-auto-configuration.condition-annotations.property-conditions]] ==== Property Conditions The `@ConditionalOnProperty` annotation lets configuration be included based on a Spring Environment property. Use the `prefix` and `name` attributes to specify the property that should be checked. @@ -7110,14 +7110,14 @@ You can also create more advanced checks by using the `havingValue` and `matchIf -[[boot-features-resource-conditions]] +[[features.developing-auto-configuration.condition-annotations.resource-conditions]] ==== Resource Conditions The `@ConditionalOnResource` annotation lets configuration be included only when a specific resource is present. Resources can be specified by using the usual Spring conventions, as shown in the following example: `file:/home/user/test.dat`. -[[boot-features-web-application-conditions]] +[[features.developing-auto-configuration.condition-annotations.web-application-conditions]] ==== Web Application Conditions The `@ConditionalOnWebApplication` and `@ConditionalOnNotWebApplication` annotations let configuration be included depending on whether the application is a "`web application`". A servlet-based web application is any application that uses a Spring `WebApplicationContext`, defines a `session` scope, or has a `ConfigurableWebEnvironment`. @@ -7128,13 +7128,13 @@ This condition will not match for applications that are run with an embedded ser -[[boot-features-spel-conditions]] +[[features.developing-auto-configuration.condition-annotations.spel-conditions]] ==== SpEL Expression Conditions The `@ConditionalOnExpression` annotation lets configuration be included based on the result of a {spring-framework-docs}/core.html#expressions[SpEL expression]. -[[boot-features-test-autoconfig]] +[[features.developing-auto-configuration.testing]] === Testing your Auto-configuration An auto-configuration can be affected by many factors: user configuration (`@Bean` definition and `Environment` customization), condition evaluation (presence of a particular library), and others. Concretely, each test should create a well defined `ApplicationContext` that represents a combination of those customizations. @@ -7177,13 +7177,13 @@ include::{include-springbootfeatures}/testing/ConditionEvaluationReportTests.jav -[[boot-features-test-autoconfig-simulating-web-context]] +[[features.developing-auto-configuration.testing.simulating-a-web-context]] ==== Simulating a Web Context If you need to test an auto-configuration that only operates in a Servlet or Reactive web application context, use the `WebApplicationContextRunner` or `ReactiveWebApplicationContextRunner` respectively. -[[boot-features-test-autoconfig-overriding-classpath]] +[[features.developing-auto-configuration.testing.overriding-classpath]] ==== Overriding the Classpath It is also possible to test what happens when a particular class and/or package is not present at runtime. Spring Boot ships with a `FilteredClassLoader` that can easily be used by the runner. @@ -7196,7 +7196,7 @@ include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests. -[[boot-features-custom-starter]] +[[features.developing-auto-configuration.custom-starter]] === Creating Your Own Starter A typical Spring Boot starter contains code to auto-configure and customize the infrastructure of a given technology, let's call that "acme". To make it easily extensible, a number of configuration keys in a dedicated namespace can be exposed to the environment. @@ -7217,7 +7217,7 @@ If the auto-configuration is relatively straightforward and does not have option -[[boot-features-custom-starter-naming]] +[[features.developing-auto-configuration.custom-starter.naming]] ==== Naming You should make sure to provide a proper namespace for your starter. Do not start your module names with `spring-boot`, even if you use a different Maven `groupId`. @@ -7229,7 +7229,7 @@ If you only have one module that combines the two, name it `acme-spring-boot-sta -[[boot-features-custom-starter-configuration-keys]] +[[features.developing-auto-configuration.custom-starter.configuration-keys]] ==== Configuration keys If your starter provides configuration keys, use a unique namespace for them. In particular, do not include your keys in the namespaces that Spring Boot uses (such as `server`, `management`, `spring`, and so on). @@ -7253,13 +7253,13 @@ 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. -[[boot-features-custom-starter-module-autoconfigure]] +[[features.developing-auto-configuration.custom-starter.autoconfigure-module]] ==== The "`autoconfigure`" Module The `autoconfigure` module contains everything that is necessary to get started with the library. It may also contain configuration key definitions (such as `@ConfigurationProperties`) and any callback interface that can be used to further customize how the components are initialized. @@ -7324,7 +7324,7 @@ With Gradle 4.6 and later, the dependency should be declared in the `annotationP -[[boot-features-custom-starter-module-starter]] +[[features.developing-auto-configuration.custom-starter.starter-module]] ==== Starter Module The starter is really an empty jar. Its only purpose is to provide the necessary dependencies to work with the library. @@ -7340,7 +7340,7 @@ If a project is created with only your custom starter, Spring Boot's core featur -[[boot-features-kotlin]] +[[features.kotlin]] == Kotlin support https://kotlinlang.org[Kotlin] is a statically-typed language targeting the JVM (and other platforms) which allows writing concise and elegant code while providing {kotlin-docs}java-interop.html[interoperability] with existing libraries written in Java. @@ -7353,7 +7353,7 @@ Feel free to join the #spring channel of https://slack.kotlinlang.org/[Kotlin Sl -[[boot-features-kotlin-requirements]] +[[features.kotlin.requirements]] === Requirements Spring Boot supports Kotlin 1.3.x. To use Kotlin, `org.jetbrains.kotlin:kotlin-stdlib` and `org.jetbrains.kotlin:kotlin-reflect` must be present on the classpath. @@ -7369,7 +7369,7 @@ TIP: These dependencies and plugins are provided by default if one bootstraps a -[[boot-features-kotlin-null-safety]] +[[features.kotlin.null-safety]] === Null-safety One of Kotlin's key features is {kotlin-docs}null-safety.html[null-safety]. It deals with `null` values at compile time rather than deferring the problem to runtime and encountering a `NullPointerException`. @@ -7390,12 +7390,12 @@ Also be aware that Spring Boot's own API is {github-issues}10712[not yet annotat -[[boot-features-kotlin-api]] +[[features.kotlin.api]] === Kotlin API -[[boot-features-kotlin-api-runapplication]] +[[features.kotlin.api.?run-application]] ==== runApplication Spring Boot provides an idiomatic way to run an application with `runApplication(*args)` as shown in the following example: @@ -7424,7 +7424,7 @@ It also allows customization of the application as shown in the following exampl -[[boot-features-kotlin-api-extensions]] +[[features.kotlin.api.extensions]] ==== Extensions Kotlin {kotlin-docs}extensions.html[extensions] provide the ability to extend existing classes with additional functionality. The Spring Boot Kotlin API makes use of these extensions to add new Kotlin specific conveniences to existing APIs. @@ -7434,7 +7434,7 @@ Among other things, the extensions make it possible to take advantage of Kotlin -[[boot-features-kotlin-dependency-management]] +[[features.kotlin.dependency-management]] === Dependency management In order to avoid mixing different versions of Kotlin dependencies on the classpath, Spring Boot imports the Kotlin BOM. @@ -7448,9 +7448,9 @@ TIP: `org.jetbrains.kotlinx:kotlinx-coroutines-reactor` dependency is provided b -[[boot-features-kotlin-configuration-properties]] +[[features.kotlin.configuration-properties]] === @ConfigurationProperties -`@ConfigurationProperties` when used in combination with <> supports classes with immutable `val` properties as shown in the following example: +`@ConfigurationProperties` when used in combination with <> supports classes with immutable `val` properties as shown in the following example: [source,kotlin,indent=0] ---- @@ -7468,28 +7468,28 @@ 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. -[[boot-features-kotlin-testing]] +[[features.kotlin.testing]] === Testing While it is possible to use JUnit 4 to test Kotlin code, JUnit 5 is provided by default and is recommended. JUnit 5 enables a test class to be instantiated once and reused for all of the class's tests. This makes it possible to use `@BeforeAll` and `@AfterAll` annotations on non-static methods, which is a good fit for Kotlin. To mock Kotlin classes, https://mockk.io/[MockK] is recommended. -If you need the `Mockk` equivalent of the Mockito specific <>, you can use https://github.com/Ninja-Squad/springmockk[SpringMockK] which provides similar `@MockkBean` and `@SpykBean` annotations. +If you need the `Mockk` equivalent of the Mockito specific <>, you can use https://github.com/Ninja-Squad/springmockk[SpringMockK] which provides similar `@MockkBean` and `@SpykBean` annotations. -[[boot-features-kotlin-resources]] +[[features.kotlin.resources]] === Resources -[[boot-features-kotlin-resources-further-reading]] +[[features.kotlin.resources.further-reading]] ==== Further reading * {kotlin-docs}[Kotlin language reference] * https://kotlinlang.slack.com/[Kotlin Slack] (with a dedicated #spring channel) @@ -7505,7 +7505,7 @@ If you need the `Mockk` equivalent of the Mockito specific <>, or by <>. +Spring Boot applications can be containerized <>, or by <>. -[[boot-features-container-images-docker]] +[[features.container-images.building.dockerfiles]] ==== Dockerfiles -While it is possible to convert a Spring Boot fat jar into a docker image with just a few lines in the Dockerfile, we will use the <> to create an optimized docker image. +While it is possible to convert a Spring Boot fat jar into a docker image with just a few lines in the Dockerfile, we will use the <> to create an optimized docker image. When you create a jar containing the layers index file, the `spring-boot-jarmode-layertools` jar will be added as a dependency to your jar. With this jar on the classpath, you can launch your application in a special mode which allows the bootstrap code to run something entirely different from your application, for example, something that extracts the layers. -CAUTION: The `layertools` mode can not be used with a <> that includes a launch script. +CAUTION: The `layertools` mode can not be used with a <> that includes a launch script. Disable launch script configuration when building a jar file that is intended to be used with `layertools`. Here’s how you can launch your jar with a `layertools` jar mode: @@ -7635,7 +7635,7 @@ You can use some combination of `unzip` and `mv` to move things to the right lay -[[boot-features-container-images-buildpacks]] +[[features.container-images.images.buildpacks]] ==== Cloud Native Buildpacks Dockerfiles are just one way to build docker images. Another way to build docker images is directly from your Maven or Gradle plugin, using buildpacks. @@ -7657,9 +7657,9 @@ Spring Boot can use that information when serving static resources, but this can -[[boot-features-whats-next]] +[[features.whats-next]] == What to Read Next 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/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc index 6c4a66e6b9..a57681dbb3 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-spring-boot.adoc @@ -1,4 +1,4 @@ -[[using-boot]] +[[using]] = Using Spring Boot include::attributes.adoc[] @@ -11,15 +11,15 @@ If you are starting out with Spring Boot, you should probably read the _<> and that can consume artifacts published to the "`Maven Central`" repository. +It is strongly recommended that you choose a build system that supports <> and that can consume artifacts published to the "`Maven Central`" repository. We would recommend that you choose Maven or Gradle. It is possible to get Spring Boot to work with other build systems (Ant, for example), but they are not particularly well supported. -[[using-boot-dependency-management]] +[[using.build-systems.dependency-management]] === Dependency Management Each release of Spring Boot provides a curated list of dependencies that it supports. In practice, you do not need to provide a version for any of these dependencies in your build configuration, as Spring Boot manages that for you. @@ -28,14 +28,14 @@ When you upgrade Spring Boot itself, these dependencies are upgraded as well in NOTE: You can still specify a version and override Spring Boot's recommendations if you need to do so. The curated list contains all the Spring modules that you can use with Spring Boot as well as a refined list of third party libraries. -The list is available as a standard Bills of Materials (`spring-boot-dependencies`) that can be used with both <> and <>. +The list is available as a standard Bills of Materials (`spring-boot-dependencies`) that can be used with both <> and <>. WARNING: Each release of Spring Boot is associated with a base version of the Spring Framework. We **highly** recommend that you not specify its version. -[[using-boot-maven]] +[[using.build-systems.maven]] === Maven To learn about using Spring Boot with Maven, please refer to the documentation for Spring Boot's Maven plugin: @@ -44,7 +44,7 @@ To learn about using Spring Boot with Maven, please refer to the documentation f -[[using-boot-gradle]] +[[using.build-systems.gradle]] === Gradle To learn about using Spring Boot with Gradle, please refer to the documentation for Spring Boot's Gradle plugin: @@ -53,7 +53,7 @@ To learn about using Spring Boot with Gradle, please refer to the documentation -[[using-boot-ant]] +[[using.build-systems.ant]] === Ant It is possible to build a Spring Boot project using Apache Ant+Ivy. The `spring-boot-antlib` "`AntLib`" module is also available to help Ant create executable jars. @@ -114,11 +114,11 @@ A typical `build.xml` looks like the following example: ---- -TIP: If you do not want to use the `spring-boot-antlib` module, see the _<>_ "`How-to`" . +TIP: If you do not want to use the `spring-boot-antlib` module, see the _<>_ "`How-to`" . -[[using-boot-starter]] +[[using.build-systems.starters]] === Starters Starters are a set of convenient dependency descriptors that you can include in your application. You get a one-stop shop for all the Spring and related technologies that you need without having to hunt through sample code and copy-paste loads of dependency descriptors. @@ -133,7 +133,7 @@ This naming structure is intended to help when you need to find a starter. The Maven integration in many IDEs lets you search dependencies by name. For example, with the appropriate Eclipse or STS plugin installed, you can press `ctrl-space` in the POM editor and type "`spring-boot-starter`" for a complete list. -As explained in the "`<>`" section, third party starters should not start with `spring-boot`, as it is reserved for official Spring Boot artifacts. +As explained in the "`<>`" section, third party starters should not start with `spring-boot`, as it is reserved for official Spring Boot artifacts. Rather, a third-party starter typically starts with the name of the project. For example, a third-party starter project called `thirdpartyproject` would typically be named `thirdpartyproject-spring-boot-starter`. **** @@ -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[] @@ -153,20 +153,20 @@ Finally, Spring Boot also includes the following starters that can be used if yo .Spring Boot technical starters include::starters/technical-starters.adoc[] -To learn how to swap technical facets, please see the how-to documentation for <> and <>. +To learn how to swap technical facets, please see the how-to documentation for <> and <>. TIP: For a list of additional community contributed starters, see the {spring-boot-latest-code}/spring-boot-project/spring-boot-starters/README.adoc[README file] in the `spring-boot-starters` module on GitHub. -[[using-boot-structuring-your-code]] +[[using.structuring-your-code]] == Structuring Your Code Spring Boot does not require any specific code layout to work. However, there are some best practices that help. -[[using-boot-using-the-default-package]] +[[using.structuring-your-code.using-the-default-package]] === Using the "`default`" Package When a class does not include a `package` declaration, it is considered to be in the "`default package`". The use of the "`default package`" is generally discouraged and should be avoided. @@ -176,10 +176,10 @@ TIP: We recommend that you follow Java's recommended package naming conventions -[[using-boot-locating-the-main-class]] +[[using.structuring-your-code.locating-the-main-class]] === Locating the Main Application Class We generally recommend that you locate your main application class in a root package above other classes. -The <> is often placed on your main class, and it implicitly defines a base "`search package`" for certain items. +The <> is often placed on your main class, and it implicitly defines a base "`search package`" for certain items. For example, if you are writing a JPA application, the package of the `@SpringBootApplication` annotated class is used to search for `@Entity` items. Using a root package also allows component scan to apply only on your project. @@ -228,7 +228,7 @@ The `Application.java` file would declare the `main` method, along with the basi -[[using-boot-configuration-classes]] +[[using.configuration-classes]] == Configuration Classes Spring Boot favors Java-based configuration. Although it is possible to use `SpringApplication` with XML sources, we generally recommend that your primary source be a single `@Configuration` class. @@ -240,7 +240,7 @@ Searching for `+Enable*+` annotations can be a good starting point. -[[using-boot-importing-configuration]] +[[using.configuration-classes.importing-additional-configuration]] === Importing Additional Configuration Classes You need not put all your `@Configuration` into a single class. The `@Import` annotation can be used to import additional configuration classes. @@ -248,14 +248,14 @@ Alternatively, you can use `@ComponentScan` to automatically pick up all Spring -[[using-boot-importing-xml-configuration]] +[[using.configuration-classes.importing-xml-configuration]] === Importing XML Configuration If you absolutely must use XML based configuration, we recommend that you still start with a `@Configuration` class. You can then use an `@ImportResource` annotation to load XML configuration files. -[[using-boot-auto-configuration]] +[[using.auto-configuration]] == Auto-configuration Spring Boot auto-configuration attempts to automatically configure your Spring application based on the jar dependencies that you have added. For example, if `HSQLDB` is on your classpath, and you have not manually configured any database connection beans, then Spring Boot auto-configures an in-memory database. @@ -267,7 +267,7 @@ We generally recommend that you add one or the other to your primary `@Configura -[[using-boot-replacing-auto-configuration]] +[[using.auto-configuration.replacing]] === Gradually Replacing Auto-configuration Auto-configuration is non-invasive. At any point, you can start to define your own configuration to replace specific parts of the auto-configuration. @@ -278,7 +278,7 @@ Doing so enables debug logs for a selection of core loggers and logs a condition -[[using-boot-disabling-specific-auto-configuration]] +[[using.auto-configuration.disabling-specific]] === Disabling Specific Auto-configuration Classes If you find that specific auto-configuration classes that you do not want are being applied, you can use the exclude attribute of `@SpringBootApplication` to disable them, as shown in the following example: @@ -303,7 +303,7 @@ The actual contents of those classes, such as nested configuration classes or be -[[using-boot-spring-beans-and-dependency-injection]] +[[using.spring-beans-and-dependency-injection]] == Spring Beans and Dependency Injection You are free to use any of the standard Spring Framework techniques to define your beans and their injected dependencies. We often find that using `@ComponentScan` (to find your beans) and using `@Autowired` (to do constructor injection) works well. @@ -357,13 +357,13 @@ TIP: Notice how using constructor injection lets the `riskAssessor` field be mar -[[using-boot-using-springbootapplication-annotation]] +[[using.using-the-springbootapplication-annotation]] == Using the @SpringBootApplication Annotation Many Spring Boot developers like their apps to use auto-configuration, component scan and be able to define extra configuration on their "application class". A single `@SpringBootApplication` annotation can be used to enable those three features, that is: -* `@EnableAutoConfiguration`: enable <> -* `@ComponentScan`: enable `@Component` scan on the package where the application is located (see <>) +* `@EnableAutoConfiguration`: enable <> +* `@ComponentScan`: enable `@Component` scan on the package where the application is located (see <>) * `@Configuration`: allow to register extra beans in the context or import additional configuration classes [source,java,pending-extract=true,indent=0] @@ -416,7 +416,7 @@ In this example, `Application` is just like any other Spring Boot application ex -[[using-boot-running-your-application]] +[[using.running-your-application]] == Running Your Application One of the biggest advantages of packaging your application as a jar and using an embedded HTTP server is that you can run your application as you would any other. The sample applies to debugging Spring Boot applications. @@ -427,7 +427,7 @@ If you choose to package your application as a war file, you should refer to you -[[using-boot-running-from-an-ide]] +[[using.running-your-application.from-an-ide]] === Running from an IDE You can run a Spring Boot application from your IDE as a Java application. However, you first need to import your project. @@ -444,7 +444,7 @@ STS users can use the `Relaunch` button rather than the `Run` button to ensure t -[[using-boot-running-as-a-packaged-application]] +[[using.running-your-application.as-a-packaged-application]] === Running as a Packaged Application If you use the Spring Boot Maven or Gradle plugins to create an executable jar, you can run your application using `java -jar`, as shown in the following example: @@ -464,7 +464,7 @@ Doing so lets you attach a debugger to your packaged application, as shown in th -[[using-boot-running-with-the-maven-plugin]] +[[using.running-your-application.with-the-maven-plugin]] === Using the Maven Plugin The Spring Boot Maven plugin includes a `run` goal that can be used to quickly compile and run your application. Applications run in an exploded form, as they do in your IDE. @@ -484,7 +484,7 @@ You might also want to use the `MAVEN_OPTS` operating system environment variabl -[[using-boot-running-with-the-gradle-plugin]] +[[using.running-your-application.with-the-gradle-plugin]] === Using the Gradle Plugin The Spring Boot Gradle plugin also includes a `bootRun` task that can be used to run your application in an exploded form. The `bootRun` task is added whenever you apply the `org.springframework.boot` and `java` plugins and is shown in the following example: @@ -503,18 +503,18 @@ You might also want to use the `JAVA_OPTS` operating system environment variable -[[using-boot-hot-swapping]] +[[using.running-your-application.hot-swapping]] === Hot Swapping Since Spring Boot applications are plain Java applications, JVM hot-swapping should work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can replace. For a more complete solution, https://www.jrebel.com/products/jrebel[JRebel] can be used. The `spring-boot-devtools` module also includes support for quick application restarts. -See the <> section later in this chapter and the <> for details. +See the <> section later in this chapter and the <> for details. -[[using-boot-devtools]] +[[using.devtools]] == Developer Tools Spring Boot includes an additional set of tools that can make the application development experience a little more pleasant. The `spring-boot-devtools` module can be included in any project to provide additional development-time features. @@ -550,16 +550,16 @@ To disable devtools, exclude the dependency or set the `-Dspring.devtools.restar TIP: Flagging the dependency as optional in Maven or using the `developmentOnly` configuration in Gradle (as shown above) prevents devtools from being transitively applied to other modules that use your project. TIP: Repackaged archives do not contain devtools by default. -If you want to use a <>, you need to include it. +If you want to use a <>, you need to include it. When using the Maven plugin, set the `excludeDevtools` property to `false`. When using the Gradle plugin, {spring-boot-gradle-plugin-docs}#packaging-executable-configuring-including-development-only-dependencies[configure the task's classpath to include the `developmentOnly` configuration]. -[[using-boot-devtools-property-defaults]] +[[using.devtools.property-defaults]] === Property Defaults Several of the libraries supported by Spring Boot use caches to improve performance. -For example, <> cache compiled templates to avoid repeatedly parsing template files. +For example, <> cache compiled templates to avoid repeatedly parsing template files. Also, Spring MVC can add HTTP caching headers to responses when serving static resources. While caching is very beneficial in production, it can be counter-productive during development, preventing you from seeing the changes you just made in your application. @@ -579,12 +579,12 @@ TIP: For a complete list of the properties that are applied by the devtools, see -[[using-boot-devtools-restart]] +[[using.devtools.restart]] === Automatic Restart Applications that use `spring-boot-devtools` automatically restart whenever files on the classpath change. This can be a useful feature when working in an IDE, as it gives a very fast feedback loop for code changes. By default, any entry on the classpath that points to a directory is monitored for changes. -Note that certain resources, such as static assets and view templates, <>. +Note that certain resources, such as static assets and view templates, <>. .Triggering a restart **** @@ -600,7 +600,7 @@ NOTE: If you are restarting with Maven or Gradle using the build plugin you must If you disable forking, the isolated application classloader used by devtools will not be created and restarts will not operate properly. TIP: Automatic restart works very well when used with LiveReload. -<> for details. +<> for details. If you use JRebel, automatic restarts are disabled in favor of dynamic class reloading. Other devtools features (such as LiveReload and property overrides) can still be used. @@ -626,7 +626,7 @@ These work by rewriting classes as they are loaded to make them more amenable to -[[using-boot-devtools-restart-logging-condition-delta]] +[[using.devtools.restart.logging-condition-delta]] ==== Logging changes in condition evaluation By default, each time your application restarts, a report showing the condition evaluation delta is logged. The report shows the changes to your application's auto-configuration as you make changes such as adding or removing beans and setting configuration properties. @@ -643,11 +643,11 @@ To disable the logging of the report, set the following property: -[[using-boot-devtools-restart-exclude]] +[[using.devtools.restart.excluding-resources]] ==== Excluding Resources Certain resources do not necessarily need to trigger a restart when they are changed. For example, Thymeleaf templates can be edited in-place. -By default, changing resources in `/META-INF/maven`, `/META-INF/resources`, `/resources`, `/static`, `/public`, or `/templates` does not trigger a restart but does trigger a <>. +By default, changing resources in `/META-INF/maven`, `/META-INF/resources`, `/resources`, `/static`, `/public`, or `/templates` does not trigger a restart but does trigger a <>. If you want to customize these exclusions, you can use the configprop:spring.devtools.restart.exclude[] property. For example, to exclude only `/static` and `/public` you would set the following property: @@ -663,15 +663,15 @@ TIP: If you want to keep those defaults and _add_ additional exclusions, use the -[[using-boot-devtools-restart-additional-paths]] +[[using.devtools.restart.watching-additional-paths]] ==== Watching Additional Paths You may want your application to be restarted or reloaded when you make changes to files that are not on the classpath. To do so, use the configprop:spring.devtools.restart.additional-paths[] property to configure additional paths to watch for changes. -You can use the configprop:spring.devtools.restart.exclude[] property <> to control whether changes beneath the additional paths trigger a full restart or a <>. +You can use the configprop:spring.devtools.restart.exclude[] property <> to control whether changes beneath the additional paths trigger a full restart or a <>. -[[using-boot-devtools-restart-disable]] +[[using.devtools.restart.disable]] ==== Disabling Restart If you do not want to use the restart feature, you can disable it by using the configprop:spring.devtools.restart.enabled[] property. In most cases, you can set this property in your `application.properties` (doing so still initializes the restart classloader, but it does not watch for file changes). @@ -688,7 +688,7 @@ If you need to _completely_ disable restart support (for example, because it doe -[[using-boot-devtools-restart-triggerfile]] +[[using.devtools.restart.triggerfile]] ==== Using a Trigger File If you work with an IDE that continuously compiles changed files, you might prefer to trigger restarts only at specific times. To do so, you can use a "`trigger file`", which is a special file that must be modified when you want to actually trigger a restart check. @@ -720,7 +720,7 @@ Then your `trigger-file` property would be: Restarts will now only happen when the `src/main/resources/.reloadtrigger` is updated. -TIP: You might want to set `spring.devtools.restart.trigger-file` as a <>, so that all your projects behave in the same way. +TIP: You might want to set `spring.devtools.restart.trigger-file` as a <>, so that all your projects behave in the same way. Some IDEs have features that save you from needing to update your trigger file manually. https://spring.io/tools[Spring Tools for Eclipse] and https://www.jetbrains.com/idea/[IntelliJ IDEA (Ultimate Edition)] both have such support. @@ -729,7 +729,7 @@ For IntelliJ IDEA, you can follow the https://www.jetbrains.com/help/idea/spring -[[using-boot-devtools-customizing-classload]] +[[using.devtools.restart.customizing-the-classload]] ==== Customizing the Restart Classloader As described earlier in the <> section, restart functionality is implemented by using two classloaders. For most applications, this approach works well. @@ -760,7 +760,7 @@ You can package files inside your project, or in the libraries that the project -[[using-boot-devtools-known-restart-limitations]] +[[using.devtools.restart.limitations]] ==== Known Limitations Restart functionality does not work well with objects that are deserialized by using a standard `ObjectInputStream`. If you need to deserialize data, you may need to use Spring's `ConfigurableObjectInputStream` in combination with `Thread.currentThread().getContextClassLoader()`. @@ -770,7 +770,7 @@ If you find such a problem, you need to request a fix with the original authors. -[[using-boot-devtools-livereload]] +[[using.devtools.livereload]] === LiveReload The `spring-boot-devtools` module includes an embedded LiveReload server that can be used to trigger a browser refresh when a resource is changed. LiveReload browser extensions are freely available for Chrome, Firefox and Safari from http://livereload.com/extensions/[livereload.com]. @@ -781,11 +781,11 @@ NOTE: You can only run one LiveReload server at a time. Before starting your application, ensure that no other LiveReload servers are running. If you start multiple applications from your IDE, only the first has LiveReload support. -WARNING: To trigger LiveReload when a file changes, <> must be enabled. +WARNING: To trigger LiveReload when a file changes, <> must be enabled. -[[using-boot-devtools-globalsettings]] +[[using.devtools.globalsettings]] === Global Settings You can configure global devtools settings by adding any of the following files to the `$HOME/.config/spring-boot` directory: @@ -794,7 +794,7 @@ You can configure global devtools settings by adding any of the following files . `spring-boot-devtools.yml` Any properties added to these file apply to _all_ Spring Boot applications on your machine that use devtools. -For example, to configure restart to always use a <>, you would add the following property to your `spring-boot-devtools` file: +For example, to configure restart to always use a <>, you would add the following property to your `spring-boot-devtools` file: [source,yaml,indent=0,configprops,configblocks] ---- @@ -811,13 +811,13 @@ 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. ==== -[[configuring-file-system-watcher]] +[[using.devtools.globalsettings.configuring-file-system-watcher]] ==== Configuring File System Watcher {spring-boot-devtools-module-code}/filewatch/FileSystemWatcher.java[FileSystemWatcher] works by polling the class changes with a certain time interval, and then waiting for a predefined quiet period to make sure there are no more changes. Since Spring Boot relies entirely on the IDE to compile and copy files into the location from where Spring Boot can read them, you might find that there are times when certain changes are not reflected when devtools restarts the application. @@ -836,7 +836,7 @@ The monitored classpath directories are now polled every 2 seconds for changes, -[[using-boot-devtools-remote]] +[[using.devtools.remote-applications]] === Remote Applications The Spring Boot developer tools are not limited to local development. You can also use several features when running applications remotely. @@ -871,7 +871,7 @@ The client component must be launched manually. -[[running-remote-client-application]] +[[using.devtools.remote-applications.client]] ==== Running the Remote Client Application The remote client application is designed to be run from within your IDE. You need to run `org.springframework.boot.devtools.RemoteSpringApplication` with the same classpath as the remote project that you connect to. @@ -913,9 +913,9 @@ TIP: If you need to use a proxy to access the remote application, configure the -[[using-boot-devtools-remote-update]] +[[using.devtools.remote-applications.update]] ==== Remote Update -The remote client monitors your application classpath for changes in the same way as the <>. +The remote client monitors your application classpath for changes in the same way as the <>. Any updated resource is pushed to the remote application and (_if required_) triggers a restart. This can be helpful if you iterate on a feature that uses a cloud service that you do not have locally. Generally, remote updates and restarts are much quicker than a full rebuild and deploy cycle. @@ -927,24 +927,24 @@ The next batch can’t be sent to the application, since the server is restartin This is typically manifested by a warning in the `RemoteSpringApplication` logs about failing to upload some of the classes, and a consequent retry. But it may also lead to application code inconsistency and failure to restart after the first batch of changes is uploaded. If you observe such problems constantly, try increasing the `spring.devtools.restart.poll-interval` and `spring.devtools.restart.quiet-period` parameters to the values that fit your development environment. -See the <> section for configuring these properties. +See the <> section for configuring these properties. NOTE: Files are only monitored when the remote client is running. If you change a file before starting the remote client, it is not pushed to the remote server. -[[using-boot-packaging-for-production]] +[[using.packaging-for-production]] == Packaging Your Application for Production 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. -[[using-boot-whats-next]] +[[using.whats-next]] == What to Read Next You should now understand how you can use Spring Boot and some best practices that you should follow. -You can now go on to learn about specific _<>_ in depth, or you could skip ahead and read about the "`<>`" aspects of Spring Boot. +You can now go on to learn about specific _<>_ in depth, or you could skip ahead and read about the "`<>`" aspects of Spring Boot.