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 <<spring-boot-features.adoc#boot-features-external-config-conversion, the properties conversion section>>.
TIP: Spring Boot provides various conversion mechanism with advanced value formatting, make sure to review <<spring-boot-features.adoc#features.external-config.typesafe-configuration-properties.conversion, the properties conversion section>>.
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
@ -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 <<configuration-metadata-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
However, it is possible to <<configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> 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
The `name` attribute of each hint refers to the `name` of a property.
In the <<configuration-metadata-format,initial example shown earlier>>, we provide five values for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`, and `create-drop`.
In the <<configuration-metadata.format,initial example shown earlier>>, 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 <<configuration-metadata-additional-metadata,the manual metadata of the module>>:
In order to offer additional content assistance for the keys, you could add the following JSON to <<configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
[source,json,indent=0]
----
@ -380,7 +380,7 @@ If your IDE supports it, this is by far the most effective approach to auto-comp
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
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.
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, <<configuration-metadata-additional-metadata,manual metadata>> should be provided.
For cases where the default value could not be detected, <<configuration-metadata.annotation-processor.adding-additional-metadata,manual metadata>> should be provided.
@ -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 <<configuration-metadata-additional-metadata,the manual metadata of the module>>:
In order to document default values for properties in the class above, you could add the following content to <<configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
[source,json,indent=0]
----
@ -851,7 +851,7 @@ NOTE: Only the `name` of the property is required to document additional metadat
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.
@ -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.
@ -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:
@ -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:
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 "`<<using-spring-boot.adoc#using-boot-build-systems>>`" from the "`<<using-spring-boot.adoc#using-boot>>`" section first.
If you are just getting started, you might want to read "`<<using-spring-boot.adoc#using.build-systems>>`" from the "`<<using-spring-boot.adoc#using>>`" 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 <directory containing spring-boot-antlib-{spring-boot-version}.jar>
----
TIP: The "`Using Spring Boot`" section includes a more complete example of <<using-spring-boot.adoc#using-boot-ant, using Apache Ant with `spring-boot-antlib`>>.
TIP: The "`Using Spring Boot`" section includes a more complete example of <<using-spring-boot.adoc#using.build-systems.ant, using Apache Ant with `spring-boot-antlib`>>.
[[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>>
* <<spring-boot-ant-findmainclass>>
* <<build-tool-plugins.antlib.tasks.exejar>>
* <<build-tool-plugins.antlib.findmainclass>>
[[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:
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 "`<<appendix-executable-jar-format.adoc#executable-jar, executable jar format>>`" section in the appendix for details).
@ -193,7 +193,7 @@ If you need to, you may use this library directly.
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.
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 <<appendix-executable-jar-format#executable-jar,the appendix>>.
@ -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 <<spring-boot-features.adoc#boot-features-container-images-docker,creating separate layers>> for your dependencies and application classes and resources (which normally change more frequently).
More efficient container images can also be created by <<spring-boot-features.adoc#features.container-images.building.dockerfiles,creating separate layers>> 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 <<getting-started.adoc#getting-started-first-application, application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
In this section, we look at what it takes to get the <<getting-started.adoc#getting-started.first-application, application that we developed>> 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
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 <<spring-boot-features.adoc#boot-features-application-availability,manage the state of your application>> and export it with <<production-ready-features.adoc#production-ready-kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
Spring Boot helps you to <<spring-boot-features.adoc#features.spring-application.application-availability,manage the state of your application>> and export it with <<production-ready-features.adoc#actuator.endpoints.kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
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 <<spring-boot-features#boot-features-graceful-shutdown,graceful shutdown>> 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 <<spring-boot-features#features.graceful-shutdown,graceful shutdown>> 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`".
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 <<deployment-service,registered with `init.d` or `systemd`>>.
A fully executable jar can be executed like any other executable binary or it can be <<deployment.installing.nix-services,registered with `init.d` or `systemd`>>.
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
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 <<deployment-install, fully executable jar>>, 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 <<deployment.installing, fully executable jar>>, 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:
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.
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment-script-customization-conf-file, config file>>.
@ -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 <<deployment-initd-service-securing,the guidelines for securing an init.d service>>.
To learn about securing this file appropriately, see <<deployment.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
[[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.
* *Tutorial:* <<getting-started.adoc#getting-started-first-application, Part 1>> | <<getting-started.adoc#getting-started-first-application-code, Part 2>>
* *Running your example:* <<getting-started.adoc#getting-started-first-application-run, Part 1>> | <<getting-started.adoc#getting-started-first-application-executable-jar, Part 2>>
* *Tutorial:* <<getting-started.adoc#getting-started.first-application, Part 1>> | <<getting-started.adoc#getting-started.first-application.code, Part 2>>
* *Running your example:* <<getting-started.adoc#getting-started.first-application.run, Part 1>> | <<getting-started.adoc#getting-started.first-application.executable-jar, Part 2>>
[[boot-documentation-workingwith]]
[[documentation.using]]
== Working with Spring Boot
Ready to actually start using Spring Boot? <<using-spring-boot.adoc#using-boot, We have you covered>>:
Ready to actually start using Spring Boot? <<using-spring-boot.adoc#using, We have you covered>>:
When you are ready to push your Spring Boot application to production, we have <<production-ready-features.adoc#production-ready, some tricks>> that you might like:
When you are ready to push your Spring Boot application to production, we have <<production-ready-features.adoc#actuator, some tricks>> that you might like:
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 <<getting-started-installing-the-cli, Spring Boot CLI>> (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 <<getting-started.installing.cli, Spring Boot CLI>> (Command Line Interface) first.
Otherwise, read on for "`classic`" installation instructions.
=== 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 <<using-spring-boot.adoc#using-boot-starter,"`Starters`">>.
Spring Boot also provides an optional <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> to create executable jars.
Typically, your Maven POM file inherits from the `spring-boot-starter-parent` project and declares dependencies to one or more <<using-spring-boot.adoc#using.build-systems.starters,"`Starters`">>.
Spring Boot also provides an optional <<build-tool-plugins.adoc#build-tool-plugins.maven, Maven plugin>> 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 <<using-spring-boot.adoc#using-boot-starter, "`Starters`">>.
Spring Boot provides a useful <<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle plugin>> that can be used to simplify dependency declarations and to create executable jars.
Typically, your project declares dependencies to one or more <<using-spring-boot.adoc#using.build-systems.starters, "`Starters`">>.
Spring Boot provides a useful <<build-tool-plugins.adoc#build-tool-plugins.gradle, Gradle plugin>> 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
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:
=== 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 <<getting-started-manual-cli-installation, standard instructions>>, remembering to update your `PATH` environment variable to remove any older references.
If you manually installed the CLI, follow the <<getting-started.installing.cli.manual-installation, standard instructions>>, 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 <<getting-started-first-application-code,start coding right away>>.
Doing so generates a new project structure so that you can <<getting-started.first-application.code,start coding right away>>.
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.
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 <<using-spring-boot.adoc#using-boot-dependency-management,`dependency-management`>> section so that you can omit `version` tags for "`blessed`" dependencies.
It also provides a <<using-spring-boot.adoc#using.build-systems.dependency-management,`dependency-management`>> 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.
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 "`<<howto.adoc#howto, How-to>>`" reference documentation.
Otherwise, the next logical step is to read _<<using-spring-boot.adoc#using-boot>>_.
If you are really impatient, you could also jump ahead and read about _<<spring-boot-features.adoc#boot-features, Spring Boot features>>_.
Otherwise, the next logical step is to read _<<using-spring-boot.adoc#using>>_.
If you are really impatient, you could also jump ahead and read about _<<spring-boot-features.adoc#features, Spring Boot features>>_.
@ -10,11 +10,11 @@ The reference documentation consists of the following sections:
[horizontal]
<<legal.adoc#legal,Legal>> :: Legal information.
<<documentation-overview.adoc#boot-documentation,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
<<documentation-overview.adoc#documentation,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing Spring Boot, System Requirements, Servlet Containers, Installing Spring Boot, Developing Your First Spring Boot Application
<<using-spring-boot.adoc#using-boot,Using Spring Boot>> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, DevTools, and more.
<<spring-boot-features.adoc#boot-features,Spring Boot Features>> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more.
<<production-ready-features.adoc#production-ready,Spring Boot Actuator>> :: Monitoring, Metrics, Auditing, and more.
<<using-spring-boot.adoc#using,Using Spring Boot>> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, DevTools, and more.
<<spring-boot-features.adoc#features,Spring Boot Features>> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more.
<<production-ready-features.adoc#actuator,Spring Boot Actuator>> :: Monitoring, Metrics, Auditing, and more.
<<deployment.adoc#deployment,Deploying Spring Boot Applications>> :: Deploying to the Cloud, Installing as a Unix application.
<<spring-boot-cli.adoc#cli,Spring Boot CLI>> :: Installing the CLI, Using the CLI, Configuring the CLI, and more.
<<build-tool-plugins.adoc#build-tool-plugins,Build Tool Plugins>> :: Maven Plugin, Gradle Plugin, Antlib, and more.
@ -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 _<<getting-started.adoc#getting-started-installing-the-cli>>_ in the "`Getting started`" section for comprehensive installation instructions.
See _<<getting-started.adoc#getting-started.installing.cli>>_ 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.
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
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`.
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].
@ -11,15 +11,15 @@ If you are starting out with Spring Boot, you should probably read the _<<gettin
[[using-boot-build-systems]]
[[using.build-systems]]
== Build Systems
It is strongly recommended that you choose a build system that supports <<using-boot-dependency-management,_dependency management_>> and that can consume artifacts published to the "`Maven Central`" repository.
It is strongly recommended that you choose a build system that supports <<using.build-systems.dependency-management,_dependency management_>> 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 <<using-boot-maven,Maven>> and <<using-boot-gradle,Gradle>>.
The list is available as a standard Bills of Materials (`spring-boot-dependencies`) that can be used with both <<using.build-systems.maven,Maven>> and <<using.build-systems.gradle,Gradle>>.
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:
</project>
----
TIP: If you do not want to use the `spring-boot-antlib` module, see the _<<howto.adoc#howto-build-an-executable-archive-with-ant>>_ "`How-to`" .
TIP: If you do not want to use the `spring-boot-antlib` module, see the _<<howto.adoc#howto.build.build-an-executable-archive-with-ant-without-using-spring-boot-antlib>>_ "`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 "`<<spring-boot-features#boot-features-custom-starter,Creating Your Own Starter>>`" section, third party starters should not start with `spring-boot`, as it is reserved for official Spring Boot artifacts.
As explained in the "`<<spring-boot-features#features.developing-auto-configuration.custom-starter,Creating Your Own Starter>>`" 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 _<<production-ready-features.adoc#production-ready, production ready>>_ features:
In addition to the application starters, the following starters can be used to add _<<production-ready-features.adoc#actuator, production ready>>_ 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 <<howto.adoc#howto-use-another-web-server, swapping web server>> and <<howto.adoc#howto-configure-log4j-for-logging, logging system>>.
To learn how to swap technical facets, please see the how-to documentation for <<howto.adoc#howto.webserver.use-another, swapping web server>> and <<howto.adoc#howto.logging.log4j, logging system>>.
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.
We generally recommend that you locate your main application class in a root package above other classes.
The <<using-boot-using-springbootapplication-annotation, `@SpringBootApplication` annotation>> is often placed on your main class, and it implicitly defines a base "`search package`" for certain items.
The <<using.using-the-springbootapplication-annotation, `@SpringBootApplication` annotation>> 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.
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
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
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:
* `@ComponentScan`: enable `@Component` scan on the package where the application is located (see <<using-boot-structuring-your-code,the best practices>>)
* `@ComponentScan`: enable `@Component` scan on the package where the application is located (see <<using.structuring-your-code,the best practices>>)
* `@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
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
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 <<using-boot-devtools>> section later in this chapter and the <<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> for details.
See the <<using.devtools>> section later in this chapter and the <<howto.adoc#howto.hotswapping, Hot swapping "`How-to`">> 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 <<using-boot-devtools-remote,certain remote devtools feature>>, you need to include it.
If you want to use a <<using.devtools.remote-applications,certain remote devtools feature>>, 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, <<spring-boot-features#boot-features-spring-mvc-template-engines,template engines>> cache compiled templates to avoid repeatedly parsing template files.
For example, <<spring-boot-features#features.developing-web-applications.spring-mvc.template-engines,template engines>> 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, <<using-boot-devtools-restart-exclude, do not need to restart the application>>.
Note that certain resources, such as static assets and view templates, <<using.devtools.restart.excluding-resources, do not need to restart the application>>.
.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.
<<using-boot-devtools-livereload,See the LiveReload section>> for details.
<<using.devtools.livereload,See the LiveReload section>> 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
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 <<using-boot-devtools-livereload, live reload>>.
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 <<using.devtools.livereload, live reload>>.
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
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 <<using-boot-devtools-restart-exclude, described earlier>> to control whether changes beneath the additional paths trigger a full restart or a <<using-boot-devtools-livereload, live reload>>.
You can use the configprop:spring.devtools.restart.exclude[] property <<using.devtools.restart.excluding-resources, described earlier>> to control whether changes beneath the additional paths trigger a full restart or a <<using.devtools.livereload, live reload>>.
[[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 <<using-boot-devtools-globalsettings,global setting>>, so that all your projects behave in the same way.
TIP: You might want to set `spring.devtools.restart.trigger-file` as a <<using.devtools.globalsettings,global setting>>, 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
As described earlier in the <<using-spring-boot-restart-vs-reload>> 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, <<using-boot-devtools-restart>> must be enabled.
WARNING: To trigger LiveReload when a file changes, <<using.devtools.restart>> 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 <<using-boot-devtools-restart-triggerfile, trigger file>>, you would add the following property to your `spring-boot-devtools` file:
For example, to configure restart to always use a <<using.devtools.restart.triggerfile, trigger file>>, 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 <<spring-boot-features.adoc#boot-features-external-config-files-profile-specific, profile-specific configuration files>>.
Any profiles activated in `.spring-boot-devtools.properties` will not affect the loading of <<spring-boot-features.adoc#features.external-config.files.profile-specific, profile-specific configuration files>>.
Profile specific filenames (of the form `spring-boot-devtools-<profile>.properties`) and `spring.config.activate.on-profile` documents in both YAML and Properties files are not supported.
{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 <<using-boot-devtools-restart,local restart>>.
The remote client monitors your application classpath for changes in the same way as the <<using.devtools.restart,local restart>>.
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 <<configuring-file-system-watcher>> section for configuring these properties.
See the <<using.devtools.globalsettings.configuring-file-system-watcher>> 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 _<<production-ready-features.adoc#production-ready>>_ for details.
See _<<production-ready-features.adoc#actuator>>_ 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 _<<spring-boot-features#boot-features, Spring Boot features>>_ in depth, or you could skip ahead and read about the "`<<production-ready-features#production-ready, production ready>>`" aspects of Spring Boot.
You can now go on to learn about specific _<<spring-boot-features#features, Spring Boot features>>_ in depth, or you could skip ahead and read about the "`<<production-ready-features#actuator, production ready>>`" aspects of Spring Boot.
Phillip Webb
4 years ago